#!/usr/bin/env tsx
import { execFileSync } from "node:child_process";

function pm(args: string[]): string {
  const stdout = execFileSync("pm", args, { encoding: "utf8" });
  process.stdout.write(stdout);
  return stdout;
}

const query = process.env.PM_AGENT_QUERY ?? "failing CI";
const taskId = process.env.PM_TASK_ID;

pm(["context", "--json", "--depth", "full"]);
pm(["search", "--mode", "hybrid", query, "--json"]);

if (taskId) {
  pm(["start-task", taskId, "--json"]);
  pm(["test", taskId, "--add", "--command", process.env.PM_TEST_COMMAND ?? "npm test", "--description", "CI verification command"]);
  pm(["test", taskId, "--run", "--json"]);
  pm(["docs", taskId, "--add", "path=.github/workflows/ci.yml,scope=project,note=CI workflow under investigation"]);
  pm(["comments", taskId, "Agent CI pass completed. Linked evidence and test command are attached."]);
} else {
  pm([
    "create",
    "--type",
    "Task",
    "--title",
    "Investigate CI failure",
    "--description",
    "Created by agent CI workflow after context and hybrid search.",
    "--priority",
    "1",
    "--tags",
    "agent,ci",
  ]);
}

/**
 * ai-sprint-planner — AI-powered sprint planning with pm-cli
 *
 * Scores open backlog items, groups related work, assigns to team members
 * by capacity, creates a Sprint Milestone, and updates items with sprint
 * metadata — all from a single command.
 *
 * Usage:
 *   npx tsx main.ts --sprint "Sprint 12" --capacity 80 --team alice,bob,carol
 */

import { execSync } from "node:child_process";
import { parseArgs } from "node:util";

// ---------------------------------------------------------------------------
// CLI args
// ---------------------------------------------------------------------------

const { values: args } = parseArgs({
  options: {
    sprint: { type: "string" },
    capacity: { type: "string", default: "80" },
    team: { type: "string", default: "" },
    "dry-run": { type: "boolean", default: false },
  },
});

const SPRINT_NAME = args.sprint ?? `Sprint ${new Date().toISOString().slice(0, 7)}`;
const CAPACITY_HOURS = parseInt(args.capacity ?? "80", 10);
const TEAM = (args.team ?? "").split(",").map((s) => s.trim()).filter(Boolean);
const DRY_RUN = args["dry-run"] ?? false;

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

/** A pm item as returned by `pm list --json`. */
interface PmItem {
  id: string;
  title: string;
  status: "open" | "in_progress" | "blocked" | "draft" | "closed" | "canceled";
  type: string;
  priority?: number;
  estimated_minutes?: number;
  parent?: string;
  assignee?: string;
  created_at: string;
  tags?: string[];
}

/** A scored backlog item ready for sprint assignment. */
interface ScoredItem extends PmItem {
  score: number;
  estimatedHours: number;
  ageDays: number;
}

/** Sprint assignment: item + chosen team member. */
interface Assignment {
  item: ScoredItem;
  assignee: string;
}

// ---------------------------------------------------------------------------
// pm-cli helpers
// ---------------------------------------------------------------------------

/** Run a pm-cli command and return stdout as a string. */
function pm(cmd: string): string {
  return execSync(`pm ${cmd}`, { encoding: "utf-8" }).trim();
}

/** Run a pm-cli command returning parsed JSON. */
function pmJson<T>(cmd: string): T {
  return JSON.parse(pm(`${cmd} --json`));
}

/** Fetch open (and in-progress) items, excluding blocked and archived types. */
function fetchBacklog(): PmItem[] {
  const all = pmJson<PmItem[]>("list-open");
  // Include in_progress items that aren't yet in a sprint
  const active = pmJson<PmItem[]>("list-in-progress");
  return [...all, ...active].filter(
    (item) =>
      !["Milestone", "Epic", "Meeting", "Event", "Reminder"].includes(item.type)
  );
}

// ---------------------------------------------------------------------------
// Scoring
// ---------------------------------------------------------------------------

const NOW_MS = Date.now();

/**
 * Score a backlog item 0–100.
 *
 * Priority factor  (40 pts) — priority 0 scores 40, priority 4 scores 0
 * Age factor       (25 pts) — older items bubble up; capped at 90 days
 * Estimate factor  (20 pts) — items with estimates score higher
 * Parent factor    (15 pts) — prefer continuing in-progress parent work
 */
function scoreItem(item: PmItem, inProgressParents: Set<string>): number {
  // Priority: 0 = highest → 40 pts; 4 = lowest → 0 pts
  const priorityScore = ((4 - (item.priority ?? 2)) / 4) * 40;

  // Age: days since creation, capped at 90
  const ageMs = NOW_MS - new Date(item.created_at).getTime();
  const ageDays = Math.min(ageMs / (1000 * 60 * 60 * 24), 90);
  const ageScore = (ageDays / 90) * 25;

  // Estimate: reward items that have been sized
  const estimateScore = item.estimated_minutes != null ? 20 : 0;

  // Parent continuity: reward items whose parent Epic/Feature is already active
  const parentScore = item.parent && inProgressParents.has(item.parent) ? 15 : 0;

  return Math.round(priorityScore + ageScore + estimateScore + parentScore);
}

function buildScoredItems(items: PmItem[], inProgressParents: Set<string>): ScoredItem[] {
  return items
    .filter((item) => item.status !== "blocked")
    .map((item) => ({
      ...item,
      score: scoreItem(item, inProgressParents),
      estimatedHours: (item.estimated_minutes ?? 0) / 60,
      ageDays: Math.floor(
        (NOW_MS - new Date(item.created_at).getTime()) / (1000 * 60 * 60 * 24)
      ),
    }))
    .sort((a, b) => b.score - a.score);
}

// ---------------------------------------------------------------------------
// Capacity assignment
// ---------------------------------------------------------------------------

/**
 * Greedily assign scored items to team members by capacity.
 * Each member gets a equal share of the total capacity.
 * Items without estimates get a default 2h slot.
 */
function assignItems(
  scored: ScoredItem[],
  team: string[],
  totalHours: number
): { assignments: Assignment[]; unscheduled: ScoredItem[] } {
  const perMemberCapacity = totalHours / Math.max(team.length, 1);
  const remaining = new Map<string, number>(
    team.map((member) => [member, perMemberCapacity])
  );

  const assignments: Assignment[] = [];
  const unscheduled: ScoredItem[] = [];

  let memberIdx = 0;

  for (const item of scored) {
    const hours = item.estimatedHours > 0 ? item.estimatedHours : 2;

    // Round-robin: try each member in turn
    let assigned = false;
    for (let attempt = 0; attempt < team.length; attempt++) {
      const member = team[(memberIdx + attempt) % team.length];
      const cap = remaining.get(member) ?? 0;
      if (cap >= hours) {
        remaining.set(member, cap - hours);
        assignments.push({ item, assignee: member });
        memberIdx = (memberIdx + 1) % team.length;
        assigned = true;
        break;
      }
    }

    if (!assigned) {
      unscheduled.push(item);
    }
  }

  return { assignments, unscheduled };
}

// ---------------------------------------------------------------------------
// Sprint creation
// ---------------------------------------------------------------------------

/** Calculate sprint end date: 2 weeks from today. */
function sprintDeadline(): string {
  const d = new Date();
  d.setDate(d.getDate() + 14);
  return d.toISOString().slice(0, 10);
}

/** Create the sprint Milestone and return its ID. */
function createSprintMilestone(sprintName: string, assignments: Assignment[]): string {
  const totalHours = assignments.reduce((sum, a) => sum + a.item.estimatedHours, 0);
  const itemCount = assignments.length;
  const deadline = sprintDeadline();

  const cmd = [
    "create",
    `--type Milestone`,
    `--title "${sprintName}"`,
    `--description "Sprint goal: ${itemCount} items, ~${Math.round(totalHours)}h of work"`,
    `--deadline "${deadline}"`,
    `--priority 1`,
    "--json",
  ].join(" ");

  if (DRY_RUN) {
    console.log(`[dry-run] pm ${cmd}`);
    return "MILESTONE-DRY";
  }

  const result = JSON.parse(pm(cmd));
  return result.id as string;
}

/** Update each assigned item with sprint name and assignee. */
function applyAssignments(assignments: Assignment[], sprintName: string): void {
  for (const { item, assignee } of assignments) {
    const cmd = [
      `update ${item.id}`,
      `--sprint "${sprintName}"`,
      assignee ? `--assignee "${assignee}"` : "",
    ]
      .filter(Boolean)
      .join(" ");

    if (DRY_RUN) {
      console.log(`[dry-run] pm ${cmd}`);
    } else {
      pm(cmd);
    }
  }
}

// ---------------------------------------------------------------------------
// Report
// ---------------------------------------------------------------------------

function printReport(
  assignments: Assignment[],
  unscheduled: ScoredItem[],
  milestoneId: string
): void {
  const totalHours = assignments.reduce((sum, a) => sum + a.item.estimatedHours, 0);
  const usedCapacity = Math.round(totalHours * 10) / 10;

  console.log();
  console.log(`${SPRINT_NAME}  —  capacity: ${CAPACITY_HOURS}h  —  team: ${TEAM.join(", ") || "(solo)"}`);
  console.log();

  const col = (s: string, w: number) => s.slice(0, w).padEnd(w);

  console.log(
    `  ${col("Score", 6)} ${col("ID", 10)} ${col("Title", 38)} ${col("Est", 5)} ${col("Assignee", 12)}`
  );
  console.log(
    `  ${"─".repeat(6)} ${"─".repeat(10)} ${"─".repeat(38)} ${"─".repeat(5)} ${"─".repeat(12)}`
  );

  for (const { item, assignee } of assignments) {
    const est =
      item.estimated_minutes != null
        ? `${Math.round(item.estimatedHours * 10) / 10}h`
        : "  ?h";
    console.log(
      `  ${col(String(item.score), 6)} ${col(item.id, 10)} ${col(item.title, 38)} ${col(est, 5)} ${col(assignee, 12)}`
    );
  }

  console.log();
  console.log(
    `Total: ${usedCapacity}h / ${CAPACITY_HOURS}h  (${Math.max(0, CAPACITY_HOURS - usedCapacity)}h remaining)`
  );
  console.log(`Unscheduled: ${unscheduled.length} items`);
  console.log();
  if (!DRY_RUN) {
    console.log(`Sprint Milestone: ${milestoneId}`);
    console.log(`Items updated with sprint="${SPRINT_NAME}".`);
  }
  console.log();
}

// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------

async function main(): Promise<void> {
  console.log(`Planning ${SPRINT_NAME} (capacity: ${CAPACITY_HOURS}h)…`);

  // 1. Fetch open items
  const backlog = fetchBacklog();
  console.log(`Fetched ${backlog.length} open items.`);

  // 2. Find in-progress parent IDs for continuity scoring
  const inProgress = pmJson<PmItem[]>("list-in-progress");
  const inProgressParents = new Set(inProgress.map((i) => i.id));

  // 3. Score and sort
  const scored = buildScoredItems(backlog, inProgressParents);

  // 4. Assign to team by capacity
  const { assignments, unscheduled } = assignItems(scored, TEAM, CAPACITY_HOURS);

  // 5. Create sprint Milestone
  const milestoneId = createSprintMilestone(SPRINT_NAME, assignments);

  // 6. Apply assignee + sprint tags to items
  applyAssignments(assignments, SPRINT_NAME);

  // 7. Print report
  printReport(assignments, unscheduled, milestoneId);

  if (DRY_RUN) {
    console.log("(dry-run: no changes written)");
  }
}

main().catch((err) => {
  console.error(err instanceof Error ? err.message : String(err));
  process.exitCode = 1;
});

#!/usr/bin/env tsx
import { execFileSync } from "node:child_process";

function pm(args: string[]): void {
  console.log(`pm ${args.map((arg) => (arg.includes(" ") ? JSON.stringify(arg) : arg)).join(" ")}`);
  execFileSync("pm", args, { stdio: "inherit" });
}

const incidentId = process.env.PM_INCIDENT_ID ?? "APP-20";
const blockedFeatureId = process.env.PM_BLOCKED_FEATURE_ID ?? "APP-15";

