magic-spells 0.0.0-stage → 0.2.0

package/dist/chunk-PQFOO5A7.js

@@ -0,0 +1,1057 @@
+import {
+  MagicError,
+  mapHttpError,
+  readStr,
+  rec,
+  toMagicError
+} from "./chunk-JZ7XESF4.js";
+
+// ../pyramid/src/operations/index.ts
+import { z } from "zod";
+
+// ../pyramid/src/errors.ts
+var PRODUCT = "pyramid";
+var REGENERATE_KEY_HINT = "Regenerate your key in Pyramid \u2192 Settings \u2192 API Keys.";
+var NETWORK_HINT = "Check MAGIC_PYRAMID_URL and your network connection.";
+var NOT_FOUND_KINDS = ["project", "task", "status", "stage", "label", "user", "field"];
+function pyramidError(code, message, opts = {}) {
+  const [mapped, extra] = translate(code);
+  const details = extra || opts.details ? { ...opts.details, ...extra } : void 0;
+  return new MagicError(mapped, message, {
+    ...opts,
+    product: PRODUCT,
+    ...details ? { details } : {}
+  });
+}
+function translate(code) {
+  const notFound = /^(\w+)_not_found$/.exec(code);
+  if (notFound && code !== "not_found") return ["not_found", { kind: notFound[1] }];
+  const ambiguous = /^ambiguous_(\w+)_name$/.exec(code);
+  if (ambiguous) return ["ambiguous_name", { kind: ambiguous[1] }];
+  switch (code) {
+    case "status_not_in_stage":
+    case "invalid_field_value":
+    case "reply_depth_exceeded":
+    case "task_archived":
+      return ["validation_failed", { reason: code }];
+    default:
+      return [code];
+  }
+}
+function mapPyramidHttpError(status, body) {
+  return mapHttpError(status, body, {
+    product: PRODUCT,
+    title: "Pyramid",
+    authHint: REGENERATE_KEY_HINT,
+    notFoundKinds: NOT_FOUND_KINDS
+  });
+}
+function toPyramidError(e) {
+  return toMagicError(e, { product: PRODUCT, networkHint: NETWORK_HINT });
+}
+
+// ../pyramid/src/hydrate.ts
+function hydrateTaskSummary(raw, workflow) {
+  const r = obj(raw);
+  const statusId = statusIdOf(r);
+  return {
+    id: str(r.id),
+    key: str(r.key),
+    title: str(r.title),
+    description: nullableStr(r.description),
+    status: statusRef(workflow, statusId),
+    stage: stageRefForStatus(workflow, statusId, r),
+    owner: ownerStub(workflow, r.owner, r.owner_id),
+    reviewer: ownerStub(workflow, r.reviewer, r.reviewer_id),
+    labels: labelNames(workflow, r.labels ?? r.label_ids),
+    archived: r.archived_at != null || r.archived === true,
+    updated_at: str(r.updated_at)
+  };
+}
+function hydrateTaskDetail(raw, workflow) {
+  const r = obj(raw);
+  const detail = hydrateTaskSummary(raw, workflow);
+  detail.description = nullableStr(r.description);
+  if (Array.isArray(r.field_values)) {
+    detail.field_values = r.field_values.map((fv) => {
+      const f = obj(fv);
+      return {
+        // Join a custom-field id to its name where possible (no bare UUID).
+        field: fieldName(workflow, f.field ?? f.field_id ?? f.key),
+        value: f.value
+      };
+    });
+  }
+  if (r.estimates && typeof r.estimates === "object") {
+    const e = obj(r.estimates);
+    detail.estimates = {
+      total_hours: num(e.total_hours),
+      by_stage: byStageNames(workflow, e.by_stage)
+    };
+  }
+  if (Array.isArray(r.comments)) {
+    detail.comments = r.comments.map((c) => hydrateComment(c, workflow));
+  }
+  if (Array.isArray(r.references)) {
+    detail.references = r.references.map(hydrateReference);
+  }
+  if (Array.isArray(r.followers)) {
+    detail.followers = r.followers.map((f) => userStubFromAny(workflow, f)).filter((u) => u !== null);
+  }
+  if (Array.isArray(r.dependencies)) {
+    detail.dependencies = r.dependencies.map((d) => {
+      const dep = obj(d);
+      return { id: str(dep.id), key: str(dep.key), type: str(dep.type) };
+    });
+  }
+  return detail;
+}
+function hydrateComment(raw, workflow) {
+  const c = obj(raw);
+  const replies = (Array.isArray(c.replies) ? c.replies : []).map(
+    (r) => hydrateReply(r, workflow)
+  );
+  return {
+    id: str(c.id),
+    task_id: str(c.task_id),
+    stage: stageRef(workflow, str(c.stage_id)),
+    author: authorStub(workflow, c.author, c.author_id),
+    content: str(c.content),
+    mentions: mentionStubs(workflow, c.mentions),
+    replies,
+    created_at: str(c.created_at)
+  };
+}
+function hydrateReply(raw, workflow) {
+  const c = obj(raw);
+  return {
+    id: str(c.id),
+    task_id: str(c.task_id),
+    stage: stageRef(workflow, str(c.stage_id)),
+    author: authorStub(workflow, c.author, c.author_id),
+    content: str(c.content),
+    mentions: mentionStubs(workflow, c.mentions),
+    created_at: str(c.created_at)
+  };
+}
+var PERSON_VALUED_EVENTS = /* @__PURE__ */ new Set(["owner_changed", "reviewer_changed"]);
+function hydrateTimelineEvent(raw, workflow) {
+  const e = obj(raw);
+  const eventType = str(e.event_type);
+  const value = (v) => {
+    if (!PERSON_VALUED_EVENTS.has(eventType)) return v ?? null;
+    if (typeof v !== "string" || v.length === 0) return v ?? null;
+    const stub = userStubFromAny(workflow, v);
+    return stub && stub.display_name.length > 0 ? stub : v;
+  };
+  return {
+    id: str(e.id),
+    task_id: str(e.task_id) || str(obj(e.data).task_id),
+    event_type: eventType,
+    actor: userStubFromAny(workflow, e.actor ?? e.actor_id),
+    old_value: value(e.old_value),
+    new_value: value(e.new_value),
+    data: obj(e.data),
+    created_at: str(e.created_at)
+  };
+}
+var REFERENCE_TYPES = [
+  "github_pr",
+  "github_commit",
+  "github_branch",
+  "github_issue",
+  "figma",
+  "url"
+];
+function hydrateReference(raw) {
+  const r = obj(raw);
+  const rt = str(r.reference_type);
+  const reference_type = REFERENCE_TYPES.includes(rt) ? rt : "url";
+  return {
+    id: str(r.id),
+    reference_type,
+    title: str(r.title),
+    url: str(r.url),
+    external_status: nullableStr(r.external_status),
+    external_sub_id: nullableStr(r.external_sub_id)
+  };
+}
+function statusIdOf(r) {
+  if (typeof r.status_id === "string") return r.status_id;
+  if (r.status && typeof r.status === "object") {
+    const s = obj(r.status);
+    if (typeof s.id === "string") return s.id;
+  }
+  return "";
+}
+function statusRef(wf, statusId) {
+  const s = wf.statuses.find((x) => x.id === statusId);
+  return { id: statusId, name: s?.name ?? "" };
+}
+function stageRefForStatus(wf, statusId, r) {
+  const status = wf.statuses.find((x) => x.id === statusId);
+  const stageId = status?.stage_id ?? (typeof r.stage_id === "string" ? r.stage_id : "");
+  return stageRef(wf, stageId);
+}
+function stageRef(wf, stageId) {
+  const stage = wf.stages.find((x) => x.id === stageId);
+  return { id: stageId, name: stage?.name ?? "" };
+}
+function displayName(wf, userId) {
+  return wf.members.find((m) => m.id === userId)?.display_name ?? "";
+}
+function ownerStub(wf, expanded, idValue) {
+  const stub = userStubFromAny(wf, expanded);
+  if (stub) return stub;
+  return userStubFromAny(wf, idValue);
+}
+function authorStub(wf, expanded, idValue) {
+  return ownerStub(wf, expanded, idValue) ?? {
+    id: typeof idValue === "string" ? idValue : "",
+    display_name: ""
+  };
+}
+function memberOf(wf, userId) {
+  return wf.members.find((m) => m.id === userId);
+}
+function userStubFromAny(wf, value) {
+  if (typeof value === "string") {
+    if (value.length === 0) return null;
+    return withProfile(wf, { id: value, display_name: displayName(wf, value) }, {});
+  }
+  if (value && typeof value === "object") {
+    const u = obj(value);
+    const id = str(u.id);
+    if (id.length === 0) return null;
+    const dn = typeof u.display_name === "string" && u.display_name.length > 0 ? u.display_name : displayName(wf, id);
+    return withProfile(wf, { id, display_name: dn }, u);
+  }
+  return null;
+}
+function withProfile(wf, stub, raw) {
+  if (raw.first_name !== void 0) stub.first_name = nullableStr(raw.first_name);
+  if (raw.last_name !== void 0) stub.last_name = nullableStr(raw.last_name);
+  if (raw.avatar_url !== void 0) stub.avatar_url = nullableStr(raw.avatar_url);
+  const jobTitle = typeof raw.job_title === "string" && raw.job_title.length > 0 ? raw.job_title : memberOf(wf, stub.id)?.job_title;
+  if (jobTitle) stub.job_title = jobTitle;
+  return stub;
+}
+function mentionStubs(wf, value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((m) => userStubFromAny(wf, m)).filter((u) => u !== null);
+}
+function labelNames(wf, labels) {
+  if (!Array.isArray(labels)) return [];
+  return labels.map((l) => {
+    if (typeof l === "string") {
+      const byId = wf.labels.find((x) => x.id === l);
+      if (byId) return byId.name;
+      return l;
+    }
+    if (l && typeof l === "object") {
+      const lo = obj(l);
+      if (typeof lo.name === "string" && lo.name.length > 0) return lo.name;
+      if (typeof lo.id === "string") {
+        return wf.labels.find((x) => x.id === lo.id)?.name ?? "";
+      }
+    }
+    return "";
+  }).filter((name) => name.length > 0);
+}
+function fieldName(wf, value) {
+  const v = str(value);
+  if (v.length === 0) return "";
+  for (const t of wf.templates) {
+    const f = t.fields.find((x) => x.id === v || x.key === v);
+    if (f) return f.name;
+  }
+  return v;
+}
+function byStageNames(wf, value) {
+  const out = {};
+  if (!value || typeof value !== "object") return out;
+  for (const [key, raw] of Object.entries(value)) {
+    const stage = wf.stages.find((s) => s.id === key);
+    out[stage?.name ?? key] = num(raw);
+  }
+  return out;
+}
+function obj(v) {
+  return v && typeof v === "object" ? v : {};
+}
+function str(v, fallback = "") {
+  return typeof v === "string" ? v : fallback;
+}
+function nullableStr(v) {
+  return typeof v === "string" ? v : null;
+}
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+// ../pyramid/src/operations/index.ts
+var PROJECT_ROLES = ["admin", "pm", "member", "viewer", "guest"];
+function projectRole(v) {
+  return PROJECT_ROLES.includes(v) ? v : "member";
+}
+function toProjectSummary(raw) {
+  const p = rec(raw);
+  return {
+    id: readStr(p.id) ?? "",
+    handle: readStr(p.handle) ?? "",
+    name: readStr(p.name) ?? "",
+    task_prefix: readStr(p.task_prefix) ?? "",
+    role: projectRole(p.role),
+    archived: p.archived_at != null || p.archived === true
+  };
+}
+var WORKSPACE_ROLES = ["owner", "admin", "member"];
+function workspaceRole(v) {
+  return WORKSPACE_ROLES.includes(v) ? v : "member";
+}
+var whoami = {
+  name: "pyramid.whoami",
+  summary: "Report the authenticated user, their workspace, and accessible projects.",
+  input: z.object({}),
+  async run(_input, ctx) {
+    const [me, projectsRaw, workspaces] = await Promise.all([
+      ctx.client.api.getMe(),
+      ctx.client.api.listProjects(),
+      ctx.client.api.listWorkspaces().catch(() => [])
+    ]);
+    const m = rec(me);
+    const workspaceRaw = rec(m.workspace ?? workspaces[0]);
+    return {
+      user: {
+        id: readStr(m.id) ?? "",
+        display_name: readStr(m.display_name) ?? readStr(m.email) ?? "",
+        email: readStr(m.email) ?? ""
+      },
+      workspace: {
+        id: readStr(workspaceRaw.id) ?? "",
+        handle: readStr(workspaceRaw.handle) ?? "",
+        name: readStr(workspaceRaw.name) ?? readStr(workspaceRaw.handle) ?? "",
+        role: workspaceRole(workspaceRaw.role)
+      },
+      projects: projectsRaw.map(toProjectSummary)
+    };
+  }
+};
+var listProjects = {
+  name: "pyramid.project.list",
+  summary: "List the projects accessible to the authenticated user.",
+  input: z.object({}),
+  async run(_input, ctx) {
+    const raw = await ctx.client.api.listProjects();
+    return raw.map(toProjectSummary);
+  }
+};
+var getProjectWorkflowInput = z.object({ project: z.string() });
+var getProjectWorkflow = {
+  name: "pyramid.project.workflow",
+  summary: "Show a project's workflow: stages, statuses, labels, members, and custom-field templates.",
+  input: getProjectWorkflowInput,
+  meta: { cli: { positionals: ["project"] } },
+  async run(input, ctx) {
+    const project = await ctx.client.resolver.resolveProject(input.project);
+    return ctx.client.resolver.getWorkflow(project.id);
+  }
+};
+var listMyTasksInput = z.object({
+  limit: z.number().int().min(1).max(50).optional(),
+  cursor: z.string().optional()
+});
+var DEFAULT_LIMIT = 25;
+var listMyTasks = {
+  name: "pyramid.task.list-mine",
+  summary: "List tasks you own or review, newest first, across projects. Returns one page with a cursor.",
+  input: listMyTasksInput,
+  meta: { cli: { verbAliases: ["next"] } },
+  async run(input, ctx) {
+    const limit = input.limit ?? DEFAULT_LIMIT;
+    const page = await ctx.client.api.listMyTasks({
+      limit,
+      cursor: input.cursor
+    });
+    const items = [];
+    const wfCache = /* @__PURE__ */ new Map();
+    for (const raw of page.data) {
+      const projectId = readStr(rec(raw).project_id);
+      let wf;
+      if (projectId) {
+        wf = wfCache.get(projectId);
+        if (!wf) {
+          wf = await ctx.client.resolver.getWorkflow(projectId);
+          wfCache.set(projectId, wf);
+        }
+      }
+      items.push(hydrateTaskSummary(raw, wf ?? EMPTY_WORKFLOW));
+    }
+    return {
+      items,
+      next_cursor: page.cursor,
+      has_more: page.cursor !== null
+    };
+  }
+};
+var EMPTY_WORKFLOW = {
+  project: { id: "", handle: "", name: "", task_prefix: "", role: "member", archived: false },
+  stages: [],
+  statuses: [],
+  labels: [],
+  members: [],
+  templates: []
+};
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var TASK_KEY_RE = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+async function resolveTaskRef(ctx, ref) {
+  const trimmed = ref.trim();
+  if (UUID_RE.test(trimmed)) {
+    const raw = rec(await ctx.client.api.getTask(trimmed));
+    return {
+      id: readStr(raw.id) ?? trimmed,
+      projectId: readStr(raw.project_id) ?? "",
+      key: readStr(raw.key) ?? ""
+    };
+  }
+  if (TASK_KEY_RE.test(trimmed)) {
+    const page = await ctx.client.api.searchTasks({ q: trimmed, limit: 50 });
+    const needle = trimmed.toLowerCase();
+    const hit = page.data.map(rec).find((r) => (readStr(r.key) ?? "").toLowerCase() === needle);
+    if (hit) {
+      return {
+        id: readStr(hit.id) ?? "",
+        projectId: readStr(hit.project_id) ?? "",
+        key: readStr(hit.key) ?? trimmed
+      };
+    }
+    throw pyramidError("task_not_found", `No task matches "${ref}".`);
+  }
+  throw pyramidError("task_not_found", `"${ref}" is neither a task key (e.g. WEB-42) nor a UUID.`);
+}
+async function hydrateDetailFor(ctx, raw, projectId) {
+  const wf = projectId ? await ctx.client.resolver.getWorkflow(projectId) : EMPTY_WORKFLOW;
+  return hydrateTaskDetail(raw, wf);
+}
+var customFieldSchema = z.object({
+  field: z.string(),
+  value: z.unknown()
+});
+async function resolveStatusWithStage(ctx, projectId, stage, status) {
+  if (status !== void 0) {
+    const resolved = await ctx.client.resolver.resolveStatus(projectId, status);
+    if (stage !== void 0) {
+      const resolvedStage = await ctx.client.resolver.resolveStage(projectId, stage);
+      if (resolved.stage_id !== resolvedStage.id) {
+        throw pyramidError("status_not_in_stage", `Status "${status}" is not in stage "${stage}".`);
+      }
+    }
+    return { id: resolved.id, stage_id: resolved.stage_id };
+  }
+  if (stage !== void 0) {
+    const resolved = await ctx.client.resolver.resolveStatus(projectId, stage);
+    return { id: resolved.id, stage_id: resolved.stage_id };
+  }
+  return void 0;
+}
+async function resolveLabelIds(ctx, projectId, labels) {
+  if (labels === void 0) return void 0;
+  const ids = [];
+  for (const label of labels) {
+    const resolved = await ctx.client.resolver.resolveLabel(projectId, label);
+    ids.push(resolved.id);
+  }
+  return ids;
+}
+async function resolveMentionIds(ctx, projectId, mentions) {
+  if (mentions === void 0) return void 0;
+  const ids = [];
+  for (const mention of mentions) {
+    const resolved = await ctx.client.resolver.resolveUser(projectId, mention);
+    ids.push(resolved.id);
+  }
+  return ids;
+}
+async function buildCreateBody(ctx, projectId, row) {
+  const body = { title: row.title };
+  if (row.description !== void 0) body.description = row.description;
+  if (row.priority !== void 0) body.priority = row.priority;
+  if (row.due_date !== void 0) body.due_date = row.due_date;
+  if (row.estimate_hours !== void 0) body.estimate = row.estimate_hours;
+  if (row.guest_visible !== void 0) body.guest_visible = row.guest_visible;
+  const resolvedStatus = await resolveStatusWithStage(ctx, projectId, row.stage, row.status);
+  if (resolvedStatus !== void 0) body.status_id = resolvedStatus.id;
+  if (row.owner !== void 0) {
+    body.owner_id = (await ctx.client.resolver.resolveUser(projectId, row.owner)).id;
+  }
+  if (row.reviewer !== void 0) {
+    body.reviewer_id = (await ctx.client.resolver.resolveUser(projectId, row.reviewer)).id;
+  }
+  const labelIds = await resolveLabelIds(ctx, projectId, row.labels);
+  if (labelIds !== void 0) body.label_ids = labelIds;
+  if (row.custom_fields !== void 0) {
+    body.field_values = await resolveFieldValues(ctx, projectId, row.custom_fields);
+  }
+  return body;
+}
+async function resolveFieldValues(ctx, projectId, fields) {
+  const wf = await ctx.client.resolver.getWorkflow(projectId);
+  const out = {};
+  for (const cf of fields) {
+    const needle = cf.field.trim().toLowerCase();
+    let def;
+    for (const t of wf.templates) {
+      def = t.fields.find(
+        (f) => f.id === cf.field || f.key.toLowerCase() === needle || f.name.toLowerCase() === needle
+      );
+      if (def) break;
+    }
+    if (def === void 0) {
+      throw pyramidError("field_not_found", `No custom field matches "${cf.field}".`);
+    }
+    if (def.field_type === "user" && typeof cf.value === "string") {
+      out[def.id] = (await ctx.client.resolver.resolveUser(projectId, cf.value)).id;
+    } else {
+      validateFieldValue(def, cf.value);
+      out[def.id] = cf.value;
+    }
+  }
+  return out;
+}
+function validateFieldValue(def, value) {
+  const fail = (why) => {
+    throw pyramidError("invalid_field_value", `Custom field "${def.name}" ${why}.`);
+  };
+  switch (def.field_type) {
+    case "number":
+      if (typeof value !== "number") fail("expects a number");
+      break;
+    case "checkbox":
+      if (typeof value !== "boolean") fail("expects a boolean");
+      break;
+    case "date":
+      if (typeof value !== "string") fail("expects a date string (YYYY-MM-DD)");
+      break;
+    case "text":
+      if (typeof value !== "string") fail("expects a string");
+      break;
+    case "select":
+      if (typeof value !== "string") fail("expects a single option string");
+      if (def.options && !def.options.includes(value)) {
+        fail(`must be one of: ${def.options.join(", ")}`);
+      }
+      break;
+    case "multiselect":
+      if (!Array.isArray(value)) fail("expects an array of option strings");
+      if (def.options) {
+        for (const v of value) {
+          if (typeof v !== "string" || !def.options.includes(v)) {
+            fail(`values must each be one of: ${def.options.join(", ")}`);
+          }
+        }
+      }
+      break;
+  }
+}
+var taskListInput = z.object({
+  project: z.string(),
+  status: z.string().optional(),
+  stage: z.string().optional(),
+  // Owner and Reviewer — the words the product uses. There is no "assignee".
+  owner: z.string().optional(),
+  reviewer: z.string().optional(),
+  label: z.string().optional(),
+  query: z.string().optional(),
+  archived: z.boolean().optional(),
+  limit: z.number().int().min(1).max(50).optional(),
+  cursor: z.string().optional()
+});
+var taskList = {
+  name: "pyramid.task.list",
+  summary: "List a project's tasks, filtered by status/stage/owner/reviewer/label/query. Returns one page with a cursor.",
+  input: taskListInput,
+  meta: {
+    cli: { positionals: ["project"], routes: { mine: "pyramid.task.list-mine" } }
+  },
+  async run(input, ctx) {
+    const project = await ctx.client.resolver.resolveProject(input.project);
+    const archived = input.archived ?? false;
+    let page;
+    if (archived) {
+      page = await ctx.client.api.listArchived(project.id, {
+        limit: input.limit ?? DEFAULT_LIMIT,
+        cursor: input.cursor
+      });
+    } else {
+      const statusId = input.status !== void 0 ? (await ctx.client.resolver.resolveStatus(project.id, input.status)).id : void 0;
+      const stageId = input.stage !== void 0 ? (await ctx.client.resolver.resolveStage(project.id, input.stage)).id : void 0;
+      const ownerId = input.owner !== void 0 ? (await ctx.client.resolver.resolveUser(project.id, input.owner)).id : void 0;
+      const reviewerId = input.reviewer !== void 0 ? (await ctx.client.resolver.resolveUser(project.id, input.reviewer)).id : void 0;
+      const labelId = input.label !== void 0 ? (await ctx.client.resolver.resolveLabel(project.id, input.label)).id : void 0;
+      page = await ctx.client.api.listTasks(project.id, {
+        status: statusId,
+        stage_id: stageId,
+        owner_id: ownerId,
+        reviewer_id: reviewerId,
+        label_id: labelId,
+        q: input.query,
+        limit: input.limit ?? DEFAULT_LIMIT,
+        cursor: input.cursor
+      });
+    }
+    const wf = await ctx.client.resolver.getWorkflow(project.id);
+    const items = page.data.map((raw) => hydrateTaskSummary(raw, wf)).filter((t) => archived || !t.archived);
+    return {
+      items,
+      next_cursor: page.cursor,
+      has_more: page.cursor !== null
+    };
+  }
+};
+var taskShowInput = z.object({
+  task: z.string(),
+  // The backend's only drill-in is `?expand`, which inlines the related owner,
+  // reviewer, and label rows (DOC-BACKEND-CONTRACT). It does NOT expose
+  // timeline / comments / attachments — those are separate tools (e.g. list_comments).
+  expand: z.boolean().optional()
+});
+var taskShow = {
+  name: "pyramid.task.get",
+  summary: "Show one task's full detail by key (WEB-42) or UUID; `expand` inlines owner/reviewer/labels.",
+  input: taskShowInput,
+  meta: { cli: { positionals: ["task"], verbAliases: ["show"] } },
+  async run(input, ctx) {
+    const ref = await resolveTaskRef(ctx, input.task);
+    const raw = await ctx.client.api.getTask(
+      ref.id,
+      input.expand ? "owner,reviewer,labels" : void 0
+    );
+    const projectId = readStr(rec(raw).project_id) ?? ref.projectId;
+    return hydrateDetailFor(ctx, raw, projectId);
+  }
+};
+var priorityEnum = z.enum(["none", "low", "medium", "high", "urgent"]);
+var taskCreateInput = z.object({
+  project: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  stage: z.string().optional(),
+  status: z.string().optional(),
+  owner: z.string().optional(),
+  reviewer: z.string().optional(),
+  labels: z.array(z.string()).optional(),
+  priority: priorityEnum.optional(),
+  due_date: z.string().optional(),
+  estimate_hours: z.number().optional(),
+  guest_visible: z.boolean().optional(),
+  custom_fields: z.array(customFieldSchema).optional()
+});
+var taskCreate = {
+  name: "pyramid.task.create",
+  summary: "Create a task in a project. Accepts names/keys for stage/status/owner/reviewer/labels.",
+  input: taskCreateInput,
+  meta: { cli: { positionals: ["title"] } },
+  async run(input, ctx) {
+    const project = await ctx.client.resolver.resolveProject(input.project);
+    const body = await buildCreateBody(ctx, project.id, input);
+    const raw = await ctx.client.api.createTask(project.id, body);
+    return hydrateDetailFor(ctx, raw, project.id);
+  }
+};
+var taskBulkCreateInput = z.object({
+  project: z.string(),
+  template: z.string().optional(),
+  defaults: z.object({
+    stage: z.string().optional(),
+    status: z.string().optional(),
+    labels: z.array(z.string()).optional()
+  }).optional(),
+  tasks: z.array(
+    z.object({
+      title: z.string(),
+      description: z.string().optional(),
+      stage: z.string().optional(),
+      status: z.string().optional(),
+      owner: z.string().optional(),
+      reviewer: z.string().optional(),
+      labels: z.array(z.string()).optional(),
+      priority: priorityEnum.optional(),
+      due_date: z.string().optional(),
+      estimate_hours: z.number().optional(),
+      guest_visible: z.boolean().optional(),
+      custom_fields: z.array(customFieldSchema).optional()
+    })
+  ).min(1).max(100)
+});
+var taskBulkCreate = {
+  name: "pyramid.task.create-bulk",
+  summary: "Bulk-create up to 100 tasks in a project from a required template (returns the created tasks).",
+  input: taskBulkCreateInput,
+  // CLI surfaces bulk-create on `task create` via a special-cased `--file`.
+  meta: { cli: { positionals: ["project"], verbAliases: ["bulk"], fileInput: "tasks" } },
+  async run(input, ctx) {
+    const project = await ctx.client.resolver.resolveProject(input.project);
+    const defaults = input.defaults ?? {};
+    if (input.template === void 0) {
+      throw pyramidError(
+        "validation_failed",
+        "Bulk create requires a `template` (the task-schema template to instantiate)."
+      );
+    }
+    const templateId = await resolveTemplateId(ctx, project.id, input.template);
+    const rows = [];
+    for (const row of input.tasks) {
+      rows.push(
+        await buildCreateBody(ctx, project.id, {
+          ...row,
+          stage: row.stage ?? defaults.stage,
+          status: row.status ?? defaults.status,
+          labels: row.labels ?? defaults.labels
+        })
+      );
+    }
+    const raw = rec(
+      await ctx.client.api.bulkCreate({
+        project_id: project.id,
+        template_id: templateId,
+        tasks: rows
+      })
+    );
+    const created = Array.isArray(raw.created) ? raw.created : [];
+    const wf = await ctx.client.resolver.getWorkflow(project.id);
+    return created.map((r) => hydrateTaskDetail(r, wf));
+  }
+};
+async function resolveTemplateId(ctx, projectId, template) {
+  const wf = await ctx.client.resolver.getWorkflow(projectId);
+  const needle = template.trim().toLowerCase();
+  const match = wf.templates.find((t) => t.id === template || t.name.toLowerCase() === needle);
+  if (match) return match.id;
+  throw pyramidError("validation_failed", `No task template matches "${template}".`, {
+    candidates: wf.templates.map((t) => t.name)
+  });
+}
+var taskUpdateInput = z.object({
+  task: z.string(),
+  title: z.string().optional(),
+  description: z.string().nullable().optional(),
+  priority: z.string().optional(),
+  due_date: z.string().nullable().optional(),
+  start_date: z.string().nullable().optional(),
+  estimate: z.number().optional(),
+  guest_visible: z.boolean().optional(),
+  owner: z.string().nullable().optional(),
+  reviewer: z.string().nullable().optional(),
+  add_labels: z.array(z.string()).optional(),
+  remove_labels: z.array(z.string()).optional(),
+  custom_fields: z.array(customFieldSchema).optional()
+});
+var taskUpdate = {
+  name: "pyramid.task.update",
+  summary: "Update a task, including its owner/reviewer (pass null to clear). Labels and custom fields fan out to their endpoints.",
+  input: taskUpdateInput,
+  meta: { cli: { positionals: ["task"] } },
+  async run(input, ctx) {
+    const ref = await resolveTaskRef(ctx, input.task);
+    const projectId = ref.projectId;
+    const patch = {};
+    if (input.title !== void 0) patch.title = input.title;
+    if (input.description !== void 0) patch.description = input.description;
+    if (input.priority !== void 0) patch.priority = input.priority;
+    if (input.due_date !== void 0) patch.due_date = input.due_date;
+    if (input.start_date !== void 0) patch.start_date = input.start_date;
+    if (input.estimate !== void 0) patch.estimate = input.estimate;
+    if (input.guest_visible !== void 0) patch.guest_visible = input.guest_visible;
+    if (input.owner !== void 0) {
+      patch.owner_id = input.owner === null ? null : (await ctx.client.resolver.resolveUser(projectId, input.owner)).id;
+    }
+    if (input.reviewer !== void 0) {
+      patch.reviewer_id = input.reviewer === null ? null : (await ctx.client.resolver.resolveUser(projectId, input.reviewer)).id;
+    }
+    if (Object.keys(patch).length > 0) {
+      await failingSubUpdate("content", () => ctx.client.api.updateTask(ref.id, patch));
+    }
+    const addLabelIds = await resolveLabelIds(ctx, projectId, input.add_labels);
+    for (const labelId of addLabelIds ?? []) {
+      await failingSubUpdate("add_label", () => ctx.client.api.addTaskLabel(ref.id, labelId));
+    }
+    const removeLabelIds = await resolveLabelIds(ctx, projectId, input.remove_labels);
+    for (const labelId of removeLabelIds ?? []) {
+      await failingSubUpdate("remove_label", () => ctx.client.api.removeTaskLabel(ref.id, labelId));
+    }
+    if (input.custom_fields !== void 0) {
+      const fieldValues = await resolveFieldValues(ctx, projectId, input.custom_fields);
+      await failingSubUpdate(
+        "field_values",
+        () => ctx.client.api.setFieldValues(ref.id, { field_values: fieldValues })
+      );
+    }
+    const raw = await ctx.client.api.getTask(ref.id);
+    return hydrateDetailFor(ctx, raw, projectId);
+  }
+};
+async function failingSubUpdate(which, fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (err instanceof MagicError) {
+      throw new MagicError(err.code, `update_task ${which} failed: ${err.message}`, {
+        product: err.product,
+        ...err.hint !== void 0 ? { hint: err.hint } : {},
+        ...err.candidates !== void 0 ? { candidates: err.candidates } : {},
+        ...err.details !== void 0 ? { details: err.details } : {}
+      });
+    }
+    throw err;
+  }
+}
+var taskMoveInput = z.object({
+  task: z.string(),
+  status: z.string(),
+  after_task: z.string().optional(),
+  before_task: z.string().optional()
+});
+var taskMove = {
+  name: "pyramid.task.move",
+  summary: "Move a task to a target status (carries its stage), optionally positioned by neighbor key.",
+  input: taskMoveInput,
+  meta: { cli: { positionals: ["task"] } },
+  async run(input, ctx) {
+    if (input.after_task !== void 0 && input.before_task !== void 0) {
+      throw pyramidError("validation_failed", "Pass at most one of after_task / before_task.");
+    }
+    const ref = await resolveTaskRef(ctx, input.task);
+    const status = await ctx.client.resolver.resolveStatus(ref.projectId, input.status);
+    const body = { status_id: status.id };
+    if (input.after_task !== void 0) {
+      body.after_id = (await resolveTaskRef(ctx, input.after_task)).id;
+    }
+    if (input.before_task !== void 0) {
+      body.before_id = (await resolveTaskRef(ctx, input.before_task)).id;
+    }
+    const raw = rec(await ctx.client.api.moveTask(ref.id, body));
+    return hydrateDetailFor(ctx, raw.task, ref.projectId);
+  }
+};
+var taskArchiveInput = z.object({
+  task: z.string(),
+  // The CLI archives by default; `--unarchive` sets false.
+  archived: z.boolean().default(true)
+});
+var taskArchive = {
+  name: "pyramid.task.archive",
+  summary: "Soft-archive (or unarchive) a task. Reversible \u2014 not destructive-gated.",
+  input: taskArchiveInput,
+  meta: { cli: { positionals: ["task"], presets: { unarchive: { archived: false } } } },
+  async run(input, ctx) {
+    const ref = await resolveTaskRef(ctx, input.task);
+    const raw = input.archived ? await ctx.client.api.archiveTask(ref.id) : await ctx.client.api.unarchiveTask(ref.id);
+    return hydrateDetailFor(ctx, raw, ref.projectId);
+  }
+};
+var taskDeleteInput = z.object({ task: z.string() });
+var taskDelete = {
+  name: "pyramid.task.delete",
+  summary: "Hard-delete a task. Requires MAGIC_ALLOW_DESTRUCTIVE=1 (otherwise destructive_action_disabled).",
+  input: taskDeleteInput,
+  meta: {
+    destructive: true,
+    cli: { positionals: ["task"] }
+  },
+  // meta.destructive is the gate: the kit's CLI runner and MCP callTool enforce it.
+  async run(input, ctx) {
+    const ref = await resolveTaskRef(ctx, input.task);
+    await ctx.client.api.deleteTask(ref.id, true);
+    return { id: ref.id, key: ref.key, deleted: true };
+  }
+};
+var commentAddInput = z.object({
+  task: z.string(),
+  content: z.string(),
+  stage: z.string().optional(),
+  mentions: z.array(z.string()).optional()
+});
+var commentAdd = {
+  name: "pyramid.task.comment",
+  summary: "Add a stage-scoped comment to a task (defaults to the task's current stage).",
+  input: commentAddInput,
+  meta: {
+    cli: { positionals: ["task", "content"] }
+  },
+  async run(input, ctx) {
+    const ref = await resolveTaskRef(ctx, input.task);
+    const projectId = ref.projectId;
+    let stageId;
+    if (input.stage !== void 0) {
+      stageId = (await ctx.client.resolver.resolveStage(projectId, input.stage)).id;
+    } else {
+      stageId = await currentStageId(ctx, ref);
+    }
+    const mentionIds = await resolveMentionIds(ctx, projectId, input.mentions);
+    const body = { content: input.content };
+    if (stageId !== void 0) body.stage_id = stageId;
+    if (mentionIds !== void 0) body.mention_user_ids = mentionIds;
+    const raw = await ctx.client.api.addComment(ref.id, body);
+    const wf = projectId ? await ctx.client.resolver.getWorkflow(projectId) : EMPTY_WORKFLOW;
+    return hydrateComment(raw, wf);
+  }
+};
+async function currentStageId(ctx, ref) {
+  if (!ref.projectId) return void 0;
+  const raw = rec(await ctx.client.api.getTask(ref.id));
+  const statusId = readStr(raw.status_id);
+  if (statusId) {
+    const wf = await ctx.client.resolver.getWorkflow(ref.projectId);
+    const status = wf.statuses.find((s) => s.id === statusId);
+    if (status) return status.stage_id;
+  }
+  return readStr(raw.stage_id);
+}
+var commentReplyInput = z.object({
+  comment_id: z.string(),
+  content: z.string(),
+  mentions: z.array(z.string()).optional()
+});
+var commentReply = {
+  name: "pyramid.comment.reply",
+  summary: "Reply to a ROOT comment (one level only; replying to a reply -> reply_depth_exceeded).",
+  input: commentReplyInput,
+  meta: {
+    cli: { positionals: ["comment_id", "content"] }
+  },
+  async run(input, ctx) {
+    const target = rec(await ctx.client.api.getComment(input.comment_id));
+    const parentId = readStr(target.parent_id);
+    const threadRootId = readStr(target.thread_root_id);
+    const selfId = readStr(target.id);
+    if (parentId !== void 0 || threadRootId !== void 0 && threadRootId !== selfId) {
+      throw pyramidError(
+        "reply_depth_exceeded",
+        "Replies are one level deep \u2014 reply to the root comment instead."
+      );
+    }
+    const taskId = readStr(target.task_id);
+    const projectId = taskId ? (await resolveTaskRef(ctx, taskId)).projectId : "";
+    const mentionIds = await resolveMentionIds(ctx, projectId, input.mentions);
+    const body = { content: input.content };
+    if (mentionIds !== void 0) body.mention_user_ids = mentionIds;
+    const raw = await ctx.client.api.replyComment(input.comment_id, body);
+    const wf = projectId ? await ctx.client.resolver.getWorkflow(projectId) : EMPTY_WORKFLOW;
+    return hydrateComment(raw, wf);
+  }
+};
+var searchTasksInput = z.object({
+  query: z.string(),
+  limit: z.number().int().min(1).max(50).optional()
+});
+var searchTasks = {
+  name: "pyramid.task.search",
+  summary: "Full-text search tasks across the workspace by title/key/content. Returns one page.",
+  input: searchTasksInput,
+  meta: { cli: { positionals: ["query"] } },
+  async run(input, ctx) {
+    const page = await ctx.client.api.searchTasks({
+      q: input.query,
+      limit: input.limit ?? DEFAULT_LIMIT
+    });
+    const wfCache = /* @__PURE__ */ new Map();
+    const items = [];
+    for (const raw of page.data) {
+      const pid = readStr(rec(raw).project_id) ?? "";
+      let wf = wfCache.get(pid);
+      if (wf === void 0) {
+        wf = pid ? await ctx.client.resolver.getWorkflow(pid) : EMPTY_WORKFLOW;
+        wfCache.set(pid, wf);
+      }
+      items.push(hydrateTaskSummary(raw, wf));
+    }
+    return { items, next_cursor: page.cursor, has_more: page.cursor !== null };
+  }
+};
+var listCommentsInput = z.object({
+  task: z.string(),
+  // Stage-scoped (r4): defaults to the task's CURRENT stage; pass "all" to list
+  // comments across every stage, or a stage name/key to scope to that stage.
+  stage: z.string().optional(),
+  limit: z.number().int().min(1).max(50).optional(),
+  cursor: z.string().optional()
+});
+var listComments = {
+  name: "pyramid.comment.list",
+  summary: "List a task's comments, oldest first. Defaults to the task's current stage; `stage: \"all\"` lists every stage.",
+  input: listCommentsInput,
+  meta: { cli: { positionals: ["task"] } },
+  async run(input, ctx) {
+    const ref = await resolveTaskRef(ctx, input.task);
+    let stageId;
+    if (input.stage === void 0) {
+      stageId = await currentStageId(ctx, ref);
+    } else if (input.stage.trim().toLowerCase() === "all") {
+      stageId = void 0;
+    } else {
+      stageId = (await ctx.client.resolver.resolveStage(ref.projectId, input.stage)).id;
+    }
+    const page = await ctx.client.api.listComments(ref.id, {
+      stage_id: stageId,
+      limit: input.limit ?? DEFAULT_LIMIT,
+      cursor: input.cursor
+    });
+    const wf = ref.projectId ? await ctx.client.resolver.getWorkflow(ref.projectId) : EMPTY_WORKFLOW;
+    const items = page.data.map((raw) => hydrateComment(raw, wf));
+    return { items, next_cursor: page.cursor, has_more: page.cursor !== null };
+  }
+};
+var TIMELINE_DEFAULT_LIMIT = 50;
+var TIMELINE_MAX_LIMIT = 200;
+var taskTimelineInput = z.object({
+  task: z.string(),
+  /** Narrow to one kind, e.g. "owner_changed" / "status_changed". */
+  event_type: z.string().optional(),
+  limit: z.number().int().min(1).max(TIMELINE_MAX_LIMIT).optional(),
+  cursor: z.string().optional()
+});
+var taskTimeline = {
+  name: "pyramid.task.timeline",
+  summary: "A task's history (who changed what, when), OLDEST first. Optionally filter to one event_type, e.g. owner_changed.",
+  input: taskTimelineInput,
+  meta: { cli: { positionals: ["task"] } },
+  async run(input, ctx) {
+    const ref = await resolveTaskRef(ctx, input.task);
+    const page = await ctx.client.api.getTaskTimeline(ref.id, {
+      limit: input.limit ?? TIMELINE_DEFAULT_LIMIT,
+      cursor: input.cursor,
+      event_type: input.event_type
+    });
+    const wf = ref.projectId ? await ctx.client.resolver.getWorkflow(ref.projectId) : EMPTY_WORKFLOW;
+    const items = page.data.map((raw) => hydrateTimelineEvent(raw, wf));
+    return { items, next_cursor: page.cursor, has_more: page.cursor !== null };
+  }
+};
+var operations = [
+  whoami,
+  listProjects,
+  getProjectWorkflow,
+  listMyTasks,
+  taskList,
+  taskShow,
+  taskTimeline,
+  searchTasks,
+  taskCreate,
+  taskBulkCreate,
+  taskUpdate,
+  taskMove,
+  taskArchive,
+  taskDelete,
+  commentAdd,
+  commentReply,
+  listComments
+];
+var operationsByName = new Map(operations.map((o) => [o.name, o]));
+
+export {
+  pyramidError,
+  mapPyramidHttpError,
+  toPyramidError,
+  operations,
+  operationsByName
+};