magic-spells 0.0.0-stage → 0.2.0

package/dist/src-L2I546M7.js

@@ -0,0 +1,1071 @@
+import {
+  mapPyramidHttpError,
+  operationsByName,
+  pyramidError,
+  toPyramidError
+} from "./chunk-PQFOO5A7.js";
+import {
+  MagicError,
+  TtlCache,
+  readField,
+  readStr
+} from "./chunk-JZ7XESF4.js";
+
+// ../pyramid/src/cache/resolver.ts
+var TTL_MS = 6e4;
+var PROJECTS_KEY = "projects";
+var Resolver = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Per-project workflow cache (also the hydration join source). */
+  workflows = new TtlCache(TTL_MS);
+  /** Workspace-wide project list cache (backs project-name resolution). */
+  projects = new TtlCache(TTL_MS);
+  // ---------- Workflow fetch + 60s cache ----------
+  /**
+   * Cached workflow for a project (60s TTL). One fetch warms every kind of
+   * resolution for that project. Backs `get_project_workflow` and hydration.
+   */
+  async getWorkflow(projectId) {
+    const hit = this.workflows.get(projectId);
+    if (hit) return hit;
+    const [rawWf, rawLabels, rawMembers, rawSchema] = await Promise.all([
+      this.client.getWorkflow(projectId),
+      this.client.listLabels(projectId),
+      this.client.listMembers(projectId),
+      this.client.getTaskSchema(projectId)
+    ]);
+    const wf = normalizeWorkflow(rawWf);
+    wf.labels = (Array.isArray(rawLabels) ? rawLabels : []).map(normalizeLabel);
+    wf.members = (Array.isArray(rawMembers) ? rawMembers : []).map(normalizeMember);
+    wf.templates = normalizeTaskSchema(rawSchema);
+    this.workflows.set(projectId, wf);
+    return wf;
+  }
+  // ---------- Project ----------
+  /** handle (ci exact) -> name (ci exact) -> unique fuzzy contains. */
+  async resolveProject(nameOrHandle) {
+    const projects = await this.getProjects();
+    const needle = norm(nameOrHandle);
+    const byHandle = projects.filter((p) => norm(p.handle) === needle);
+    const byName = projects.filter((p) => norm(p.name) === needle);
+    const fuzzy = projects.filter((p) => contains(p.handle, needle) || contains(p.name, needle));
+    const match = pick(
+      "project",
+      "ambiguous_project_name",
+      nameOrHandle,
+      [byHandle, byName, fuzzy],
+      (p) => p.handle
+    );
+    if (match) return match;
+    throw pyramidError("project_not_found", `No project matches "${nameOrHandle}".`, {
+      candidates: shortlist(
+        nameOrHandle,
+        projects.map((p) => p.handle)
+      )
+    });
+  }
+  // ---------- Status ----------
+  /**
+   * key (ci) -> name (ci) -> category (ci) -> stage-name (first status of that
+   * stage by position). Returns the full WorkflowStatus (carries stage_id).
+   */
+  async resolveStatus(projectId, q) {
+    const wf = await this.getWorkflow(projectId);
+    const needle = norm(q);
+    const byKey = wf.statuses.filter((s) => norm(s.key) === needle);
+    const byName = wf.statuses.filter((s) => norm(s.name) === needle);
+    const byCategory = wf.statuses.filter(
+      (s) => s.category !== void 0 && norm(s.category) === needle
+    );
+    let match = pick(
+      "status",
+      "ambiguous_status_name",
+      q,
+      [byKey, byName, byCategory],
+      (s) => s.name
+    );
+    if (!match) {
+      const stage = wf.stages.find((s) => norm(s.key) === needle || norm(s.name) === needle);
+      if (stage) {
+        const first = firstStatusOfStage(wf, stage.id);
+        if (first) match = first;
+      }
+    }
+    if (!match) {
+      const fuzzy = wf.statuses.filter((s) => contains(s.key, needle) || contains(s.name, needle));
+      match = pick("status", "ambiguous_status_name", q, [fuzzy], (s) => s.name);
+    }
+    if (match) return match;
+    throw pyramidError("status_not_found", `No status matches "${q}".`, {
+      candidates: shortlist(
+        q,
+        wf.statuses.map((s) => s.name)
+      )
+    });
+  }
+  // ---------- Stage ----------
+  /** key (ci) -> name (ci) -> category (ci) -> unique fuzzy contains. */
+  async resolveStage(projectId, q) {
+    const wf = await this.getWorkflow(projectId);
+    const needle = norm(q);
+    const byKey = wf.stages.filter((s) => norm(s.key) === needle);
+    const byName = wf.stages.filter((s) => norm(s.name) === needle);
+    const byCategory = wf.stages.filter(
+      (s) => s.category !== void 0 && norm(s.category) === needle
+    );
+    const fuzzy = wf.stages.filter((s) => contains(s.key, needle) || contains(s.name, needle));
+    const match = pick(
+      "stage",
+      "ambiguous_stage_name",
+      q,
+      [byKey, byName, byCategory, fuzzy],
+      (s) => s.name
+    );
+    if (match) return match;
+    throw pyramidError("stage_not_found", `No stage matches "${q}".`, {
+      candidates: shortlist(
+        q,
+        wf.stages.map((s) => s.name)
+      )
+    });
+  }
+  // ---------- User ----------
+  /** email (ci exact) -> display_name (ci exact) -> unique fuzzy contains. */
+  async resolveUser(projectId, q) {
+    const wf = await this.getWorkflow(projectId);
+    const needle = norm(q);
+    const byEmail = wf.members.filter((m) => norm(m.email) === needle);
+    const byName = wf.members.filter((m) => norm(m.display_name) === needle);
+    const fuzzy = wf.members.filter(
+      (m) => contains(m.email, needle) || contains(m.display_name, needle)
+    );
+    const match = pick(
+      "user",
+      "ambiguous_user_name",
+      q,
+      [byEmail, byName, fuzzy],
+      (m) => m.display_name
+    );
+    if (match) return match;
+    throw pyramidError("user_not_found", `No user matches "${q}".`, {
+      candidates: shortlist(
+        q,
+        wf.members.map((m) => m.display_name)
+      )
+    });
+  }
+  // ---------- Label ----------
+  /** name (ci exact) -> unique fuzzy contains. */
+  async resolveLabel(projectId, q) {
+    const wf = await this.getWorkflow(projectId);
+    const needle = norm(q);
+    const byName = wf.labels.filter((l) => norm(l.name) === needle);
+    const fuzzy = wf.labels.filter((l) => contains(l.name, needle));
+    const match = pick("label", "ambiguous_label_name", q, [byName, fuzzy], (l) => l.name);
+    if (match) return { id: match.id, name: match.name };
+    throw pyramidError("label_not_found", `No label matches "${q}".`, {
+      candidates: shortlist(
+        q,
+        wf.labels.map((l) => l.name)
+      )
+    });
+  }
+  // ---------- Invalidation ----------
+  /**
+   * Drop cached data after a mutating op. One getWorkflow warms every per-project
+   * kind, so any per-project kind invalidates the whole project workflow entry;
+   * `project` also clears the workspace-wide project list. With no `kind`, clear
+   * everything cached for the project.
+   */
+  invalidate(projectId, kind) {
+    if (kind === "project") {
+      this.projects.clear();
+      return;
+    }
+    this.workflows.delete(projectId);
+    if (kind === void 0 && (projectId === "" || projectId === "*")) {
+      this.projects.clear();
+    }
+  }
+  // ---------- Internal: project-list cache ----------
+  async getProjects() {
+    return this.projects.getOrLoad(
+      PROJECTS_KEY,
+      async () => extractArray(await this.client.listProjects()).map(normalizeProject)
+    );
+  }
+};
+function pick(_kind, ambiguousCode, query, tiers, label) {
+  for (const tier of tiers) {
+    if (tier.length === 1) return tier[0];
+    if (tier.length > 1) {
+      throw pyramidError(ambiguousCode, `"${query}" is ambiguous \u2014 ${tier.length} matches.`, {
+        candidates: dedupeStrings(tier.map(label))
+      });
+    }
+  }
+  return void 0;
+}
+function extractArray(body) {
+  if (Array.isArray(body)) return body;
+  if (body && typeof body === "object") {
+    const obj = body;
+    for (const key of ["data", "items", "results", "projects"]) {
+      const val = obj[key];
+      if (Array.isArray(val)) return val;
+    }
+  }
+  return [];
+}
+function rec(v) {
+  return v && typeof v === "object" ? v : {};
+}
+function str(v, fallback = "") {
+  return typeof v === "string" ? v : fallback;
+}
+function optStr(v) {
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+var PROJECT_ROLES = ["admin", "pm", "member", "viewer", "guest"];
+function projectRole(v) {
+  return PROJECT_ROLES.includes(str(v)) ? str(v) : "member";
+}
+function normalizeProject(raw) {
+  const p = rec(raw);
+  return {
+    id: str(p.id),
+    handle: str(p.handle),
+    name: str(p.name),
+    task_prefix: str(p.task_prefix),
+    role: projectRole(p.role),
+    archived: p.archived_at != null || p.archived === true
+  };
+}
+function normalizeStage(raw) {
+  const s = rec(raw);
+  const stage = {
+    id: str(s.id),
+    key: str(s.key),
+    name: str(s.name),
+    position: str(s.position)
+  };
+  const category = optStr(s.category);
+  if (category !== void 0) stage.category = category;
+  return stage;
+}
+function normalizeStatus(raw) {
+  const s = rec(raw);
+  const status = {
+    id: str(s.id),
+    key: str(s.key),
+    name: str(s.name),
+    stage_id: str(s.stage_id),
+    position: str(s.position)
+  };
+  const category = optStr(s.category);
+  if (category !== void 0) status.category = category;
+  return status;
+}
+function normalizeMember(raw) {
+  const m = rec(raw);
+  const u = rec(m.user);
+  const member = {
+    id: str(u.id) || str(m.user_id) || str(m.id),
+    display_name: str(u.display_name) || str(m.display_name),
+    email: str(u.email) || str(m.email),
+    role: str(m.role) || str(u.role)
+  };
+  const jobTitle = optStr(m.job_title) ?? optStr(u.job_title);
+  if (jobTitle !== void 0) member.job_title = jobTitle;
+  return member;
+}
+function normalizeTaskSchema(raw) {
+  const s = rec(raw);
+  const fieldsByTemplate = rec(s.fields_by_template);
+  const templates = Array.isArray(s.templates) ? s.templates : [];
+  return templates.map((t) => {
+    const tt = rec(t);
+    const id = str(tt.id);
+    const rawFields = fieldsByTemplate[id];
+    const fields = (Array.isArray(rawFields) ? rawFields : []).map(normalizeField);
+    return { id, name: str(tt.name), fields };
+  });
+}
+function normalizeLabel(raw) {
+  const l = rec(raw);
+  return { id: str(l.id), name: str(l.name), color: str(l.color) };
+}
+function normalizeField(raw) {
+  const f = rec(raw);
+  const field = {
+    id: str(f.id),
+    key: str(f.key),
+    name: str(f.name),
+    field_type: str(f.field_type)
+  };
+  if (Array.isArray(f.options)) {
+    field.options = f.options.filter((o) => typeof o === "string");
+  }
+  return field;
+}
+function normalizeWorkflow(raw) {
+  const w = rec(raw);
+  const rawStages = Array.isArray(w.stages) ? w.stages : [];
+  const stages = rawStages.map(normalizeStage);
+  let statuses;
+  if (Array.isArray(w.statuses)) {
+    statuses = w.statuses.map(normalizeStatus);
+  } else {
+    statuses = [];
+    for (const rawStage of rawStages) {
+      const s = rec(rawStage);
+      const nested = Array.isArray(s.statuses) ? s.statuses : [];
+      const stageId = str(s.id);
+      for (const ns of nested) {
+        const status = normalizeStatus(ns);
+        if (status.stage_id === "") status.stage_id = stageId;
+        statuses.push(status);
+      }
+    }
+  }
+  const labels = (Array.isArray(w.labels) ? w.labels : []).map(normalizeLabel);
+  const members = (Array.isArray(w.members) ? w.members : []).map(normalizeMember);
+  const templates = (Array.isArray(w.templates) ? w.templates : []).map((t) => {
+    const tt = rec(t);
+    return {
+      id: str(tt.id),
+      name: str(tt.name),
+      fields: (Array.isArray(tt.fields) ? tt.fields : []).map(normalizeField)
+    };
+  });
+  return {
+    project: normalizeProject(w.project),
+    stages,
+    statuses,
+    labels,
+    members,
+    templates
+  };
+}
+function firstStatusOfStage(wf, stageId) {
+  const inStage = wf.statuses.filter((s) => s.stage_id === stageId);
+  if (inStage.length === 0) return void 0;
+  return [...inStage].sort(
+    (a, b) => a.position < b.position ? -1 : a.position > b.position ? 1 : 0
+  )[0];
+}
+function norm(s) {
+  return s.trim().toLowerCase();
+}
+function contains(haystack, normNeedle) {
+  if (normNeedle.length === 0) return false;
+  return haystack.trim().toLowerCase().includes(normNeedle);
+}
+function dedupeStrings(xs) {
+  return [...new Set(xs.filter((x) => x.length > 0))];
+}
+function shortlist(query, candidates) {
+  const q = norm(query);
+  const pool = dedupeStrings(candidates);
+  if (pool.length === 0) return [];
+  const scored = pool.map((c) => {
+    const cn = norm(c);
+    const sub = cn.includes(q) || q.length > 0 && q.includes(cn) ? 0 : 1;
+    return { c, sub, dist: levenshtein(q, cn) };
+  });
+  scored.sort((a, b) => a.sub - b.sub || a.dist - b.dist || a.c.localeCompare(b.c));
+  return scored.slice(0, 8).map((s) => s.c);
+}
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let curr = new Array(b.length + 1);
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+// ../pyramid/src/client/pyramid-client.ts
+import { request as undiciRequest } from "undici";
+var PyramidClient = class {
+  baseUrl;
+  apiKey;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.endsWith("/") ? config.baseUrl.slice(0, -1) : config.baseUrl;
+    this.apiKey = config.apiKey;
+  }
+  // ---- Phase-1 read-only surface (raw server JSON; hydration is elsewhere) ----
+  /**
+   * GET /v1/me — the authenticated user (raw `model.User`). The payload may carry
+   * a workspace in a future revision, so callers read it defensively; today it is
+   * just the user record. Returned raw.
+   */
+  getMe() {
+    return this.request("GET", "/v1/me");
+  }
+  /**
+   * GET /v1/workspaces — the caller's workspaces. The API key is workspace-pinned,
+   * so this is effectively a single-element list (the op layer takes `[0]` as the
+   * pinned workspace). Server shape is `{ data: Workspace[] }`; we unwrap to the
+   * array and tolerate a bare array.
+   */
+  listWorkspaces() {
+    return this.request("GET", "/v1/workspaces").then(unwrapData);
+  }
+  /**
+   * GET /v1/projects — accessible projects. Server shape is
+   * `{ data: Project[], cursor }`; we unwrap `data` (tolerating a bare array).
+   * First-page discovery only — Phase-1 needs no pagination here.
+   */
+  listProjects() {
+    return this.request("GET", "/v1/projects").then(unwrapData);
+  }
+  /**
+   * GET /v1/projects/{id}/workflow — the project's workflow (stages, statuses,
+   * labels, members, templates). Returned raw; the Resolver/hydrate layer joins
+   * it. `projectId` must already be a UUID (name->id resolution lives upstream).
+   */
+  getWorkflow(projectId) {
+    return this.request("GET", `/v1/projects/${encodeURIComponent(projectId)}/workflow`);
+  }
+  /**
+   * GET /v1/me/tasks — the tasks the caller OWNS or REVIEWS, across projects,
+   * newest first, with an opaque keyset cursor. Returns the raw `{ data, cursor }`
+   * envelope (cursor normalized to `string | null`). `limit` caps the page;
+   * `cursor` continues a prior page.
+   *
+   * There is deliberately NO `role` parameter: the server accepts `?role=` and
+   * IGNORES it (DOC-BACKEND-CONTRACT), so sending it would promise a narrowing
+   * that never happens.
+   */
+  async listMyTasks(opts) {
+    const envelope = await this.request("GET", "/v1/me/tasks", {
+      query: {
+        limit: opts?.limit,
+        cursor: opts?.cursor
+      }
+    });
+    return {
+      data: Array.isArray(envelope?.data) ? envelope.data : [],
+      cursor: typeof envelope?.cursor === "string" ? envelope.cursor : null
+    };
+  }
+  // ---- Phase-2 task read surface (raw server JSON; hydration is elsewhere) ----
+  /**
+   * GET /v1/projects/{id}/tasks — a project's tasks, newest first, with an opaque
+   * keyset cursor. Returns the raw `{ data, cursor }` envelope (cursor normalized
+   * to `string | null`). All filter values are already-resolved UUIDs (`status` is
+   * a status UUID, plus `stage_id`/`owner_id`/`reviewer_id`/`label_id`) or free
+   * text (`q`); `expand` opts relations into the rows. `projectId` must already be
+   * a UUID. (Real query names per DOC-BACKEND-CONTRACT — no `assignee_id`.)
+   */
+  async listTasks(projectId, opts) {
+    const envelope = await this.request(
+      "GET",
+      `/v1/projects/${encodeURIComponent(projectId)}/tasks`,
+      {
+        query: {
+          status: opts?.status,
+          stage_id: opts?.stage_id,
+          owner_id: opts?.owner_id,
+          reviewer_id: opts?.reviewer_id,
+          label_id: opts?.label_id,
+          q: opts?.q,
+          limit: opts?.limit,
+          cursor: opts?.cursor,
+          expand: opts?.expand
+        }
+      }
+    );
+    return normalizeCursorEnvelope(envelope);
+  }
+  /**
+   * GET /v1/projects/{id}/tasks/archived — a project's ARCHIVED tasks (a separate
+   * route from `listTasks`). Returns the raw `{ data, cursor }` envelope. `opts`
+   * carries `archived_after`/`limit`/`cursor`. `projectId` must already be a UUID.
+   */
+  async listArchived(projectId, opts) {
+    const envelope = await this.request(
+      "GET",
+      `/v1/projects/${encodeURIComponent(projectId)}/tasks/archived`,
+      {
+        query: {
+          archived_after: opts?.archived_after,
+          limit: opts?.limit,
+          cursor: opts?.cursor
+        }
+      }
+    );
+    return normalizeCursorEnvelope(envelope);
+  }
+  /**
+   * GET /v1/projects/{id}/labels — a project's labels (separate from /workflow).
+   * Returns a bare array of raw label rows (tolerating a `{ data }` envelope).
+   */
+  listLabels(projectId) {
+    return this.request(
+      "GET",
+      `/v1/projects/${encodeURIComponent(projectId)}/labels`
+    ).then(unwrapData);
+  }
+  /**
+   * GET /v1/projects/{id}/members — a project's members (separate from /workflow).
+   * Returns a bare array of raw `ProjectMember` rows (each carries `user`).
+   */
+  listMembers(projectId) {
+    return this.request(
+      "GET",
+      `/v1/projects/${encodeURIComponent(projectId)}/members`
+    ).then(unwrapData);
+  }
+  /**
+   * GET /v1/projects/{id}/task-schema — the project's custom-field schema. Returns
+   * the raw `{ templates, fields_by_template }` payload (the Resolver merges it
+   * into the cached Workflow shape).
+   */
+  getTaskSchema(projectId) {
+    return this.request(
+      "GET",
+      `/v1/projects/${encodeURIComponent(projectId)}/task-schema`
+    );
+  }
+  /**
+   * GET /v1/tasks/{id}/timeline — one page of a task's history, **oldest first**
+   * (the reverse of every other list here). Returns the raw `{ data, cursor }`
+   * envelope. `limit` defaults to 50 server-side and is capped at 200;
+   * `event_type` narrows to one kind (e.g. `owner_changed`). No If-Match.
+   */
+  async getTaskTimeline(taskId, opts) {
+    const envelope = await this.request(
+      "GET",
+      `/v1/tasks/${encodeURIComponent(taskId)}/timeline`,
+      {
+        query: {
+          limit: opts?.limit,
+          cursor: opts?.cursor,
+          event_type: opts?.event_type
+        }
+      }
+    );
+    return normalizeCursorEnvelope(envelope);
+  }
+  /**
+   * GET /v1/tasks/{id} — one task's full detail (raw `RawTaskDetail`). A non-empty
+   * `expand` enables relations (editor/timeline/comments/estimates/followers/…);
+   * omit it for the lean shape. `taskId` must already be a UUID.
+   */
+  getTask(taskId, expand) {
+    return this.request("GET", `/v1/tasks/${encodeURIComponent(taskId)}`, {
+      query: { expand }
+    });
+  }
+  /**
+   * GET /v1/search/tasks — full-text task search across the workspace. Returns the
+   * raw `{ data }` envelope (no cursor per DOC-BACKEND-CONTRACT; normalized to a
+   * null cursor). `q` is the query; the optional filters are already-resolved user
+   * UUIDs.
+   */
+  async searchTasks(opts) {
+    const envelope = await this.request("GET", "/v1/search/tasks", {
+      query: {
+        q: opts.q,
+        owner_id: opts.owner_id,
+        reviewer_id: opts.reviewer_id,
+        limit: opts.limit
+      }
+    });
+    return normalizeCursorEnvelope(envelope);
+  }
+  // ---- Phase-2 task write surface (raw server JSON; resolution is elsewhere) ----
+  /**
+   * POST /v1/projects/{id}/tasks — create one task. `body` is the already-resolved
+   * create payload (status_id/owner_id/label_ids/…); this client does no name
+   * resolution. Returns the raw `RawTaskDetail` of the created task.
+   */
+  createTask(projectId, body) {
+    return this.request("POST", `/v1/projects/${encodeURIComponent(projectId)}/tasks`, {
+      body
+    });
+  }
+  /**
+   * POST /v1/tasks/bulk — create many tasks. `body` is the resolved
+   * `{ project_id, template_id, tasks: [...] }` batch. The server replies
+   * `{ created: [Task], errors: [] }`; this returns the RAW envelope (the op
+   * hydrates `created`). No If-Match.
+   */
+  bulkCreate(body) {
+    return this.request("POST", "/v1/tasks/bulk", { body });
+  }
+  /**
+   * PATCH /v1/tasks/{id} — sparse update of a task's content (title/description/
+   * priority/dates/estimate/guest_visible) AND its `owner_id`/`reviewer_id` (an explicit
+   * null clears one). `body` still carries NO labels and NO field_values — those
+   * keep their dedicated endpoints. Requires If-Match
+   * (DOC-CONCURRENCY): GET first to capture the ETag, send it, retry ONCE on 409.
+   * Returns the raw updated `RawTaskDetail`.
+   */
+  updateTask(taskId, body) {
+    return this.withPrecondition(
+      taskId,
+      (etag) => this.request("PATCH", `/v1/tasks/${encodeURIComponent(taskId)}`, {
+        body,
+        headers: { "if-match": etag }
+      })
+    );
+  }
+  /**
+   * PATCH /v1/tasks/{id}/move — change a task's status (which carries its stage)
+   * and/or its position via neighbor ids. `body` is
+   * `{ status_id, before_id?, after_id? }` — already-resolved UUIDs; positions are
+   * server-generated, never a fractional key. The server replies an ENVELOPE
+   * `{ task, previous }`; this returns it raw (the op hydrates `raw.task`). No
+   * If-Match.
+   */
+  moveTask(taskId, body) {
+    return this.request("PATCH", `/v1/tasks/${encodeURIComponent(taskId)}/move`, { body });
+  }
+  /**
+   * POST /v1/tasks/{id}/labels — add a label to an existing task. `labelId` is an
+   * already-resolved label UUID. No If-Match. Returns the raw response.
+   */
+  addTaskLabel(taskId, labelId) {
+    return this.request("POST", `/v1/tasks/${encodeURIComponent(taskId)}/labels`, {
+      body: { label_id: labelId }
+    });
+  }
+  /**
+   * DELETE /v1/tasks/{id}/labels/{labelId} — remove a label from a task. Both ids
+   * are already-resolved UUIDs. No If-Match. Resolves to void (204).
+   */
+  async removeTaskLabel(taskId, labelId) {
+    await this.request(
+      "DELETE",
+      `/v1/tasks/${encodeURIComponent(taskId)}/labels/${encodeURIComponent(labelId)}`
+    );
+  }
+  /**
+   * PATCH /v1/tasks/{id}/field-values — bulk-set a task's custom-field values.
+   * `body` is `{ field_values: { <fieldId>: value } }` keyed by field UUID. No
+   * If-Match. Returns the raw response.
+   */
+  setFieldValues(taskId, body) {
+    return this.request("PATCH", `/v1/tasks/${encodeURIComponent(taskId)}/field-values`, {
+      body
+    });
+  }
+  /**
+   * POST /v1/tasks/{id}/archive — soft-archive a task (reversible via the op's
+   * `unarchiveTask`). Returns the raw updated `RawTaskDetail`.
+   */
+  archiveTask(taskId) {
+    return this.request("POST", `/v1/tasks/${encodeURIComponent(taskId)}/archive`);
+  }
+  /**
+   * POST /v1/tasks/{id}/unarchive — restore a soft-archived task. Returns the raw
+   * updated `RawTaskDetail`. (The `task.archive` op picks archive vs unarchive.)
+   */
+  unarchiveTask(taskId) {
+    return this.request("POST", `/v1/tasks/${encodeURIComponent(taskId)}/unarchive`);
+  }
+  /**
+   * DELETE /v1/tasks/{id} — delete a task. `hard=true` requests a hard delete
+   * (the destructive op gates this upstream behind MAGIC_ALLOW_DESTRUCTIVE).
+   * Requires If-Match (DOC-CONCURRENCY): GET first to capture the ETag, send it,
+   * retry ONCE on 409. The server replies 204; resolves to void.
+   */
+  async deleteTask(taskId, hard) {
+    await this.withPrecondition(
+      taskId,
+      (etag) => this.request("DELETE", `/v1/tasks/${encodeURIComponent(taskId)}`, {
+        query: { hard },
+        headers: { "if-match": etag }
+      })
+    );
+  }
+  // ---- Phase-2 comment surface (raw server JSON; resolution is elsewhere) ----
+  /**
+   * GET /v1/tasks/{id}/comments — a task's comments, stage-scoped. Returns the raw
+   * `{ data, cursor }` envelope. `stage_id` (already a UUID) narrows to one stage;
+   * omit it to read across stages.
+   */
+  async listComments(taskId, opts) {
+    const envelope = await this.request(
+      "GET",
+      `/v1/tasks/${encodeURIComponent(taskId)}/comments`,
+      {
+        query: {
+          stage_id: opts?.stage_id,
+          limit: opts?.limit,
+          cursor: opts?.cursor
+        }
+      }
+    );
+    return normalizeCursorEnvelope(envelope);
+  }
+  /**
+   * POST /v1/tasks/{id}/comments — add a root (stage-scoped) comment. `body` is
+   * `{ content, stage_id?, mention_user_ids? }` with already-resolved mention
+   * UUIDs; `stage_id` defaults to the task's current stage upstream. Returns the
+   * raw `RawComment`.
+   */
+  addComment(taskId, body) {
+    return this.request("POST", `/v1/tasks/${encodeURIComponent(taskId)}/comments`, {
+      body
+    });
+  }
+  /**
+   * GET /v1/comments/{id} — one comment (raw `RawComment`). The `comment.reply`
+   * op fetches the target to verify it is a ROOT comment (`parent_id` /
+   * `thread_root_id` null) BEFORE replying, enforcing the one-level rule. Returned
+   * raw; resolution/hydration is elsewhere. `commentId` must already be a UUID.
+   */
+  getComment(commentId) {
+    return this.request("GET", `/v1/comments/${encodeURIComponent(commentId)}`);
+  }
+  /**
+   * POST /v1/comments/{id}/replies — reply to a ROOT comment (one level only; the
+   * op rejects reply-to-reply before this call). `body` is
+   * `{ content, mention_user_ids? }` with already-resolved mention UUIDs. Returns
+   * the raw `RawComment`.
+   */
+  replyComment(commentId, body) {
+    return this.request("POST", `/v1/comments/${encodeURIComponent(commentId)}/replies`, {
+      body
+    });
+  }
+  // ---------------------------- core request ----------------------------
+  /**
+   * Issue one authenticated JSON request and return the parsed body as `T`.
+   *
+   * - Sets Bearer auth + `Accept: application/json` (and `Content-Type` for a body).
+   * - 2xx: returns the parsed JSON (an empty/204 body parses to `undefined`).
+   * - non-2xx: parses the `{ error: { code, message } }` envelope (best effort)
+   *   and throws `mapPyramidHttpError(status, body)`.
+   * - undici/transport failure (DNS, connect, reset, timeout): throws
+   *   `MagicError('network', ...)` via `toPyramidError`.
+   *
+   * The API key is on the header only — never logged, never in the URL.
+   */
+  async request(method, path, opts) {
+    return (await this.requestWithETag(method, path, opts)).body;
+  }
+  /**
+   * The transport core, also returning the response's `ETag` header (null when
+   * absent). `request<T>()` is the body-only sugar over this; the If-Match
+   * read-first flow reads the etag here (DOC-CONCURRENCY).
+   */
+  async requestWithETag(method, path, opts) {
+    const url = this.buildUrl(path, opts?.query);
+    const headers = {
+      authorization: `Bearer ${this.apiKey}`,
+      accept: "application/json"
+    };
+    let bodyText;
+    if (opts?.body !== void 0) {
+      bodyText = JSON.stringify(opts.body);
+      headers["content-type"] = "application/json";
+    }
+    if (opts?.headers) {
+      for (const [k, v] of Object.entries(opts.headers)) headers[k] = v;
+    }
+    let status;
+    let raw;
+    let etag;
+    try {
+      const res = await undiciRequest(url, {
+        method,
+        headers,
+        body: bodyText
+      });
+      status = res.statusCode;
+      etag = readETagHeader(res.headers);
+      raw = await res.body.text();
+    } catch (err) {
+      const mapped = toPyramidError(err);
+      throw mapped.code === "network" ? mapped : pyramidError("network", mapped.message, {
+        hint: "Check MAGIC_PYRAMID_URL and your network connection."
+      });
+    }
+    const parsed = safeJsonParse(raw);
+    if (status < 200 || status >= 300) {
+      throw mapPyramidHttpError(status, parsed);
+    }
+    return { body: parsed, etag };
+  }
+  /**
+   * Capture the current ETag for a task (DOC-CONCURRENCY): GET /v1/tasks/{id} and
+   * read its `ETag` response header, falling back to the body's `updated_at` when
+   * the header is absent. Used by the If-Match read-first flow.
+   */
+  async getTaskETag(taskId) {
+    const res = await this.requestWithETag(
+      "GET",
+      `/v1/tasks/${encodeURIComponent(taskId)}`
+    );
+    if (res.etag) return res.etag;
+    const body = res.body;
+    if (body && typeof body === "object") {
+      const updatedAt = body.updated_at;
+      if (typeof updatedAt === "string" && updatedAt.length > 0) return updatedAt;
+    }
+    return "";
+  }
+  /**
+   * Run an If-Match-guarded mutation (PATCH update / DELETE) with the read-first
+   * flow (DOC-CONCURRENCY): GET to capture the ETag, run `fn(etag)`, and on a 409
+   * `conflict` refetch the ETag and retry ONCE before surfacing the conflict.
+   */
+  async withPrecondition(taskId, fn) {
+    const etag = await this.getTaskETag(taskId);
+    try {
+      return await fn(etag);
+    } catch (err) {
+      if (err instanceof MagicError && err.code === "conflict") {
+        const fresh = await this.getTaskETag(taskId);
+        return fn(fresh);
+      }
+      throw err;
+    }
+  }
+  /** Build an absolute URL, appending defined query params (skips null/undefined). */
+  buildUrl(path, query) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value === void 0 || value === null) continue;
+        url.searchParams.set(key, String(value));
+      }
+    }
+    return url.toString();
+  }
+};
+function readETagHeader(headers) {
+  const value = headers.etag ?? headers.ETag;
+  if (Array.isArray(value)) return value[0] ?? null;
+  return typeof value === "string" ? value : null;
+}
+function unwrapData(body) {
+  if (Array.isArray(body)) return body;
+  if (body && typeof body === "object" && "data" in body) {
+    const data = body.data;
+    if (Array.isArray(data)) return data;
+  }
+  return [];
+}
+function normalizeCursorEnvelope(envelope) {
+  return {
+    data: Array.isArray(envelope?.data) ? envelope.data : [],
+    cursor: typeof envelope?.cursor === "string" ? envelope.cursor : null
+  };
+}
+function safeJsonParse(text) {
+  if (text.trim() === "") return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+
+// ../pyramid/src/credential.ts
+var PYRAMID_CREDENTIAL = {
+  id: "pyramid",
+  title: "Pyramid",
+  credential: "pyramid_",
+  keyHelp: "Pyramid \u2192 Settings \u2192 API Keys"
+};
+var DEFAULT_API_URL = "https://api.pyramid.magicspells.io";
+
+// ../pyramid/src/doctor.ts
+var whoamiOp = async () => (await import("./operations-GGMLIYEW.js")).operationsByName.get("pyramid.whoami");
+var doctorChecks = [
+  {
+    name: "pyramid auth",
+    async run(ctx) {
+      const me = await (await whoamiOp()).run({}, ctx);
+      const name = me.user.display_name || "(unknown user)";
+      const user = me.user.email ? `${name} <${me.user.email}>` : name;
+      const workspace = me.workspace.name || "(workspace)";
+      const names = me.projects.map((p) => p.name || p.handle).filter((n) => n.length > 0);
+      return {
+        ok: true,
+        detail: `Authenticated as ${user} \xB7 workspace ${workspace} \xB7 ${names.length} project${names.length === 1 ? "" : "s"}` + (names.length ? `: ${names.join(", ")}` : ""),
+        data: {
+          user: { name, email: me.user.email || null },
+          workspace: { name: workspace },
+          projects: names
+        }
+      };
+    }
+  },
+  {
+    name: "pyramid workflow",
+    async run(ctx) {
+      const projects = await ctx.client.api.listProjects();
+      const id = readStr(readField(projects[0], "id"));
+      if (!id) return { ok: true, detail: "No projects; workflow endpoint not checked." };
+      await ctx.client.resolver.getWorkflow(id);
+      return { ok: true, detail: "Workflow endpoint: OK." };
+    }
+  }
+];
+
+// ../pyramid/src/mcp/prompts.ts
+var DOCTOR_DESCRIPTION = "Check your Pyramid setup: confirm the API key authenticates and show the user, workspace, and accessible projects.";
+var DOCTOR_INSTRUCTION = [
+  "Run a Pyramid setup check.",
+  "",
+  "Call the `pyramid_whoami` tool, then report back, in plain language:",
+  "  \u2022 the authenticated user (display name and email),",
+  "  \u2022 the workspace (name) you are connected to, and",
+  "  \u2022 the accessible projects (names).",
+  "",
+  "Finish by confirming the setup looks good. If `pyramid_whoami` returns an error,",
+  "act on its `code`: for an `auth_*` code, tell the user to regenerate their",
+  "key in Pyramid \u2192 Settings \u2192 API Keys. Never print raw JSON or an HTTP status."
+].join("\n");
+function registerPrompts(server) {
+  server.registerPrompt("pyramid_doctor", { description: DOCTOR_DESCRIPTION }, () => ({
+    messages: [
+      {
+        role: "user",
+        content: { type: "text", text: DOCTOR_INSTRUCTION }
+      }
+    ]
+  }));
+}
+
+// ../pyramid/src/mcp/resources.ts
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+function op(name) {
+  const found = operationsByName.get(name);
+  if (!found) throw new Error(`missing operation ${name}`);
+  return found;
+}
+async function renderOp(op2, context) {
+  try {
+    const input = op2.input.parse({});
+    const result = await op2.run(input, await context());
+    return JSON.stringify(result, null, 2);
+  } catch (err) {
+    return JSON.stringify({ error: toPyramidError(err).toJSON() }, null, 2);
+  }
+}
+function registerResources(server, context) {
+  server.registerResource(
+    "pyramid_me",
+    "pyramid://me",
+    {
+      title: "Pyramid identity",
+      description: "The authenticated user, their workspace, and accessible projects (whoami).",
+      mimeType: "application/json"
+    },
+    async (uri) => {
+      const text = await renderOp(op("pyramid.whoami"), context);
+      return {
+        contents: [{ uri: uri.href, mimeType: "application/json", text }]
+      };
+    }
+  );
+  server.registerResource(
+    "pyramid_projects",
+    "pyramid://projects",
+    {
+      title: "Pyramid projects",
+      description: "The projects accessible to the authenticated user.",
+      mimeType: "application/json"
+    },
+    async (uri) => {
+      const text = await renderOp(op("pyramid.project.list"), context);
+      return {
+        contents: [{ uri: uri.href, mimeType: "application/json", text }]
+      };
+    }
+  );
+  server.registerResource(
+    "pyramid_project_workflow",
+    new ResourceTemplate("pyramid://projects/{handle}/workflow", { list: void 0 }),
+    {
+      title: "Project workflow",
+      description: "A project's stages, statuses, labels, members, and field templates, by handle.",
+      mimeType: "application/json"
+    },
+    async (uri, variables) => {
+      const raw = variables.handle;
+      const handle = Array.isArray(raw) ? raw[0] : raw;
+      const workflow = op("pyramid.project.workflow");
+      let text;
+      if (handle) {
+        try {
+          const result = await workflow.run(
+            workflow.input.parse({ project: handle }),
+            await context()
+          );
+          text = JSON.stringify(result, null, 2);
+        } catch (err) {
+          text = JSON.stringify({ error: toPyramidError(err).toJSON() }, null, 2);
+        }
+      } else {
+        text = JSON.stringify(
+          {
+            error: {
+              code: "validation_failed",
+              message: "missing project handle",
+              product: "pyramid"
+            }
+          },
+          null,
+          2
+        );
+      }
+      return {
+        contents: [{ uri: uri.href, mimeType: "application/json", text }]
+      };
+    }
+  );
+}
+
+// ../pyramid/src/mcp/index.ts
+var instructions = (version) => `Pyramid MCP v${version} \u2014 drive the Pyramid project tracker. Rules: (1) You act as one user in ONE workspace (the key is workspace-pinned). (2) Inputs accept names/keys, not UUIDs; outputs are already hydrated to names. (3) RENDER tasks as a left-rail card, one field per line, no JSON: \`\u2502 <KEY>\` / \`\u2502 NAME: <title>\` / \`\u2502 DESCRIPTION: <one line; truncate in lists>\` / \`\u2502 <Stage>: <Status>\` \u2014 always show stage and status together as \`Stage: Status\`. (4) For a LIST ("get my work"), render one card per task SEPARATED BY A BLANK LINE so each reads as a distinct ticket \u2014 never let cards run together \u2014 with one-line descriptions; show the page, then say "showing N of M \u2014 ask for more"; NEVER auto-paginate. Full description + drill-in only for a single task. (5) Drill-in (comments, git PRs/commits) only when asked, for the named task. (6) Dates are UTC \u2014 render UTC-labeled or relative-with-label, never bare local. (7) On error, act on the \`code\` (don't parse the message): \`ambiguous_*\` \u2192 show candidates and ask; \`auth_*\` \u2192 tell the user to regenerate their key in Pyramid \u2192 Settings \u2192 API Keys. Never print raw JSON or an HTTP status to the user.`;
+function registerPyramidMcp(server, context) {
+  registerResources(server, context);
+  registerPrompts(server);
+}
+
+// ../pyramid/src/index.ts
+var pyramid = {
+  ...PYRAMID_CREDENTIAL,
+  apiUrl: DEFAULT_API_URL,
+  // `magic login` mints workspace keys here from the Account grant (API-PYRAMID-CLI-SESSIONS).
+  sessions: { path: "/v1/cli/sessions" },
+  // The operations graph loads only when a Pyramid command runs.
+  load: async () => (await import("./operations-GGMLIYEW.js")).operations,
+  client(session, config) {
+    const api = new PyramidClient({
+      apiKey: session.key,
+      baseUrl: config.products.pyramid.apiUrl
+    });
+    return { api, resolver: new Resolver(api) };
+  },
+  // `--project` stays a Pyramid flag, usable anywhere in argv (pyramid-cli's global).
+  globalFlags: ["project"],
+  doctor: doctorChecks,
+  mcp: { instructions, register: registerPyramidMcp }
+};
+var src_default = pyramid;
+export {
+  DEFAULT_API_URL,
+  PYRAMID_CREDENTIAL,
+  src_default as default,
+  pyramid
+};