pm([
  "create",
  "--title",
  "CRITICAL: CSV export corrupts data when field contains a comma",
  "--type",
  "Issue",
  "--priority",
  "0",
  "--severity",
  "critical",
  "--reporter",
  "customer-success",
  "--repro-steps",
  "Create a record with a comma, export CSV, then open it in a spreadsheet.",
  "--expected-result",
  "Comma-containing fields are quoted and data remains aligned.",
  "--actual-result",
  "Field splits across columns and corrupts subsequent data.",
  "--affected-version",
  "v1.3",
  "--environment",
  "production",
  "--description",
  "100% reproducible. Three paying customers affected.",
]);

pm(["start-task", incidentId]);
pm(["comments", incidentId, "TRIAGE T+0: P0 confirmed. Export deployments halted while root cause is investigated."]);
pm(["notes", incidentId, "--add", "Likely affected file: src/export/csv.ts. Validate RFC 4180 quoting edge cases."]);
pm(["update", blockedFeatureId, "--status", "blocked", "--blocked-by", incidentId]);
pm(["comments", blockedFeatureId, `Blocked on ${incidentId}. No export changes should ship until the P0 is resolved.`]);
pm(["comments", incidentId, "T+15min: Root cause found. CSV writer called without forced quoting. Tests in progress."]);
pm(["learnings", incidentId, "--add", "Every export change requires CSV edge-case tests for comma, quotes, newline, empty, and unicode fields."]);
pm(["close-task", incidentId, "Resolved: restored CSV quoting, added edge-case tests, validated staging and production exports."]);
pm(["update", blockedFeatureId, "--status", "open"]);

/**
 * code-health-reporter — Aggregate pm health, validation, and duplicate-scan signals
 * into a single color-coded terminal report with an optional webhook post.
 *
 * Runs:
 *   pm health --json
 *   pm validate --json
 *   pm dedupe-audit --json (when available)
 *
 * Then aggregates results into a single health score summary, prints a
 * color-coded terminal report, and optionally POSTs to a webhook URL.
 *
 * Usage:
 *   npx tsx main.ts
 *   HEALTH_WEBHOOK_URL=https://hooks.example.com/... npx tsx main.ts
 *   npx tsx main.ts --webhook https://hooks.example.com/...
 */

import { execSync } from "node:child_process";
import { parseArgs } from "node:util";

// ---------------------------------------------------------------------------
// CLI args
// ---------------------------------------------------------------------------

const { values: args } = parseArgs({
  options: {
    webhook: { type: "string" },
    "no-color": { type: "boolean", default: false },
  },
});

const WEBHOOK_URL =
  args.webhook ?? process.env.HEALTH_WEBHOOK_URL ?? "";
const NO_COLOR = args["no-color"] ?? false;

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

/** Output shape of `pm health --json` */
interface HealthReport {
  score?: number;           // 0–100 overall health score
  issues?: HealthIssue[];
  summary?: string;
  checks?: HealthCheck[];
}

interface HealthIssue {
  id?: string;
  level: "error" | "warning" | "info";
  message: string;
  item_id?: string;
}

interface HealthCheck {
  name: string;
  passed: boolean;
  message?: string;
}

/** Output shape of `pm validate --json` */
interface ValidateReport {
  valid?: boolean;
  errors?: ValidationError[];
  warnings?: ValidationWarning[];
}

interface ValidationError {
  item_id?: string;
  field?: string;
  message: string;
}

interface ValidationWarning {
  item_id?: string;
  field?: string;
  message: string;
}

/** Output shape of `pm dedupe-audit --json` when that optional command is available. */
interface DedupeReport {
  duplicates?: DuplicateGroup[];
  total_items?: number;
  checked?: number;
  duplicate_count?: number;
}

interface DuplicateGroup {
  ids: string[];
  titles: string[];
  similarity?: number;
  reason?: string;
}

/** Aggregated health score with breakdown. */
interface AggregatedReport {
  timestamp: string;
  overallScore: number;
  grade: "A" | "B" | "C" | "D" | "F";
  health: { raw: HealthReport; score: number; issueCount: number };
  validation: { raw: ValidateReport; score: number; errorCount: number; warningCount: number };
  dedupe: { raw: DedupeReport; score: number; duplicateCount: number };
  summary: string;
}

// ---------------------------------------------------------------------------
// pm-cli helpers
// ---------------------------------------------------------------------------

/** Run a pm command and return raw output. Returns null on non-zero exit. */
function pmRaw(args: string[]): string | null {
  try {
    return execSync(["pm", ...args].join(" "), {
      encoding: "utf-8",
      stdio: ["pipe", "pipe", "pipe"],
    }).trim();
  } catch (err: unknown) {
    // pm may exit non-zero but still write JSON to stdout
    if (err && typeof err === "object" && "stdout" in err) {
      const stdout = (err as { stdout: string }).stdout;
      if (typeof stdout === "string" && stdout.trim().startsWith("{")) {
        return stdout.trim();
      }
    }
    return null;
  }
}

function pmJson<T>(args: string[]): T | null {
  const out = pmRaw(args);
  if (!out) return null;
  try {
    return JSON.parse(out) as T;
  } catch {
    return null;
  }
}

// ---------------------------------------------------------------------------
// Score calculation helpers
// ---------------------------------------------------------------------------

function calcHealthScore(report: HealthReport | null): { score: number; issueCount: number } {
  if (!report) return { score: 50, issueCount: 0 }; // unknown

  // If the report provides its own score, trust it
  if (typeof report.score === "number") {
    const errorCount = (report.issues ?? []).filter((i) => i.level === "error").length;
    return { score: report.score, issueCount: errorCount };
  }

  const issues = report.issues ?? [];
  const checks = report.checks ?? [];
  const errors = issues.filter((i) => i.level === "error").length;
  const warnings = issues.filter((i) => i.level === "warning").length;

  // Score: start at 100, deduct per issue
  let score = 100;
  score -= errors * 15;
  score -= warnings * 5;

  // Factor in check results
  if (checks.length > 0) {
    const failedChecks = checks.filter((c) => !c.passed).length;
    score -= failedChecks * 10;
  }

  return { score: Math.max(0, Math.min(100, score)), issueCount: errors };
}

function calcValidationScore(
  report: ValidateReport | null
): { score: number; errorCount: number; warningCount: number } {
  if (!report) return { score: 50, errorCount: 0, warningCount: 0 };

  const errors = report.errors?.length ?? 0;
  const warnings = report.warnings?.length ?? 0;
  let score = 100;
  score -= errors * 20;
  score -= warnings * 5;

  return {
    score: Math.max(0, Math.min(100, score)),
    errorCount: errors,
    warningCount: warnings,
  };
}

function calcDedupeScore(
  report: DedupeReport | null
): { score: number; duplicateCount: number } {
  if (!report) return { score: 50, duplicateCount: 0 };

  const duplicates = report.duplicates?.length ?? 0;
  const total = report.total_items ?? report.checked ?? 1;

  // Score based on duplicate rate
  const dupRate = duplicates / Math.max(total, 1);
  const score = Math.max(0, Math.round((1 - dupRate * 3) * 100)); // 3x penalty

  return { score: Math.min(100, score), duplicateCount: duplicates };
}

function scoreToGrade(score: number): "A" | "B" | "C" | "D" | "F" {
  if (score >= 90) return "A";
  if (score >= 75) return "B";
  if (score >= 60) return "C";
  if (score >= 45) return "D";
  return "F";
}

// ---------------------------------------------------------------------------
// Aggregate
// ---------------------------------------------------------------------------

function aggregate(
  healthRaw: HealthReport | null,
  validateRaw: ValidateReport | null,
  dedupeRaw: DedupeReport | null
): AggregatedReport {
  const health = {
    raw: healthRaw ?? {},
    ...calcHealthScore(healthRaw),
  };
  const validation = {
    raw: validateRaw ?? {},
    ...calcValidationScore(validateRaw),
  };
  const dedupe = {
    raw: dedupeRaw ?? {},
    ...calcDedupeScore(dedupeRaw),
  };

  // Weighted average: health 40%, validation 40%, dedupe 20%
  const overallScore = Math.round(
    health.score * 0.4 + validation.score * 0.4 + dedupe.score * 0.2
  );

  const grade = scoreToGrade(overallScore);

  const parts: string[] = [];
  if (health.issueCount > 0)
    parts.push(`${health.issueCount} health issue(s)`);
  if (validation.errorCount > 0)
    parts.push(`${validation.errorCount} validation error(s)`);
  if (validation.warningCount > 0)
    parts.push(`${validation.warningCount} validation warning(s)`);
  if (dedupe.duplicateCount > 0)
    parts.push(`${dedupe.duplicateCount} duplicate group(s)`);

  const summary =
    parts.length === 0
      ? "All checks passed. Project data is clean."
      : `Found: ${parts.join(", ")}.`;

  return {
    timestamp: new Date().toISOString(),
    overallScore,
    grade,
    health,
    validation,
    dedupe,
    summary,
  };
}

// ---------------------------------------------------------------------------
// Terminal colors
// ---------------------------------------------------------------------------

function c(code: string): string {
  return NO_COLOR ? "" : code;
}

const RESET = c("\x1b[0m");
const BOLD = c("\x1b[1m");
const DIM = c("\x1b[2m");
const RED = c("\x1b[31m");
const GREEN = c("\x1b[32m");
const YELLOW = c("\x1b[33m");
const CYAN = c("\x1b[36m");
const MAGENTA = c("\x1b[35m");
const BG_GREEN = c("\x1b[42m");
const BG_RED = c("\x1b[41m");
const BG_YELLOW = c("\x1b[43m");

function scoreColor(score: number): string {
  if (score >= 80) return GREEN;
  if (score >= 60) return YELLOW;
  return RED;
}

function gradeBlock(grade: string, score: number): string {
  if (score >= 80) return `${BG_GREEN}${BOLD} ${grade} ${RESET}`;
  if (score >= 60) return `${BG_YELLOW}${BOLD} ${grade} ${RESET}`;
  return `${BG_RED}${BOLD} ${grade} ${RESET}`;
}

function bar(score: number, width = 24): string {
  const filled = Math.round((score / 100) * width);
  const empty = width - filled;
  const col = scoreColor(score);
  return `${col}${"█".repeat(filled)}${RESET}${DIM}${"░".repeat(empty)}${RESET} ${scoreColor(score)}${score}${RESET}`;
}

// ---------------------------------------------------------------------------
// Terminal report
// ---------------------------------------------------------------------------

function printReport(r: AggregatedReport): void {
  console.log();
  console.log(
    `${BOLD}Code Health Reporter${RESET}  ${DIM}${r.timestamp}${RESET}`
  );
  console.log("─".repeat(60));
  console.log();

  // Overall score block
  console.log(`${BOLD}Overall Health Score${RESET}`);
  console.log(`  ${gradeBlock(r.grade, r.overallScore)}  ${bar(r.overallScore)}`);
  console.log(`  ${DIM}${r.summary}${RESET}`);
  console.log();

  // Section: pm health
  console.log(`${BOLD}pm health${RESET}  ${scoreColor(r.health.score)}${r.health.score}/100${RESET}`);
  if (r.health.raw.checks && r.health.raw.checks.length > 0) {
    for (const chk of r.health.raw.checks) {
      const icon = chk.passed ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
      console.log(`  ${icon}  ${chk.name}${chk.message ? ` — ${DIM}${chk.message}${RESET}` : ""}`);
    }
  } else if (r.health.raw.issues && r.health.raw.issues.length > 0) {
    for (const issue of r.health.raw.issues.slice(0, 10)) {
      const col =
        issue.level === "error"
          ? RED
          : issue.level === "warning"
          ? YELLOW
          : CYAN;
      const prefix = issue.item_id ? `${DIM}${issue.item_id}${RESET} ` : "";
      console.log(`  ${col}[${issue.level}]${RESET} ${prefix}${issue.message}`);
    }
    if ((r.health.raw.issues?.length ?? 0) > 10) {
      console.log(
        `  ${DIM}… and ${r.health.raw.issues!.length - 10} more issue(s)${RESET}`
      );
    }
  } else if (r.health.raw.summary) {
    console.log(`  ${DIM}${r.health.raw.summary}${RESET}`);
  } else {
    console.log(`  ${GREEN}No issues detected.${RESET}`);
  }
  console.log();

  // Section: pm validate
  console.log(
    `${BOLD}pm validate${RESET}  ${scoreColor(r.validation.score)}${r.validation.score}/100${RESET}`
  );
  const vErrors = r.validation.raw.errors ?? [];
  const vWarnings = r.validation.raw.warnings ?? [];
  if (vErrors.length === 0 && vWarnings.length === 0) {
    const valid = r.validation.raw.valid !== false;
    console.log(
      `  ${valid ? GREEN + "✓" + RESET + " Valid" : RED + "✗" + RESET + " Invalid"} — no errors or warnings`
    );
  } else {
    for (const err of vErrors.slice(0, 10)) {
      const loc = err.item_id
        ? `${DIM}${err.item_id}${err.field ? `.${err.field}` : ""}${RESET} `
        : "";
      console.log(`  ${RED}[error]${RESET}   ${loc}${err.message}`);
    }
    if (vErrors.length > 10)
      console.log(`  ${DIM}… and ${vErrors.length - 10} more error(s)${RESET}`);
    for (const warn of vWarnings.slice(0, 5)) {
      const loc = warn.item_id
        ? `${DIM}${warn.item_id}${warn.field ? `.${warn.field}` : ""}${RESET} `
        : "";
      console.log(`  ${YELLOW}[warning]${RESET} ${loc}${warn.message}`);
    }
    if (vWarnings.length > 5)
      console.log(`  ${DIM}… and ${vWarnings.length - 5} more warning(s)${RESET}`);
  }
  console.log();

  // Section: optional duplicate scan
  console.log(
    `${BOLD}duplicate scan${RESET}  ${scoreColor(r.dedupe.score)}${r.dedupe.score}/100${RESET}`
  );
  const dupes = r.dedupe.raw.duplicates ?? [];
  if (dupes.length === 0) {
    console.log(`  ${GREEN}✓ No duplicate items found.${RESET}`);
  } else {
    console.log(
      `  ${YELLOW}${dupes.length} duplicate group(s) found:${RESET}`
    );
    for (const group of dupes.slice(0, 5)) {
      const titles = group.titles ?? group.ids;
      const sim = group.similarity != null ? ` (${Math.round(group.similarity * 100)}% similar)` : "";
      console.log(
        `  ${MAGENTA}•${RESET} [${group.ids.join(", ")}]${sim}`
      );
      if (titles.length > 0 && titles !== group.ids) {
        console.log(`    ${DIM}${titles[0]}${RESET}`);
      }
    }
    if (dupes.length > 5)
      console.log(`  ${DIM}… and ${dupes.length - 5} more group(s)${RESET}`);
  }
  console.log();

  // Score breakdown table
  console.log(`${BOLD}Score Breakdown${RESET}`);
  const rows: [string, number, string][] = [
    ["pm health  (40%)", r.health.score, bar(r.health.score, 16)],
    ["pm validate (40%)", r.validation.score, bar(r.validation.score, 16)],
    ["duplicate scan (20%)", r.dedupe.score, bar(r.dedupe.score, 16)],
    ["Overall", r.overallScore, bar(r.overallScore, 16)],
  ];
  for (const [label, , barStr] of rows) {
    const isBold = label === "Overall";
    console.log(
      `  ${isBold ? BOLD : ""}${label.padEnd(20)}${RESET}  ${barStr}`
    );
  }
  console.log();
}

// ---------------------------------------------------------------------------
// Webhook
// ---------------------------------------------------------------------------

interface WebhookPayload {
  timestamp: string;
  overallScore: number;
  grade: string;
  summary: string;
  sections: {
    health: number;
    validation: number;
    dedupe: number;
  };
  issues: {
    healthIssues: number;
    validationErrors: number;
    validationWarnings: number;
    duplicateGroups: number;
  };
}

async function postWebhook(r: AggregatedReport, url: string): Promise<void> {
  const payload: WebhookPayload = {
    timestamp: r.timestamp,
    overallScore: r.overallScore,
    grade: r.grade,
    summary: r.summary,
    sections: {
      health: r.health.score,
      validation: r.validation.score,
      dedupe: r.dedupe.score,
    },
    issues: {
      healthIssues: r.health.issueCount,
      validationErrors: r.validation.errorCount,
      validationWarnings: r.validation.warningCount,
      duplicateGroups: r.dedupe.duplicateCount,
    },
  };

  console.log(`Posting health report to webhook…`);
  const res = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });

  if (!res.ok) {
    const text = await res.text();
    throw new Error(`Webhook error ${res.status}: ${text}`);
  }

  console.log(`  ${GREEN}✓${RESET} Webhook delivered (HTTP ${res.status}).`);
}

// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------

async function main(): Promise<void> {
  console.log("Running pm health checks…");

  process.stdout.write("  pm health       … ");
  const healthRaw = pmJson<HealthReport>(["health", "--json"]);
  console.log(healthRaw ? "done" : `${YELLOW}not available${RESET}`);

  process.stdout.write("  pm validate     … ");
  const validateRaw = pmJson<ValidateReport>(["validate", "--json"]);
  console.log(validateRaw ? "done" : `${YELLOW}not available${RESET}`);

  process.stdout.write("  duplicate scan  … ");
  const dedupeRaw = pmJson<DedupeReport>(["dedupe-audit", "--json"]);
  console.log(dedupeRaw ? "done" : `${YELLOW}not available${RESET}`);

  const report = aggregate(healthRaw, validateRaw, dedupeRaw);
  printReport(report);

  if (WEBHOOK_URL) {
    await postWebhook(report, WEBHOOK_URL);
  }

  // Exit with non-zero if grade is D or F
  if (report.grade === "D" || report.grade === "F") {
    process.exitCode = 1;
  }
}

main().catch((err) => {
  console.error(err instanceof Error ? err.message : String(err));
  process.exitCode = 1;
});

import {
  defineExtension,
  type ExtensionApi,
  type CommandHandlerContext,
  type ImportExportContext,
} from "@unbrained/pm-cli/sdk";

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

/** A GitHub label object returned by the REST API. */
interface GithubLabel {
  id: number;
  name: string;
  color: string;
  description: string | null;
}

/** A GitHub user object (author/assignee). */
interface GithubUser {
  login: string;
  id: number;
  avatar_url: string;
  html_url: string;
}

/** A GitHub issue object from the REST API (simplified to fields we use). */
interface GithubIssue {
  number: number;
  title: string;
  body: string | null;
  state: "open" | "closed";
  html_url: string;
  labels: GithubLabel[];
  user: GithubUser | null;
  created_at: string;
  updated_at: string;
  /** Present only on pull requests — used to filter PRs out of the issue list. */
  pull_request?: unknown;
}

/** Options for the fetchIssues helper. */
interface FetchIssuesOptions {
  owner: string;
  repo: string;
  state: string;
  label: string | null;
  token: string;
}

/** Shape of a pm item returned by ghIssueToPmItem. */
interface PmItemShape {
  idSuffix: string;
  title: string;
  body: string;
  status: "open" | "closed";
  priority: "high" | "medium" | "low";
  tags: string[];
  meta: {
    gh_number: number;
    gh_url: string;
    gh_author: string | null;
    gh_created_at: string;
    gh_updated_at: string;
  };
}

/** Config object expected by the importer. */
interface ImporterConfig {
  owner: string;
  repo: string;
  state?: string;
  label?: string | null;
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/** Resolve the GitHub token from the environment. */
function getToken(): string {
  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
  if (!token) {
    throw new Error(
      "No GitHub token found. Set GH_TOKEN or GITHUB_TOKEN in your environment.\n" +
        "Get a token at https://github.com/settings/tokens (needs repo or public_repo scope)."
    );
  }
  return token;
}

/**
 * Fetch all issues from the GitHub REST API, handling pagination.
 * Pull requests are filtered out — the issues endpoint returns both.
 */
async function fetchIssues({
  owner,
  repo,
  state,
  label,
  token,
}: FetchIssuesOptions): Promise<GithubIssue[]> {
  const issues: GithubIssue[] = [];
  let page = 1;
  const perPage = 100;

  while (true) {
    const url = new URL(
      `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/issues`
    );
    url.searchParams.set("state", state);
    url.searchParams.set("per_page", String(perPage));
    url.searchParams.set("page", String(page));
    if (label) {
      url.searchParams.set("labels", label);
    }

    const response = await fetch(url.toString(), {
      headers: {
        Authorization: `Bearer ${token}`,
        Accept: "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28",
        "User-Agent": "pm-github/0.1.0",
      },
    });

    if (!response.ok) {
      const body = await response.text();
      throw new Error(
        `GitHub API error ${response.status} for ${owner}/${repo}: ${body}`
      );
    }

    const data: GithubIssue[] = await response.json();

    // The issues endpoint also returns pull requests; filter them out.
    const realIssues = data.filter((item) => !item.pull_request);
    issues.push(...realIssues);

    if (data.length < perPage) {
      // Last page reached.
      break;
    }
    page++;
  }

  return issues;
}

/** Map a GitHub issue object to a pm item shape. */
function ghIssueToPmItem(ghIssue: GithubIssue): PmItemShape {
  const labelNames = (ghIssue.labels ?? []).map((l) => l.name);

  // Infer priority from labels.
  let priority: "high" | "medium" | "low" = "medium";
  for (const labelName of labelNames) {
    const lower = labelName.toLowerCase();
    if (
      lower.includes("priority: high") ||
      lower === "high" ||
      lower === "urgent"
    ) {
      priority = "high";
      break;
    }
    if (lower.includes("priority: low") || lower === "low") {
      priority = "low";
    }
  }

  // Truncate long issue bodies.
  const MAX_BODY = 500;
  const rawBody = ghIssue.body ?? "";
  const body =
    rawBody.length > MAX_BODY
      ? rawBody.slice(0, MAX_BODY) + "\n\n…(truncated, see full issue)"
      : rawBody;

  // Tags: always include "github" and "gh-issue", plus all label names.
  const tags = ["github", "gh-issue", ...labelNames];

  return {
    // Stable ID suffix for deduplication — pm-cli will upsert on this key.
    idSuffix: `gh-issue-${ghIssue.number}`,
    title: ghIssue.title,
    body,
    status: ghIssue.state === "closed" ? "closed" : "open",
    priority,
    tags,
    meta: {
      gh_number: ghIssue.number,
      gh_url: ghIssue.html_url,
      gh_author: ghIssue.user?.login ?? null,
      gh_created_at: ghIssue.created_at,
      gh_updated_at: ghIssue.updated_at,
    },
  };
}

// ---------------------------------------------------------------------------
// Extension definition
// ---------------------------------------------------------------------------

export default defineExtension({
  name: "pm-github",
  version: "0.1.0",

  activate(api: ExtensionApi) {
    // -----------------------------------------------------------------------
    // commands capability — registers `pm gh-import`
    // -----------------------------------------------------------------------
    api.registerCommand({
      name: "gh-import",
      description: "Import GitHub Issues as pm items",
      intent: "fetch and upsert GitHub issues into the pm item store",
      examples: [
        "pm gh-import --owner myorg --repo myrepo",
        "pm gh-import --owner myorg --repo myrepo --state all --label bug",
      ],
      flags: [
        {
          long: "--owner",
          value_name: "org",
          description: "GitHub org or user name (required)",
          required: true,
        },
        {
          long: "--repo",
          value_name: "name",
          description: "Repository name (required)",
          required: true,
        },
        {
          long: "--state",
          value_name: "state",
          description: "Issue state to import: open | closed | all (default: open)",
        },
        {
          long: "--label",
          value_name: "label",
          description: "Filter by label name (optional)",
        },
      ],

      async run(ctx: CommandHandlerContext) {
        const owner = ctx.options["owner"] as string;
        const repo = ctx.options["repo"] as string;
        const state = (ctx.options["state"] as string | undefined) ?? "open";
        const label = (ctx.options["label"] as string | undefined) ?? null;

        console.error(`Connecting to GitHub API for ${owner}/${repo}...`);

        const token = getToken();

        let ghIssues: GithubIssue[];
        try {
          ghIssues = await fetchIssues({ owner, repo, state, label, token });
        } catch (err) {
          console.error((err as Error).message);
          process.exitCode = 1;
          return;
        }

        if (ghIssues.length === 0) {
          console.error(
            `No issues found for ${owner}/${repo} (state=${state}${label ? `, label=${label}` : ""}).`
          );
          return;
        }

        const items = ghIssues.map(ghIssueToPmItem);
        return { owner, repo, state, label, count: items.length, items };
      },
    });

    // -----------------------------------------------------------------------
    // importers capability — registers this extension as a named importer so
    // other tools and extensions can invoke it programmatically.
    // -----------------------------------------------------------------------
    api.registerImporter("gh-issues", async (ctx: ImportExportContext) => {
      const config = ctx.options;
      const { owner, repo, state = "open", label = null } =
        config as unknown as ImporterConfig;

      if (!owner || !repo) {
        throw new Error(
          "gh-issues importer requires config.owner and config.repo"
        );
      }

      const token = getToken();
      const ghIssues = await fetchIssues({ owner, repo, state, label, token });
      const items = ghIssues.map(ghIssueToPmItem);

      return { count: items.length, items };
    });
  },
});

/**
 * github-sync-workflow — GitHub Issues ↔ pm-cli bi-directional sync
 *
 * Pull direction: import GitHub Issues as pm items.
 * Push direction: reflect pm status changes back to GitHub as labels/comments.
 *
 * Usage:
 *   npx tsx main.ts pull --owner myorg --repo myrepo
 *   npx tsx main.ts push --owner myorg --repo myrepo
 *   npx tsx main.ts sync --owner myorg --repo myrepo
 */

import { execSync } from "node:child_process";
import { parseArgs } from "node:util";

// ---------------------------------------------------------------------------
// CLI args
// ---------------------------------------------------------------------------

const {
  positionals: [command = "sync"],
  values: flags,
} = parseArgs({
  allowPositionals: true,
  options: {
    owner: { type: "string" },
    repo: { type: "string" },
    "dry-run": { type: "boolean", default: false },
  },
});

const OWNER = flags.owner ?? "";
const REPO = flags.repo ?? "";
const DRY_RUN = flags["dry-run"] ?? false;

if (!OWNER || !REPO) {
  console.error("Error: --owner and --repo are required.");
  process.exitCode = 1;
  process.exit();
}

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

interface GhLabel {
  id: number;
  name: string;
}

interface GhUser {
  login: string;
}

interface GhIssue {
  number: number;
  title: string;
  body: string | null;
  state: "open" | "closed";
  html_url: string;
  labels: GhLabel[];
  user: GhUser | null;
  created_at: string;
  updated_at: string;
  pull_request?: unknown;
}

/** pm item as returned by `pm list --json` */
interface PmItem {
  id: string;
  title: string;
  status: "open" | "in_progress" | "blocked" | "closed" | "canceled" | "draft";
  type: string;
  priority?: number;
  tags?: string[];
  blocked_by?: string;
  blocked_reason?: string;
  close_reason?: string;
  gh_number?: number;
}

// ---------------------------------------------------------------------------
// GitHub REST helpers
// ---------------------------------------------------------------------------

function ghToken(): string {
  const token = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN ?? "";
  if (!token) {
    throw new Error(
      "No GitHub token found. Set GH_TOKEN or GITHUB_TOKEN in your environment."
    );
  }
  return token;
}

async function ghFetch<T>(path: string, init?: RequestInit): Promise<T> {
  const url = `https://api.github.com${path}`;
  const res = await fetch(url, {
    ...init,
    headers: {
      Authorization: `Bearer ${ghToken()}`,
      Accept: "application/vnd.github+json",
      "X-GitHub-Api-Version": "2022-11-28",
      "User-Agent": "pm-github-sync/0.1.0",
      "Content-Type": "application/json",
      ...(init?.headers ?? {}),
    },
  });
  if (!res.ok) {
    const text = await res.text();
    throw new Error(`GitHub API ${res.status} ${path}: ${text}`);
  }
  return res.json() as Promise<T>;
}

async function fetchAllIssues(state: "open" | "all" = "open"): Promise<GhIssue[]> {
  const issues: GhIssue[] = [];
  let page = 1;
  while (true) {
    const batch = await ghFetch<GhIssue[]>(
      `/repos/${OWNER}/${REPO}/issues?state=${state}&per_page=100&page=${page}`
    );
    const real = batch.filter((i) => !i.pull_request);
    issues.push(...real);
    if (batch.length < 100) break;
    page++;
  }
  return issues;
}

async function addIssueLabel(number: number, label: string): Promise<void> {
  if (DRY_RUN) {
    console.log(`  [dry-run] POST /repos/${OWNER}/${REPO}/issues/${number}/labels  label=${label}`);
    return;
  }
  await ghFetch(`/repos/${OWNER}/${REPO}/issues/${number}/labels`, {
    method: "POST",
    body: JSON.stringify({ labels: [label] }),
  });
}

async function removeIssueLabel(number: number, label: string): Promise<void> {
  if (DRY_RUN) {
    console.log(`  [dry-run] DELETE label=${label} from issue #${number}`);
    return;
  }
  try {
    await ghFetch(`/repos/${OWNER}/${REPO}/issues/${number}/labels/${encodeURIComponent(label)}`, {
      method: "DELETE",
    });
  } catch {
    // Label may not exist — ignore
  }
}

async function postComment(number: number, body: string): Promise<void> {
  if (DRY_RUN) {
    console.log(`  [dry-run] POST comment on issue #${number}: "${body.slice(0, 80)}…"`);
    return;
  }
  await ghFetch(`/repos/${OWNER}/${REPO}/issues/${number}/comments`, {
    method: "POST",
    body: JSON.stringify({ body }),
  });
}

async function closeIssue(number: number): Promise<void> {
  if (DRY_RUN) {
    console.log(`  [dry-run] PATCH issue #${number} state=closed`);
    return;
  }
  await ghFetch(`/repos/${OWNER}/${REPO}/issues/${number}`, {
    method: "PATCH",
    body: JSON.stringify({ state: "closed" }),
  });
}

// ---------------------------------------------------------------------------
// pm-cli helpers
// ---------------------------------------------------------------------------

function pm(cmd: string): string {
  return execSync(`pm ${cmd}`, { encoding: "utf-8" }).trim();
}

function pmJson<T>(cmd: string): T {
  return JSON.parse(pm(`${cmd} --json`));
}

// ---------------------------------------------------------------------------
// Priority mapping: GitHub labels → pm priority (0=highest)
// ---------------------------------------------------------------------------

function labelsToPriority(labels: GhLabel[]): number {
  const names = labels.map((l) => l.name.toLowerCase());
  for (const name of names) {
    if (
      name.includes("priority: critical") ||
      name === "urgent" ||
      name === "p0"
    ) return 0;
    if (
      name.includes("priority: high") ||
      name === "high" ||
      name === "p1"
    ) return 1;
    if (
      name.includes("priority: low") ||
      name === "low" ||
      name === "p3"
    ) return 3;
  }
  return 2;
}

// ---------------------------------------------------------------------------
// Pull: GitHub Issues → pm items
// ---------------------------------------------------------------------------

async function pull(): Promise<void> {
  console.log(`Pulling issues from ${OWNER}/${REPO}…`);
  const issues = await fetchAllIssues("open");
  console.log(`  Fetched ${issues.length} open issue(s).`);

  let created = 0;
  let updated = 0;

  for (const issue of issues) {
    const idSuffix = `gh-issue-${issue.number}`;
    const priority = labelsToPriority(issue.labels);
    const tags = ["github", "gh-issue", ...issue.labels.map((l) => l.name)].join(",");

    // Check if a pm item with this gh-issue tag already exists
    const existing = pmJson<PmItem[]>(`list-all --tag ${idSuffix}`);

    if (existing.length > 0) {
      // Update existing item
      const pmId = existing[0].id;
      const cmd = [
        `update ${pmId}`,
        `--title "${issue.title.replace(/"/g, '\\"')}"`,
        `--priority ${priority}`,
        `--tags "${tags},${idSuffix}"`,
      ].join(" ");

      if (DRY_RUN) {
        console.log(`  [dry-run] pm ${cmd}`);
      } else {
        pm(cmd);
      }
      updated++;
    } else {
      // Create new pm item
      const body = (issue.body ?? "")
        .slice(0, 500)
        .replace(/"/g, '\\"');

      const cmd = [
        "create",
        `--type Issue`,
        `--title "${issue.title.replace(/"/g, '\\"')}"`,
        `--description "GitHub Issue #${issue.number} — ${OWNER}/${REPO}"`,
        `--body "${body}"`,
        `--priority ${priority}`,
        `--tags "${tags},${idSuffix}"`,
        "--json",
      ].join(" ");

      if (DRY_RUN) {
        console.log(`  [dry-run] pm ${cmd}`);
      } else {
        pm(cmd);
      }
      created++;
    }
  }

  console.log(`  Done: ${created} created, ${updated} updated.`);
}

// ---------------------------------------------------------------------------
// Push: pm status changes → GitHub
// ---------------------------------------------------------------------------

async function push(): Promise<void> {
  console.log(`Pushing pm status changes to ${OWNER}/${REPO}…`);

  // Find all pm items tagged with gh-issue
  const pmItems = pmJson<PmItem[]>("list-all --tag gh-issue");
  console.log(`  Found ${pmItems.length} pm item(s) with gh-issue tag.`);

  let pushed = 0;

  for (const item of pmItems) {
    // Extract issue number from tag list (gh-issue-<number>)
    const tag = (item.tags ?? []).find((t) => t.startsWith("gh-issue-"));
    if (!tag) continue;
    const number = parseInt(tag.replace("gh-issue-", ""), 10);
    if (isNaN(number)) continue;

    switch (item.status) {
      case "in_progress":
        console.log(`  #${number} → in_progress`);
        await removeIssueLabel(number, "blocked");
        await addIssueLabel(number, "in-progress");
        await postComment(number, `**pm-cli update:** This issue is now \`in_progress\` (pm item: ${item.id}).`);
        pushed++;
        break;

      case "blocked":
        console.log(`  #${number} → blocked`);
        await removeIssueLabel(number, "in-progress");
        await addIssueLabel(number, "blocked");
        const reason = item.blocked_reason ?? item.blocked_by ?? "no reason specified";
        await postComment(number, `**pm-cli update:** This issue is \`blocked\`. Reason: ${reason}`);
        pushed++;
        break;

      case "closed": {
        console.log(`  #${number} → closed`);
        const closeReason = item.close_reason ?? "resolved";
        await postComment(number, `**pm-cli update:** Marked as closed in pm-cli. Reason: ${closeReason}`);
        await removeIssueLabel(number, "in-progress");
        await removeIssueLabel(number, "blocked");
        await closeIssue(number);
        pushed++;
        break;
      }

      case "canceled": {
        console.log(`  #${number} → canceled`);
        await postComment(number, `**pm-cli update:** This issue was canceled in pm-cli (not going to fix).`);
        await closeIssue(number);
        pushed++;
        break;
      }

      default:
        // open / draft — no push action needed
        break;
    }
  }

  console.log(`  Pushed ${pushed} status update(s) to GitHub.`);
}

// ---------------------------------------------------------------------------
// Entry point
// ---------------------------------------------------------------------------

async function main(): Promise<void> {
  if (command === "pull") {
    await pull();
  } else if (command === "push") {
    await push();
  } else if (command === "sync") {
    await pull();
    await push();
  } else {
    console.error(`Unknown command: ${command}. Use pull, push, or sync.`);
    process.exitCode = 1;
  }
}

main().catch((err) => {
  console.error(err instanceof Error ? err.message : String(err));
  process.exitCode = 1;
});

#!/usr/bin/env tsx
import { execFileSync } from "node:child_process";

function pm(args: string[]): void {
  execFileSync("pm", args, { stdio: "inherit" });
}

const milestone = process.env.PM_RELEASE ?? "v1.4";

pm(["search", "--mode", "hybrid", "good first issue"]);
pm(["search", "--mode", "hybrid", "duplicate cold start startup"]);
pm([
  "create",
  "--type",
  "Issue",
  "--title",
  "Contributor-friendly setup docs are missing Windows instructions",
  "--description",
  "Add Windows-specific setup notes and troubleshooting for common shell/path issues.",
  "--priority",
  "2",
  "--tags",
  "good-first-issue,docs,contributors",
  "--release",
  milestone,
]);
pm([
  "create",
  "--type",
  "Milestone",
  "--title",
  `${milestone} contributor experience cleanup`,
  "--description",
  "Track docs and onboarding fixes before the next public release.",
  "--priority",
  "2",
  "--release",
  milestone,
]);
pm(["aggregate", "--group-by", "release"]);
pm(["calendar", "--view", "month", "--release", milestone]);

/**
 * release-manager — Release readiness assessment with pm-cli
 *
 * Lists all Milestone/Feature items for a sprint, calculates release readiness,
 * generates a draft release notes from closed Features, and outputs a Go/No-Go
 * decision based on P1 item completion.
 *
 * Usage:
 *   npx tsx main.ts --sprint "Sprint 12"
 *   npx tsx main.ts --sprint "Sprint 12" --version "v2.3.0"
 *   npx tsx main.ts --sprint "Sprint 12" --dry-run
 */

import { execSync } from "node:child_process";
import { parseArgs } from "node:util";

// ---------------------------------------------------------------------------
// CLI args
// ---------------------------------------------------------------------------

const { values: args } = parseArgs({
  options: {
    sprint: { type: "string" },
    version: { type: "string" },
    "dry-run": { type: "boolean", default: false },
  },
});

const SPRINT_NAME = args.sprint ?? "";
const RELEASE_VERSION = args.version ?? "next";
const DRY_RUN = args["dry-run"] ?? false;

if (!SPRINT_NAME) {
  console.error("Error: --sprint is required. Example: --sprint \"Sprint 12\"");
  process.exitCode = 1;
  process.exit();
}

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

/** A pm item as returned by `pm list --json`. */
interface PmItem {
  id: string;
  title: string;
  status: "open" | "in_progress" | "blocked" | "draft" | "closed" | "canceled";
  type: string;
  priority?: number;
  estimated_minutes?: number;
  sprint?: string;
  assignee?: string;
  close_reason?: string;
  blocked_reason?: string;
  blocked_by?: string;
  tags?: string[];
  created_at: string;
  closed_at?: string;
}

interface FeatureGroup {
  feature: PmItem;
  tasks: PmItem[];
  closedTasks: number;
  totalTasks: number;
  readinessPct: number;
}

interface ReleaseReport {
  sprint: string;
  version: string;
  milestones: PmItem[];
  features: FeatureGroup[];
  allItems: PmItem[];
  closedCount: number;
  openCount: number;
  blockedCount: number;
  p1Items: PmItem[];
  p1ClosedCount: number;
  overallReadinessPct: number;
  goNoGo: "GO" | "NO-GO";
  blockers: string[];
}

// ---------------------------------------------------------------------------
// pm-cli helpers
// ---------------------------------------------------------------------------

function pm(cmd: string): string {
  return execSync(`pm ${cmd}`, { encoding: "utf-8" }).trim();
}

function pmJson<T>(cmd: string): T {
  return JSON.parse(pm(`${cmd} --json`));
}

// ---------------------------------------------------------------------------
// Data fetching
// ---------------------------------------------------------------------------

/** Fetch all items for the given sprint. */
function fetchSprintItems(sprintName: string): PmItem[] {
  try {
    return pmJson<PmItem[]>(`list-all --sprint "${sprintName}"`);
  } catch {
    // Fallback: get all items and filter client-side
    const all = pmJson<PmItem[]>("list-all");
    return all.filter((item) => item.sprint === sprintName);
  }
}

/** Group feature items with their child tasks. */
function groupFeatures(items: PmItem[]): FeatureGroup[] {
  const features = items.filter((i) => i.type === "Feature");
  const tasksByParent = new Map<string, PmItem[]>();

  for (const item of items) {
    if (item.type === "Task" || item.type === "Bug" || item.type === "Issue") {
      const parentId = (item as PmItem & { parent?: string }).parent;
      if (parentId) {
        if (!tasksByParent.has(parentId)) tasksByParent.set(parentId, []);
        tasksByParent.get(parentId)!.push(item);
      }
    }
  }

  return features.map((feature) => {
    const tasks = tasksByParent.get(feature.id) ?? [];
    const closedTasks = tasks.filter(
      (t) => t.status === "closed" || t.status === "canceled"
    ).length;
    const totalTasks = tasks.length;
    const readinessPct =
      totalTasks > 0
        ? Math.round((closedTasks / totalTasks) * 100)
        : feature.status === "closed"
        ? 100
        : 0;

    return { feature, tasks, closedTasks, totalTasks, readinessPct };
  });
}

// ---------------------------------------------------------------------------
// Analysis
// ---------------------------------------------------------------------------

function analyzeRelease(sprintName: string, version: string): ReleaseReport {
  const allItems = fetchSprintItems(sprintName);

  const milestones = allItems.filter((i) => i.type === "Milestone");
  const featureGroups = groupFeatures(allItems);

  const closedCount = allItems.filter(
    (i) => i.status === "closed" || i.status === "canceled"
  ).length;
  const blockedCount = allItems.filter((i) => i.status === "blocked").length;
  const openCount = allItems.length - closedCount;

  // P1 items (priority 1 = high)
  const p1Items = allItems.filter(
    (i) => (i.priority ?? 2) <= 1 && i.type !== "Milestone"
  );
  const p1ClosedCount = p1Items.filter(
    (i) => i.status === "closed" || i.status === "canceled"
  ).length;

  const overallReadinessPct =
    allItems.length > 0
      ? Math.round((closedCount / allItems.length) * 100)
      : 0;

  // Collect blockers narrative
  const blockers: string[] = allItems
    .filter((i) => i.status === "blocked")
    .map((i) => {
      const reason = i.blocked_reason ?? i.blocked_by ?? "no reason specified";
      return `${i.id} "${i.title}" — ${reason}`;
    });

  // P1 incomplete items also surface as blockers for Go/No-Go
  const incompleteP1 = p1Items.filter(
    (i) => i.status !== "closed" && i.status !== "canceled"
  );
  for (const item of incompleteP1) {
    if (!blockers.some((b) => b.startsWith(item.id))) {
      blockers.push(`P1 incomplete: ${item.id} "${item.title}" (${item.status})`);
    }
  }

  const goNoGo: "GO" | "NO-GO" =
    p1Items.length > 0 && p1ClosedCount < p1Items.length
      ? "NO-GO"
      : blockedCount > 0
      ? "NO-GO"
      : "GO";

  return {
    sprint: sprintName,
    version,
    milestones,
    features: featureGroups,
    allItems,
    closedCount,
    openCount,
    blockedCount,
    p1Items,
    p1ClosedCount,
    overallReadinessPct,
    goNoGo,
    blockers,
  };
}

// ---------------------------------------------------------------------------
// Release notes generation
// ---------------------------------------------------------------------------

function generateReleaseNotes(report: ReleaseReport): string {
  const lines: string[] = [
    `# Release Notes — ${report.version}`,
    `Sprint: ${report.sprint}`,
    `Date: ${new Date().toISOString().slice(0, 10)}`,
    "",
    "## What's New",
    "",
  ];

  const closedFeatures = report.features.filter(
    (fg) => fg.feature.status === "closed"
  );

  if (closedFeatures.length === 0) {
    lines.push("_No features closed in this sprint._");
  } else {
    for (const { feature } of closedFeatures) {
      lines.push(`- **${feature.title}** (${feature.id})`);
    }
  }

  // Closed bugs / issues
  const closedIssues = report.allItems.filter(
    (i) =>
      (i.type === "Bug" || i.type === "Issue") &&
      (i.status === "closed" || i.status === "canceled")
  );

  if (closedIssues.length > 0) {
    lines.push("");
    lines.push("## Bug Fixes");
    lines.push("");
    for (const issue of closedIssues) {
      lines.push(`- ${issue.title} (${issue.id})`);
    }
  }

  lines.push("");
  lines.push("## Stats");
  lines.push("");
  lines.push(`- Items closed: ${report.closedCount} / ${report.allItems.length}`);
  lines.push(`- Release readiness: ${report.overallReadinessPct}%`);
  lines.push(`- P1 items: ${report.p1ClosedCount} / ${report.p1Items.length} closed`);

  return lines.join("\n");
}

// ---------------------------------------------------------------------------
// Terminal output
// ---------------------------------------------------------------------------

const RESET = "\x1b[0m";
const BOLD = "\x1b[1m";
const RED = "\x1b[31m";
const GREEN = "\x1b[32m";
const YELLOW = "\x1b[33m";
const CYAN = "\x1b[36m";
const DIM = "\x1b[2m";

function colorStatus(status: PmItem["status"]): string {
  switch (status) {
    case "closed":
    case "canceled":
      return `${GREEN}${status}${RESET}`;
    case "blocked":
      return `${RED}${status}${RESET}`;
    case "in_progress":
      return `${CYAN}in_progress${RESET}`;
    default:
      return `${DIM}${status}${RESET}`;
  }
}

function progressBar(pct: number, width = 20): string {
  const filled = Math.round((pct / 100) * width);
  const empty = width - filled;
  return `[${"█".repeat(filled)}${"░".repeat(empty)}] ${pct}%`;
}

function printReport(report: ReleaseReport, releaseNotes: string): void {
  console.log();
  console.log(
    `${BOLD}Release Manager — ${report.sprint}  /  ${report.version}${RESET}`
  );
  console.log("─".repeat(60));
  console.log();

  // Overall readiness
  console.log(`${BOLD}Overall Readiness${RESET}`);
  const barColor =
    report.overallReadinessPct >= 80
      ? GREEN
      : report.overallReadinessPct >= 50
      ? YELLOW
      : RED;
  console.log(
    `  ${barColor}${progressBar(report.overallReadinessPct)}${RESET}  (${report.closedCount}/${report.allItems.length} items closed)`
  );
  console.log();

  // P1 summary
  console.log(`${BOLD}P1 Item Status${RESET}`);
  if (report.p1Items.length === 0) {
    console.log(`  ${DIM}No P1 items in this sprint.${RESET}`);
  } else {
    const p1Color =
      report.p1ClosedCount === report.p1Items.length ? GREEN : RED;
    console.log(
      `  ${p1Color}${report.p1ClosedCount} / ${report.p1Items.length} P1 items closed${RESET}`
    );
    for (const item of report.p1Items) {
      const indicator =
        item.status === "closed" || item.status === "canceled" ? "✓" : "✗";
      const color =
        item.status === "closed" || item.status === "canceled" ? GREEN : RED;
      console.log(
        `  ${color}${indicator}${RESET}  ${item.id}  ${item.title.slice(0, 45)}  [${colorStatus(item.status)}]`
      );
    }
  }
  console.log();

  // Feature breakdown
  if (report.features.length > 0) {
    console.log(`${BOLD}Feature Readiness${RESET}`);
    const col = (s: string, w: number) => s.slice(0, w).padEnd(w);
    console.log(
      `  ${col("ID", 12)} ${col("Feature", 36)} ${col("Tasks", 10)} ${"Readiness"}`
    );
    console.log(
      `  ${"─".repeat(12)} ${"─".repeat(36)} ${"─".repeat(10)} ${"─".repeat(20)}`
    );
    for (const { feature, closedTasks, totalTasks, readinessPct } of report.features) {
      const tasksSummary =
        totalTasks > 0 ? `${closedTasks}/${totalTasks}` : "—";
      const barC =
        readinessPct === 100 ? GREEN : readinessPct >= 50 ? YELLOW : RED;
      console.log(
        `  ${col(feature.id, 12)} ${col(feature.title, 36)} ${col(tasksSummary, 10)} ${barC}${progressBar(readinessPct, 12)}${RESET}`
      );
    }
    console.log();
  }

  // Blockers
  if (report.blockers.length > 0) {
    console.log(`${BOLD}${RED}Blockers${RESET}`);
    for (const b of report.blockers) {
      console.log(`  ${RED}•${RESET} ${b}`);
    }
    console.log();
  }

  // Release Notes draft
  console.log(`${BOLD}Release Notes Draft${RESET}`);
  console.log("─".repeat(60));
  console.log(releaseNotes);
  console.log("─".repeat(60));
  console.log();

  // Go/No-Go decision
  const goColor = report.goNoGo === "GO" ? GREEN : RED;
  console.log(
    `${BOLD}Decision: ${goColor}${report.goNoGo}${RESET}${BOLD} for ${report.version}${RESET}`
  );
  if (report.goNoGo === "NO-GO") {
    console.log(
      `  ${RED}Resolve ${report.blockers.length} blocker(s) before releasing.${RESET}`
    );
  }
  console.log();

  if (DRY_RUN) {
    console.log(`${DIM}(dry-run: no changes written)${RESET}`);
  }
}

// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------

async function main(): Promise<void> {
  console.log(`Analyzing release readiness for "${SPRINT_NAME}" → ${RELEASE_VERSION}…`);

  const report = analyzeRelease(SPRINT_NAME, RELEASE_VERSION);
  console.log(`  ${report.allItems.length} items found in sprint.`);

  const releaseNotes = generateReleaseNotes(report);
  printReport(report, releaseNotes);
}

main().catch((err) => {
  console.error(err instanceof Error ? err.message : String(err));
  process.exitCode = 1;
});

#!/usr/bin/env tsx
import { execFileSync } from "node:child_process";

function pm(args: string[]): void {
  execFileSync("pm", args, { stdio: "inherit" });
}

const prefix = process.env.PM_ITEM_PREFIX ?? "APP";
const taskId = process.env.PM_TASK_ID ?? `${prefix}-3`;

pm([
  "create",
  "--type",
  "Epic",
  "--title",
  "Ship billing dashboard",
  "--description",
  "End-to-end solo developer workflow for planning, implementation, verification, and learnings.",
  "--priority",
  "1",
  "--tags",
  "billing,solo",
]);
pm([
  "create",
  "--type",
  "Task",
  "--title",
  "Add invoice status filters",
  "--description",
  "Filter paid, open, overdue, and failed invoices on the dashboard.",
  "--priority",
  "1",
  "--tags",
  "billing,frontend",
]);
pm(["context", "--depth", "full"]);
pm(["start-task", taskId]);
pm(["notes", taskId, "--add", "Implementation note: keep filters URL-addressable for support links."]);
pm(["test", taskId, "--add", "--command", "npm test -- invoice-filters", "--description", "Invoice filter regression tests"]);
pm(["learnings", taskId, "--add", "URL-backed filters reduce support handoff friction."]);
pm(["close-task", taskId, "Invoice filters implemented, tested, and documented."]);

/**
 * sprint-velocity-tracker — Track and project sprint velocity with pm-cli
 *
 * Reads closed items from the last N sprints, calculates velocity per sprint
 * (story points / estimated hours completed), draws an ASCII velocity chart,
 * and projects capacity for the next sprint.
 *
 * Usage:
 *   npx tsx main.ts
 *   SPRINTS_BACK=5 npx tsx main.ts
 *   npx tsx main.ts --sprints 5 --unit hours
 */

import { execSync } from "node:child_process";
import { parseArgs } from "node:util";

// ---------------------------------------------------------------------------
// CLI args / env
// ---------------------------------------------------------------------------

const { values: args } = parseArgs({
  options: {
    sprints: { type: "string" },
    unit: { type: "string", default: "hours" }, // "hours" | "points"
    chart: { type: "boolean", default: true },
  },
});

const SPRINTS_BACK = parseInt(
  args.sprints ?? process.env.SPRINTS_BACK ?? "3",
  10
);
const UNIT: "hours" | "points" = args.unit === "points" ? "points" : "hours";

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

/** A pm item as returned by `pm list --json`. */
interface PmItem {
  id: string;
  title: string;
  status: "open" | "in_progress" | "blocked" | "draft" | "closed" | "canceled";
  type: string;
  priority?: number;
  estimated_minutes?: number;
  story_points?: number;
  sprint?: string;
  assignee?: string;
  created_at: string;
  closed_at?: string;
}

/** A pm Milestone representing a sprint. */
interface SprintMilestone {
  id: string;
  title: string;
  status: PmItem["status"];
  created_at: string;
  closed_at?: string;
}

/** Velocity data for one sprint. */
interface SprintVelocity {
  name: string;
  totalItems: number;
  closedItems: number;
  estimatedHours: number;
  completedHours: number;
  storyPoints: number;
  completedPoints: number;
  velocity: number; // depends on UNIT
  velocityUnit: string;
}

// ---------------------------------------------------------------------------
// pm-cli helpers
// ---------------------------------------------------------------------------

function pm(cmd: string): string {
  return execSync(`pm ${cmd}`, { encoding: "utf-8" }).trim();
}

function pmJson<T>(cmd: string): T {
  return JSON.parse(pm(`${cmd} --json`));
}

// ---------------------------------------------------------------------------
// Sprint discovery
// ---------------------------------------------------------------------------

/** Fetch sprint Milestones and return the most recent N closed ones. */
function fetchRecentSprints(n: number): SprintMilestone[] {
  let milestones: PmItem[];
  try {
    milestones = pmJson<PmItem[]>("list-all --type Milestone");
  } catch {
    milestones = pmJson<PmItem[]>("list-all").filter(
      (i) => i.type === "Milestone"
    );
  }

  // Sort by created_at descending, take the most recent N
  return milestones
    .sort(
      (a, b) =>
        new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
    )
    .slice(0, n) as SprintMilestone[];
}

// ---------------------------------------------------------------------------
// Velocity calculation
// ---------------------------------------------------------------------------

/** Fetch all closed items for a sprint by sprint name tag. */
function fetchClosedItems(sprintName: string): PmItem[] {
  let items: PmItem[];
  try {
    items = pmJson<PmItem[]>(`list-all --sprint "${sprintName}"`);
  } catch {
    items = pmJson<PmItem[]>("list-all").filter(
      (i) => i.sprint === sprintName
    );
  }
  return items.filter(
    (i) =>
      (i.status === "closed" || i.status === "canceled") &&
      !["Milestone", "Epic"].includes(i.type)
  );
}

function calcVelocity(sprint: SprintMilestone): SprintVelocity {
  const allSprintItems: PmItem[] = (() => {
    try {
      return pmJson<PmItem[]>(`list-all --sprint "${sprint.title}"`);
    } catch {
      return pmJson<PmItem[]>("list-all").filter(
        (i) => i.sprint === sprint.title
      );
    }
  })().filter((i) => !["Milestone", "Epic"].includes(i.type));

  const closed = allSprintItems.filter(
    (i) => i.status === "closed" || i.status === "canceled"
  );

  const estimatedHours = allSprintItems.reduce(
    (sum, i) => sum + (i.estimated_minutes ?? 0) / 60,
    0
  );
  const completedHours = closed.reduce(
    (sum, i) => sum + (i.estimated_minutes ?? 0) / 60,
    0
  );

  const storyPoints = allSprintItems.reduce(
    (sum, i) => sum + (i.story_points ?? 0),
    0
  );
  const completedPoints = closed.reduce(
    (sum, i) => sum + (i.story_points ?? 0),
    0
  );

  const velocity =
    UNIT === "points"
      ? completedPoints
      : Math.round(completedHours * 10) / 10;

  return {
    name: sprint.title,
    totalItems: allSprintItems.length,
    closedItems: closed.length,
    estimatedHours: Math.round(estimatedHours * 10) / 10,
    completedHours: Math.round(completedHours * 10) / 10,
    storyPoints,
    completedPoints,
    velocity,
    velocityUnit: UNIT === "points" ? "pts" : "h",
  };
}

// ---------------------------------------------------------------------------
// Statistics
// ---------------------------------------------------------------------------

function average(nums: number[]): number {
  if (nums.length === 0) return 0;
  return nums.reduce((s, n) => s + n, 0) / nums.length;
}

function stddev(nums: number[]): number {
  if (nums.length < 2) return 0;
  const avg = average(nums);
  const variance = nums.reduce((s, n) => s + Math.pow(n - avg, 2), 0) / nums.length;
  return Math.sqrt(variance);
}

function trend(nums: number[]): "up" | "down" | "stable" {
  if (nums.length < 2) return "stable";
  const first = average(nums.slice(0, Math.ceil(nums.length / 2)));
  const last = average(nums.slice(Math.floor(nums.length / 2)));
  const delta = last - first;
  const threshold = average(nums) * 0.05; // 5% threshold
  if (delta > threshold) return "up";
  if (delta < -threshold) return "down";
  return "stable";
}

// ---------------------------------------------------------------------------
// ASCII chart
// ---------------------------------------------------------------------------

const CHART_HEIGHT = 8;
const CHART_WIDTH = 6; // chars per sprint bar

function drawVelocityChart(sprints: SprintVelocity[]): string {
  if (sprints.length === 0) return "(no data)";

  const velocities = sprints.map((s) => s.velocity);
  const maxV = Math.max(...velocities, 1);

  const lines: string[] = [];
  const unit = sprints[0].velocityUnit;

  // Y-axis + bars
  for (let row = CHART_HEIGHT; row >= 0; row--) {
    const threshold = (row / CHART_HEIGHT) * maxV;
    let line = "";

    // Y-axis label (every other row)
    if (row % 2 === 0) {
      const label = String(Math.round(threshold)).padStart(4);
      line += `${label} │`;
    } else {
      line += `     │`;
    }

    for (const s of sprints) {
      const barHeight = (s.velocity / maxV) * CHART_HEIGHT;
      if (barHeight >= row) {
        line += " ████ ";
      } else if (row === 0) {
        line += " ─────";
      } else {
        line += "      ";
      }
    }
    lines.push(line);
  }

  // X-axis baseline
  lines.push(`     └${"──────".repeat(sprints.length)}`);

  // Sprint labels
  const labelLine =
    "       " +
    sprints.map((s) => s.name.slice(-6).padEnd(6)).join("");
  lines.push(labelLine);

  lines.push(`\n  Unit: ${unit} completed per sprint`);
  return lines.join("\n");
}

// ---------------------------------------------------------------------------
// Terminal output
// ---------------------------------------------------------------------------

const RESET = "\x1b[0m";
const BOLD = "\x1b[1m";
const GREEN = "\x1b[32m";
const YELLOW = "\x1b[33m";
const CYAN = "\x1b[36m";
const DIM = "\x1b[2m";
const RED = "\x1b[31m";

function trendArrow(t: "up" | "down" | "stable"): string {
  if (t === "up") return `${GREEN}↑ improving${RESET}`;
  if (t === "down") return `${RED}↓ declining${RESET}`;
  return `${YELLOW}→ stable${RESET}`;
}

function printVelocityReport(sprints: SprintVelocity[]): void {
  const velocities = sprints.map((s) => s.velocity);
  const avg = average(velocities);
  const sd = stddev(velocities);
  const t = trend(velocities);
  const projected = Math.round(avg * 10) / 10;
  const unit = sprints[0]?.velocityUnit ?? "h";

  console.log();
  console.log(`${BOLD}Sprint Velocity Tracker${RESET}  (last ${sprints.length} sprint(s), unit: ${unit})`);
  console.log("─".repeat(60));
  console.log();

  // Sprint table
  const col = (s: string, w: number) => s.slice(0, w).padEnd(w);
  console.log(
    `  ${col("Sprint", 20)} ${col("Items", 7)} ${col("Closed", 7)} ${col(`${UNIT === "points" ? "Pts" : "Est h"}`, 8)} ${col(`Done ${unit}`, 8)} ${BOLD}Velocity${RESET}`
  );
  console.log(
    `  ${"─".repeat(20)} ${"─".repeat(7)} ${"─".repeat(7)} ${"─".repeat(8)} ${"─".repeat(8)} ${"─".repeat(10)}`
  );

  for (const s of sprints) {
    const completionPct =
      s.totalItems > 0 ? Math.round((s.closedItems / s.totalItems) * 100) : 0;
    const pctColor =
      completionPct >= 80 ? GREEN : completionPct >= 50 ? YELLOW : RED;
    const estDisplay =
      UNIT === "points"
        ? String(s.storyPoints)
        : `${s.estimatedHours}h`;
    const doneDisplay =
      UNIT === "points"
        ? String(s.completedPoints)
        : `${s.completedHours}h`;
    console.log(
      `  ${col(s.name, 20)} ${col(String(s.totalItems), 7)} ${col(`${pctColor}${s.closedItems}${RESET}`, 7 + 9)} ${col(estDisplay, 8)} ${col(doneDisplay, 8)} ${CYAN}${s.velocity}${unit}${RESET}`
    );
  }
  console.log();

  // Stats summary
  console.log(`${BOLD}Summary${RESET}`);
  console.log(`  Average velocity : ${CYAN}${Math.round(avg * 10) / 10}${unit}${RESET}`);
  console.log(`  Std deviation    : ${DIM}±${Math.round(sd * 10) / 10}${unit}${RESET}`);
  console.log(`  Trend            : ${trendArrow(t)}`);
  console.log();

  // ASCII chart
  if (args.chart !== false && sprints.length > 0) {
    console.log(`${BOLD}Velocity Chart${RESET}`);
    console.log();
    console.log(drawVelocityChart(sprints));
    console.log();
  }

  // Next sprint projection
  console.log(`${BOLD}Next Sprint Projection${RESET}`);
  const lo = Math.max(0, Math.round((avg - sd) * 10) / 10);
  const hi = Math.round((avg + sd) * 10) / 10;
  console.log(`  Based on ${sprints.length} sprint(s), plan for:`);
  console.log(`  ${GREEN}${projected}${unit}${RESET} of work  (range: ${lo}–${hi}${unit})`);
  console.log();

  if (sprints.length < 3) {
    console.log(
      `  ${YELLOW}Note: projections improve with more sprint history.${RESET}`
    );
    console.log(
      `  Run with SPRINTS_BACK=5 for a more reliable average.`
    );
    console.log();
  }
}

// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------

async function main(): Promise<void> {
  console.log(
    `Fetching velocity data for last ${SPRINTS_BACK} sprint(s) (unit: ${UNIT})…`
  );

  const recentSprints = fetchRecentSprints(SPRINTS_BACK);

  if (recentSprints.length === 0) {
    console.log(
      "No sprint Milestones found. Create at least one Milestone with type=Milestone."
    );
    process.exitCode = 1;
    return;
  }

  console.log(`  Found ${recentSprints.length} sprint Milestone(s).`);

  const velocities = recentSprints.map((s) => {
    process.stdout.write(`  Calculating velocity for "${s.title}"…`);
    const v = calcVelocity(s);
    process.stdout.write(` ${v.velocity}${v.velocityUnit}\n`);
    return v;
  });

  // Reverse so oldest sprint is leftmost in chart
  velocities.reverse();

  printVelocityReport(velocities);
}

main().catch((err) => {
  console.error(err instanceof Error ? err.message : String(err));
  process.exitCode = 1;
});

#!/usr/bin/env tsx
import { execFileSync } from "node:child_process";

function pm(args: string[]): void {
  execFileSync("pm", args, { stdio: "inherit" });
}

const sprint = process.env.PM_SPRINT ?? "2026-W20";

pm([
  "create",
  "--type",
  "Milestone",
  "--title",
  `${sprint} sprint goal`,
  "--description",
  "Team sprint focused on closing high-priority product quality items.",
  "--priority",
  "1",
  "--sprint",
  sprint,
]);
pm([
  "create",
  "--type",
  "Feature",
  "--title",
  "Improve project sharing review flow",
  "--description",
  "Make shared project permissions clear and enforce view-only access.",
  "--priority",
  "1",
  "--assignee",
  "alex",
  "--sprint",
  sprint,
]);
pm(["list-open", "--sprint", sprint]);
pm(["aggregate", "--group-by", "assignee"]);
pm(["calendar", "--view", "week", "--sprint", sprint]);
pm(["validate", "--check-lifecycle", "--check-stale-blockers"]);

/**
 * team-standup-reporter — Generate daily standup reports from pm-cli activity
 *
 * Reads pm activity for the last 24h (or since last Friday for Mondays),
 * groups by team member, and formats Yesterday / Today / Blockers.
 *
 * Optionally posts to Slack via an Incoming Webhook.
 *
 * Usage:
 *   npx tsx main.ts
 *   npx tsx main.ts --assignee alice
 *   npx tsx main.ts --slack
 *   SLACK_WEBHOOK_URL=https://hooks.slack.com/... npx tsx main.ts --slack
 */

import { execSync } from "node:child_process";
import { parseArgs } from "node:util";

// ---------------------------------------------------------------------------
// CLI args
// ---------------------------------------------------------------------------

const { values: args } = parseArgs({
  options: {
    assignee: { type: "string" },
    slack: { type: "boolean", default: false },
    "webhook-url": { type: "string" },
  },
});

const FILTER_ASSIGNEE = args.assignee ?? null;
const POST_TO_SLACK = args.slack ?? false;
const SLACK_WEBHOOK =
  args["webhook-url"] ??
  process.env.SLACK_WEBHOOK_URL ??
  "";

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

/** A single activity entry returned by `pm activity --json`. */
interface ActivityEntry {
  id: string;
  item_id: string;
  item_title?: string;
  op: string;        // "create" | "update" | "close" | "comment" | "note" | "file" | "claim" | ...
  author?: string;
  ts: string;        // ISO timestamp
  message?: string;
}

/** A pm item (minimal fields we need for "today" list). */
interface PmItem {
  id: string;
  title: string;
  status: "open" | "in_progress" | "blocked" | "closed" | "canceled" | "draft";
  assignee?: string;
  blocked_reason?: string;
  blocked_by?: string;
  estimated_minutes?: number;
}

/** Grouped standup data for one team member. */
interface MemberStandup {
  author: string;
  yesterday: YesterdayEntry[];
  today: PmItem[];
  blockers: PmItem[];
}

interface YesterdayEntry {
  itemId: string;
  itemTitle: string;
  ops: string[];
  estimatedHours?: number;
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

function pm(cmd: string): string {
  return execSync(`pm ${cmd}`, { encoding: "utf-8" }).trim();
}

function pmJson<T>(cmd: string): T {
  return JSON.parse(pm(`${cmd} --json`));
}

/** Return the "from" timestamp for activity queries.
 *  On Mondays we go back to last Friday (72h). Otherwise 24h. */
function activityFrom(): string {
  const now = new Date();
  const dayOfWeek = now.getDay(); // 0=Sun, 1=Mon, ..., 6=Sat
  const hoursBack = dayOfWeek === 1 ? 72 : 24;
  const from = new Date(now.getTime() - hoursBack * 60 * 60 * 1000);
  return from.toISOString();
}

/** Format a date as "Monday 2026-05-11" */
function formatDate(d: Date): string {
  const days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
  const ymd = d.toISOString().slice(0, 10);
  return `${days[d.getDay()]} ${ymd}`;
}

// ---------------------------------------------------------------------------
// Build standup data
// ---------------------------------------------------------------------------

function fetchActivity(from: string): ActivityEntry[] {
  const cmd = FILTER_ASSIGNEE
    ? `activity --from "${from}" --author "${FILTER_ASSIGNEE}"`
    : `activity --from "${from}"`;
  return pmJson<ActivityEntry[]>(cmd);
}

function fetchOpenItems(): PmItem[] {
  const open = pmJson<PmItem[]>("list-open");
  const inProgress = pmJson<PmItem[]>("list-in-progress");
  const blocked = pmJson<PmItem[]>("list-blocked");
  return [...open, ...inProgress, ...blocked];
}

/** Group activity entries by author, then by item. */
function groupActivity(entries: ActivityEntry[]): Map<string, Map<string, YesterdayEntry>> {
  const byAuthor = new Map<string, Map<string, YesterdayEntry>>();

  for (const entry of entries) {
    const author = entry.author ?? "(unknown)";
    if (!byAuthor.has(author)) {
      byAuthor.set(author, new Map());
    }
    const byItem = byAuthor.get(author)!;

    if (!byItem.has(entry.item_id)) {
      byItem.set(entry.item_id, {
        itemId: entry.item_id,
        itemTitle: entry.item_title ?? entry.item_id,
        ops: [],
      });
    }

    const existing = byItem.get(entry.item_id)!;
    if (!existing.ops.includes(entry.op)) {
      existing.ops.push(entry.op);
    }
  }

  return byAuthor;
}

/** Describe a list of ops concisely: "Started, commented, closed" → readable verb */
function describeOps(ops: string[]): string {
  const verbMap: Record<string, string> = {
    create: "Created",
    update: "Updated",
    close: "Closed",
    claim: "Started",
    release: "Paused",
    comment: "Commented on",
    note: "Added notes to",
    learning: "Added learnings to",
    file: "Attached files to",
    "start-task": "Started",
    "close-task": "Closed",
    "pause-task": "Paused",
  };

  const verbs = ops.map((op) => verbMap[op] ?? op);
  if (verbs.length === 1) return verbs[0];
  const last = verbs.pop();
  return `${verbs.join(", ")} and ${last}`;
}

function buildStandups(
  activityByAuthor: Map<string, Map<string, YesterdayEntry>>,
  allItems: PmItem[]
): MemberStandup[] {
  const authors = [...activityByAuthor.keys()].sort();
  const itemsByAssignee = new Map<string, PmItem[]>();

  for (const item of allItems) {
    if (item.assignee) {
      if (!itemsByAssignee.has(item.assignee)) {
        itemsByAssignee.set(item.assignee, []);
      }
      itemsByAssignee.get(item.assignee)!.push(item);
    }
  }

  return authors.map((author) => {
    const byItem = activityByAuthor.get(author)!;
    const yesterday = [...byItem.values()];
    const myItems = itemsByAssignee.get(author) ?? [];
    const today = myItems.filter((i) => i.status === "open" || i.status === "in_progress");
    const blockers = myItems.filter((i) => i.status === "blocked");

    return { author, yesterday, today, blockers };
  });
}

// ---------------------------------------------------------------------------
// Format report
// ---------------------------------------------------------------------------

function formatTextReport(standups: MemberStandup[], date: string): string {
  const lines: string[] = [
    `Daily Standup — ${date}`,
    "─".repeat(48),
    "",
  ];

  for (const member of standups) {
    lines.push(member.author);

    lines.push("  Yesterday:");
    if (member.yesterday.length === 0) {
      lines.push("    (no recorded activity)");
    } else {
      for (const entry of member.yesterday) {
        const verb = describeOps(entry.ops);
        lines.push(`    • ${verb} ${entry.itemId} "${entry.itemTitle}"`);
      }
    }

    lines.push("  Today:");
    if (member.today.length === 0) {
      lines.push("    (nothing assigned)");
    } else {
      const items = member.today
        .map((i) => `${i.id} (${i.status.replace("_", " ")})`)
        .join(", ");
      lines.push(`    ${items}`);
    }

    lines.push("  Blockers:");
    if (member.blockers.length === 0) {
      lines.push("    none");
    } else {
      for (const b of member.blockers) {
        const reason = b.blocked_reason ?? b.blocked_by ?? "reason not specified";
        lines.push(`    ${b.id} is blocked — ${reason}`);
      }
    }

    lines.push("");
  }

  return lines.join("\n");
}

/** Format for Slack — uses mrkdwn. */
function formatSlackPayload(standups: MemberStandup[], date: string): string {
  const blocks: unknown[] = [
    {
      type: "header",
      text: { type: "plain_text", text: `Daily Standup — ${date}`, emoji: false },
    },
    { type: "divider" },
  ];

  for (const member of standups) {
    const yesterdayLines =
      member.yesterday.length === 0
        ? "_no recorded activity_"
        : member.yesterday
            .map((e) => `• ${describeOps(e.ops)} *${e.itemId}* "${e.itemTitle}"`)
            .join("\n");

    const todayText =
      member.today.length === 0
        ? "_nothing assigned_"
        : member.today.map((i) => `${i.id} (${i.status.replace("_", " ")})`).join(", ");

    const blockersText =
      member.blockers.length === 0
        ? "none"
        : member.blockers
            .map((b) => `${b.id} — ${b.blocked_reason ?? b.blocked_by ?? "reason not specified"}`)
            .join("; ");

    blocks.push({
      type: "section",
      text: {
        type: "mrkdwn",
        text: `*${member.author}*\n*Yesterday:*\n${yesterdayLines}\n*Today:* ${todayText}\n*Blockers:* ${blockersText}`,
      },
    });
  }

  return JSON.stringify({ blocks });
}

// ---------------------------------------------------------------------------
// Slack posting
// ---------------------------------------------------------------------------

async function postToSlack(payload: string): Promise<void> {
  if (!SLACK_WEBHOOK) {
    console.warn("SLACK_WEBHOOK_URL not set — skipping Slack post.");
    return;
  }

  const res = await fetch(SLACK_WEBHOOK, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: payload,
  });

  if (!res.ok) {
    const text = await res.text();
    throw new Error(`Slack webhook error ${res.status}: ${text}`);
  }

  console.log("Posted to Slack.");
}

// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------

async function main(): Promise<void> {
  const from = activityFrom();
  const date = formatDate(new Date());

  console.log(`Fetching pm activity since ${from}…`);

  const activity = fetchActivity(from);
  console.log(`  ${activity.length} activity entries found.`);

  const allItems = fetchOpenItems();
  const activityByAuthor = groupActivity(activity);
  const standups = buildStandups(activityByAuthor, allItems);

  if (standups.length === 0) {
    console.log("No activity found for the standup window. Nothing to report.");
    return;
  }

  const textReport = formatTextReport(standups, date);
  console.log("\n" + textReport);

  if (POST_TO_SLACK) {
    const slackPayload = formatSlackPayload(standups, date);
    await postToSlack(slackPayload);
  }
}

main().catch((err) => {
  console.error(err instanceof Error ? err.message : String(err));
  process.exitCode = 1;
});

/**
 * ts-sdk-starter — pm-cli TypeScript extension reference
 *
 * Demonstrates 8 of the 9 SDK capability types with correct types and API usage:
 *   1. commands   — custom `pm incident` command
 *   2. schema     — custom "Incident" item type + fields
 *   3. schema     — custom flag on `create` (--severity)
 *   4. importers  — JSON fixture importer
 *   5. hooks      — beforeCommand / afterCommand lifecycle hooks
 *   6. renderers  — toon renderer override for incident output
 *   7. search     — custom search provider (title-match stub)
 *   8. preflight  — preflight decision override
 *   9. services   — help_format service override stub
 *
 * Note: `parser` (registerParser) is not demonstrated here. See pm-starter
 * for a parser example.
 *
 * Each section is labelled with its capability name so you can jump directly
 * to the capability you care about when building your own extension.
 */

import {
  defineExtension,
  type ExtensionApi,
  type CommandHandlerContext,
  type ImportExportContext,
  type BeforeCommandHookContext,
  type AfterCommandHookContext,
  type RendererOverrideContext,
  type SearchProviderQueryContext,
  type SearchProviderHit,
  type PreflightOverrideContext,
  type ServiceOverrideContext,
} from "@unbrained/pm-cli/sdk";
import * as fs from "node:fs/promises";
import * as path from "node:path";

// ---------------------------------------------------------------------------
// Shared types
// ---------------------------------------------------------------------------

/** Shape of a JSON fixture file entry for the incident importer. */
interface IncidentFixture {
  id?: string;
  title: string;
  description?: string;
  severity: "critical" | "major" | "minor";
  service?: "api" | "web" | "worker";
}

// ---------------------------------------------------------------------------
// Extension definition
// ---------------------------------------------------------------------------

export default defineExtension({
  activate(api: ExtensionApi) {
    // =======================================================================
    // Capability 2 & 3: schema — custom item type, fields, and create flag
    // =======================================================================
    //
    // registerItemTypes adds a new type so `pm create --type incident`
    // stores items in the incidents/ folder with option enforcement.
    // registerItemFields declares backing field types.
    // registerFlags adds extra flags to existing built-in commands.

    api.registerItemTypes([
      {
        name: "Incident",
        folder: "incidents",
        aliases: ["incident", "inc"],
        required_create_fields: ["title", "severity"],
        options: [
          {
            key: "severity",
            values: ["critical", "major", "minor"],
            required: true,
          },
          {
            key: "service",
            values: ["api", "web", "worker"],
          },
        ],
      },
    ]);

    api.registerItemFields([
      { name: "severity", type: "string" },
      { name: "service", type: "string", optional: true },
    ]);

    // Add --severity and --service flags to `pm create`:
    //   pm create --type incident --title "DB down" --severity critical
    api.registerFlags("create", [
      {
        long: "--severity",
        value_name: "level",
        description: "Incident severity: critical | major | minor",
      },
      {
        long: "--service",
        value_name: "svc",
        description: "Affected service: api | web | worker",
      },
    ]);

    // =======================================================================
    // Capability 1: commands — `pm incident` custom command
    // =======================================================================
    //
    // CommandHandlerContext provides: command, args (string[]), options
    // (Record<string, unknown>), global, pm_root.
    // Use `options` for flag values. Read files via pm_root if needed.

    api.registerCommand({
      name: "incident",
      description: "Show a summary of active incidents",
      intent: "surface open incidents for standup or triage",
      examples: [
        "pm incident",
        "pm incident --severity critical",
        "pm incident --service api",
      ],
      flags: [
        {
          long: "--severity",
          value_name: "level",
          description: "Filter by severity: critical | major | minor",
        },
        {
          long: "--service",
          value_name: "svc",
          description: "Filter by service: api | web | worker",
        },
      ],

      async run(ctx: CommandHandlerContext) {
        const severityFilter = ctx.options["severity"] as string | undefined;
        const serviceFilter = ctx.options["service"] as string | undefined;

        // Read incidents from pm_root — .agents/pm/incidents/
        const incidentsDir = path.join(ctx.pm_root, "incidents");
        let files: string[] = [];
        try {
          files = await fs.readdir(incidentsDir);
        } catch {
          return { incidents: [], message: "No incidents directory found. Run `pm init` first." };
        }

        const incidents: Array<{ id: string; title: string; severity?: string; service?: string }> = [];

        for (const file of files.filter((f) => f.endsWith(".toon"))) {
          try {
            const content = await fs.readFile(path.join(incidentsDir, file), "utf-8");
            // Parse YAML front-matter (simple extraction — real code would use gray-matter or similar)
            const titleMatch = content.match(/^title:\s*(.+)$/m);
            const severityMatch = content.match(/^severity:\s*(.+)$/m);
            const serviceMatch = content.match(/^service:\s*(.+)$/m);
            const idMatch = content.match(/^id:\s*(.+)$/m);
            const statusMatch = content.match(/^status:\s*(.+)$/m);

            if (statusMatch?.[1]?.trim() === "closed" || statusMatch?.[1]?.trim() === "canceled") continue;

            const item = {
              id: idMatch?.[1]?.trim() ?? file.replace(".toon", ""),
              title: titleMatch?.[1]?.trim() ?? "(untitled)",
              severity: severityMatch?.[1]?.trim(),
              service: serviceMatch?.[1]?.trim(),
            };

            if (severityFilter && item.severity !== severityFilter) continue;
            if (serviceFilter && item.service !== serviceFilter) continue;

            incidents.push(item);
          } catch {
            // skip unreadable files
          }
        }

        // Sort: critical first, then major, then minor
        const order: Record<string, number> = { critical: 0, major: 1, minor: 2 };
        incidents.sort((a, b) => (order[a.severity ?? ""] ?? 9) - (order[b.severity ?? ""] ?? 9));

        return { incidents, count: incidents.length };
      },
    });

    // =======================================================================
    // Capability 4: importers — JSON fixture importer
    // =======================================================================
    //
    // ImportExportContext provides: registration, action, command, args,
    // options, global, pm_root.
    // Use options for user-supplied arguments, pm_root to locate the store.

    api.registerImporter(
      "incident-fixtures",
      async (ctx: ImportExportContext) => {
        const filePath = ctx.options["file"] as string | undefined;
        if (!filePath) {
          throw new Error(
            "incident-fixtures requires --file <path> — path to a JSON fixtures file."
          );
        }

        const resolved = path.resolve(filePath);
        let raw: string;
        try {
          raw = await fs.readFile(resolved, "utf-8");
        } catch {
          throw new Error(`Could not read fixtures file: ${resolved}`);
        }

        const fixtures: IncidentFixture[] = JSON.parse(raw);
        const incidentsDir = path.join(ctx.pm_root, "incidents");
        await fs.mkdir(incidentsDir, { recursive: true });

        let count = 0;
        for (const fixture of fixtures) {
          const id = fixture.id ?? `inc-${fixture.title.toLowerCase().replace(/\s+/g, "-").slice(0, 20)}`;
          const toon = [
            "---",
            `id: "${id}"`,
            `title: "${fixture.title}"`,
            `status: open`,
            `type: Incident`,
            `severity: ${fixture.severity}`,
            fixture.service ? `service: ${fixture.service}` : null,
            fixture.description ? `description: "${fixture.description}"` : null,
            `created_at: "${new Date().toISOString()}"`,
            "---",
            fixture.description ?? "",
          ]
            .filter((l): l is string => l !== null)
            .join("\n");

          await fs.writeFile(path.join(incidentsDir, `${id}.toon`), toon, "utf-8");
          count++;
        }

        return { count, message: `Imported ${count} incident(s) from ${resolved}` };
      }
    );

    // =======================================================================
    // Capability 5: hooks — beforeCommand / afterCommand lifecycle
    // =======================================================================
    //
    // BeforeCommandHookContext: command, args, options, global, pm_root
    // AfterCommandHookContext: ...BeforeCommandHookContext, ok, error?, result?
    // Hooks should be fast and not throw — errors are swallowed by the runtime.

    api.hooks.beforeCommand(async (ctx: BeforeCommandHookContext) => {
      // Example: log every pm command to a local audit file (fire-and-forget)
      const auditPath = path.join(ctx.pm_root, "incident-audit.log");
      const line = `${new Date().toISOString()} BEFORE ${ctx.command}\n`;
      fs.appendFile(auditPath, line).catch(() => {});
    });

    api.hooks.afterCommand(async (ctx: AfterCommandHookContext) => {
      const auditPath = path.join(ctx.pm_root, "incident-audit.log");
      const line = `${new Date().toISOString()} AFTER  ${ctx.command} ok=${ctx.ok}\n`;
      fs.appendFile(auditPath, line).catch(() => {});
    });

    // =======================================================================
    // Capability 6: renderers — toon renderer override
    // =======================================================================
    //
    // RendererOverride signature: (context: RendererOverrideContext) => string
    // context.result is the command result. context.format is "toon" or "json".
    // Return the formatted string. Return "" to pass through to the default.

    api.registerRenderer("toon", (ctx: RendererOverrideContext): string => {
      const result = ctx.result as Record<string, unknown> | null;
      if (
        result &&
        typeof result === "object" &&
        "incidents" in result &&
        Array.isArray(result.incidents)
      ) {
        const incidents = result.incidents as Array<{
          id: string;
          title: string;
          severity?: string;
          service?: string;
        }>;

        if (incidents.length === 0) {
          return "incidents:\n  count: 0\n  message: no open incidents";
        }

        const lines = [
          `incidents:`,
          `  count: ${incidents.length}`,
          `  items:`,
        ];
        for (const inc of incidents) {
          lines.push(`    - id: "${inc.id}"`);
          lines.push(`      title: "${inc.title}"`);
          if (inc.severity) lines.push(`      severity: ${inc.severity}`);
          if (inc.service) lines.push(`      service: ${inc.service}`);
        }
        return lines.join("\n");
      }

      // Return empty string to fall through to the default renderer.
      return "";
    });

    // =======================================================================
    // Capability 7: search — title-match search provider
    // =======================================================================
    //
    // SearchProviderQueryContext provides: query, mode, tokens, options,
    // settings, documents (ItemDocument[]).
    // Return SearchProviderHit[] with { id, score, matched_fields }.

    api.registerSearchProvider({
      name: "incident-search",
      async query(ctx: SearchProviderQueryContext): Promise<SearchProviderHit[]> {
        const q = ctx.query.toLowerCase();
        return ctx.documents
          .filter((doc) => {
            const type = (doc.metadata.type as string | undefined)?.toLowerCase() ?? "";
            const title = (doc.metadata.title as string | undefined)?.toLowerCase() ?? "";
            return type === "incident" && title.includes(q);
          })
          .map((doc) => ({
            id: doc.metadata.id as string,
            score: 0.75,
            matched_fields: ["title"],
          }));
      },
    });

    // =======================================================================
    // Capability 8: preflight — override preflight decision flags
    // =======================================================================
    //
    // PreflightOverrideContext: command, args, options, global, pm_root,
    //   decision: { enforce_item_format_gate, run_preflight_item_format_sync,
    //               run_extension_migrations, enforce_mandatory_migration_gate }
    // Return PreflightOverrideDelta to selectively override decision flags.
    // Return {} to leave all flags unchanged.

    api.registerPreflight(async (ctx: PreflightOverrideContext) => {
      // Example: skip format sync on read-only commands (list, get, search)
      const readOnlyCommands = new Set(["list", "get", "search", "context", "aggregate", "stats"]);
      if (readOnlyCommands.has(ctx.command)) {
        return { run_preflight_item_format_sync: false };
      }

      // Leave all other preflight flags at their defaults.
      return {};
    });

    // =======================================================================
    // Capability 9: services — help_format service override stub
    // =======================================================================
    //
    // ServiceOverrideContext: service (ExtensionServiceName), command?, args?,
    //   options?, global?, pm_root?, payload (the default service payload).
    // Return the new payload, or context.payload to pass through unchanged.
    //
    // Valid service names: output_format, error_format, help_format,
    //   lock_acquire, lock_release, history_append, item_store_write,
    //   item_store_delete.

    api.registerService("help_format", (ctx: ServiceOverrideContext) => {
      // Pass through to the default help formatter unchanged.
      // Replace this with custom logic to inject banners, extra sections, etc.
      return ctx.payload;
    });
  },
});