@opentask/taskin-task-manager 3.0.2 → 3.2.0

package/src/filter-tasks/filter-tasks.types.ts

@@ -0,0 +1,26 @@
+import type { GroupId, TaskId, TaskStatus, TaskType } from '@opentask/taskin-types';
+
+/**
+ * O que restringe uma listagem de tarefas — derivado do schema unico.
+ *
+ * Vive em `filter-criteria.ts`, onde os criterios sao definidos uma vez so e as
+ * superficies (CLI e MCP) derivam. Reexportado aqui para nao mudar os imports
+ * existentes.
+ */
+export type { TaskFilterCriteria } from './filter-criteria.js';
+
+/**
+ * A forma de uma tarefa numa listagem — o que identifica, nao o que ela diz.
+ *
+ * @public
+ */
+export interface TaskSummary {
+  readonly id: TaskId;
+  readonly title: string;
+  readonly status: TaskStatus;
+  readonly type: TaskType;
+  readonly assignee?: { readonly id: string; readonly name: string };
+  readonly priority?: number;
+  readonly groupId?: GroupId;
+  readonly difficulty?: number;
+}

package/src/filter-tasks/index.ts

@@ -0,0 +1,16 @@
+export type {
+  CriterionCli,
+  CriterionSurface,
+  FilterCliOption,
+  FilterJsonSchema,
+  TaskFilterCriteria,
+} from './filter-criteria.js';
+export {
+  FILTER_CRITERIA_SURFACES,
+  FilterCriteriaSchema,
+  filterCriteriaCliOptions,
+  filterCriteriaJsonSchema,
+  parseFilterCriteria,
+} from './filter-criteria.js';
+export { filterTasks, summarizeTask } from './filter-tasks.js';
+export type { TaskSummary } from './filter-tasks.types.js';

package/src/group-registry.contract.ts

@@ -0,0 +1,99 @@
+import { parseGroupId } from '@opentask/taskin-types';
+import { describe, expect, it } from 'vitest';
+import type { IGroupRegistry } from './group-registry.types.js';
+
+/**
+ * Contrato que toda implementacao de {@link IGroupRegistry} precisa cumprir.
+ *
+ * Vive no pacote agnostico pelo mesmo motivo do contrato de usuarios: um
+ * provider de arquivos, um do Redmine e um do GitHub provam o mesmo
+ * comportamento sem depender do pacote um do outro. Exportado pelo subcaminho
+ * `./testing`, para o `vitest` nunca entrar no grafo de execucao.
+ *
+ * @param createSubject - Devolve um registro vazio, e uma forma de saber quantas
+ *   tarefas pertencem a um grupo — porque apagar precisa dizer quantas foram
+ *   afetadas, e isso e o unico ponto onde o contrato toca em tarefas.
+ * @public
+ */
+export function runGroupRegistryContractTests(
+  createSubject: () => Promise<{
+    registry: IGroupRegistry;
+    atribuir: (groupId: string, quantas: number) => Promise<void>;
+  }>,
+): void {
+  const g = (id: string) => parseGroupId(id);
+
+  describe('IGroupRegistry contract', () => {
+    it('cria e lista', async () => {
+      const { registry } = await createSubject();
+
+      await registry.createGroup({ id: g('g-1'), name: 'Sprint' });
+
+      expect(await registry.listGroups()).toEqual([{ id: 'g-1', name: 'Sprint' }]);
+    });
+
+    it('acha pelo id, e devolve indefinido para o que nao existe', async () => {
+      const { registry } = await createSubject();
+      await registry.createGroup({ id: g('g-1'), name: 'Sprint' });
+
+      expect(await registry.findGroup(g('g-1'))).toEqual({ id: 'g-1', name: 'Sprint' });
+      expect(await registry.findGroup(g('g-2'))).toBeUndefined();
+    });
+
+    it('recusa id repetido', async () => {
+      const { registry } = await createSubject();
+      await registry.createGroup({ id: g('g-1'), name: 'Sprint' });
+
+      await expect(registry.createGroup({ id: g('g-1'), name: 'Outro' })).rejects.toThrow();
+    });
+
+    /*
+     * O ponto da entidade: o nome vive num lugar so, entao renomear e uma
+     * escrita — e nenhuma tarefa e tocada.
+     */
+    it('renomeia sem tocar em tarefa nenhuma', async () => {
+      const { registry, atribuir } = await createSubject();
+      await registry.createGroup({ id: g('g-1'), name: 'Sprint' });
+      await atribuir('g-1', 3);
+
+      await registry.renameGroup(g('g-1'), 'Sprint de outubro');
+
+      expect(await registry.findGroup(g('g-1'))).toEqual({ id: 'g-1', name: 'Sprint de outubro' });
+    });
+
+    it('recusa renomear o que nao existe', async () => {
+      const { registry } = await createSubject();
+
+      await expect(registry.renameGroup(g('g-404'), 'Qualquer')).rejects.toThrow();
+    });
+
+    it('apagar sem destino solta os membros, e diz quantos eram', async () => {
+      const { registry, atribuir } = await createSubject();
+      await registry.createGroup({ id: g('g-1'), name: 'Sprint' });
+      await atribuir('g-1', 3);
+
+      const resultado = await registry.deleteGroup(g('g-1'));
+
+      expect(resultado.reassigned).toBe(3);
+      expect(await registry.findGroup(g('g-1'))).toBeUndefined();
+    });
+
+    it('apagar com destino move os membros para la', async () => {
+      const { registry, atribuir } = await createSubject();
+      await registry.createGroup({ id: g('g-1'), name: 'Sprint' });
+      await registry.createGroup({ id: g('g-2'), name: 'Backlog' });
+      await atribuir('g-1', 2);
+
+      const resultado = await registry.deleteGroup(g('g-1'), { reassignTo: g('g-2') });
+
+      expect(resultado.reassigned).toBe(2);
+      expect(await registry.findGroup(g('g-2'))).toBeDefined();
+    });
+
+    it('recusa apagar o que nao existe', async () => {
+      const { registry } = await createSubject();
+
+      await expect(registry.deleteGroup(g('g-404'))).rejects.toThrow();
+    });
+  });
+}

package/src/group-registry.types.ts

@@ -0,0 +1,47 @@
+import type { Group, GroupId } from '@opentask/taskin-types';
+
+/**
+ * O que acontece com os membros quando o grupo e apagado.
+ *
+ * Nao ha opcao de "nao dizer": tarefa apontando para grupo inexistente em
+ * silencio foi o unico resultado considerado inaceitavel ao decidir isto. As
+ * duas escolhas cobrem o que Redmine (`reassign_to_id`) e Jira (`moveIssuesTo`)
+ * ja oferecem na propria chamada de exclusao.
+ *
+ * @public
+ */
+export interface DeleteGroupOptions {
+  /**
+   * Para onde os membros vao. Ausente, eles ficam **sem grupo** — e a operacao
+   * informa quantos foram afetados, para o efeito nunca ser invisivel.
+   */
+  reassignTo?: GroupId;
+}
+
+/** @public */
+export interface DeleteGroupResult {
+  /** Quantas tarefas pertenciam ao grupo apagado. */
+  reassigned: number;
+}
+
+/**
+ * Operacoes de grupo que um provider oferece.
+ *
+ * Separado de `ITaskProvider` de proposito: nem toda fonte tem o conceito. Um
+ * provider que tenha implementa isto; um que nao tenha simplesmente nao o
+ * expoe, e quem consome descobre pela ausencia em vez de receber uma operacao
+ * que falha — o mesmo erro do `-t sse` do `mcp-server`, que existia na flag e
+ * nao na implementacao.
+ *
+ * @public
+ */
+export interface IGroupRegistry {
+  listGroups: () => Promise<Group[]>;
+  findGroup: (id: GroupId) => Promise<Group | undefined>;
+  /** Falha quando o id ja existe. */
+  createGroup: (group: Group) => Promise<void>;
+  /** Falha quando o grupo nao existe. */
+  renameGroup: (id: GroupId, name: string) => Promise<void>;
+  /** Falha quando o grupo nao existe. */
+  deleteGroup: (id: GroupId, options?: DeleteGroupOptions) => Promise<DeleteGroupResult>;
+}

package/src/index.ts

@@ -1,6 +1,10 @@
 // Re-export commonly used types from @opentask/taskin-types for convenience
 export type { Task, TaskStatus, TaskType, User } from '@opentask/taskin-types';
+export * from './filter-tasks/index';
+export * from './group-registry.types';
 export * from './metrics.types';
+export * from './numerar-prioridade/index';
+export * from './ordenar-tarefas/index';
 export * from './task-manager';
 export * from './task-manager.types';
 export * from './user-registry.types';

package/src/numerar-prioridade/index.ts

@@ -0,0 +1 @@
+export * from './numerar-prioridade.js';

package/src/numerar-prioridade/numerar-prioridade.test.ts

@@ -0,0 +1,69 @@
+import type { Task } from '@opentask/taskin-types';
+import { parseTaskId } from '@opentask/taskin-types';
+import { describe, expect, it } from 'vitest';
+import { numerarPrioridade } from './numerar-prioridade.js';
+
+const tarefa = (id: string, order?: number): Task =>
+  ({ id: parseTaskId(id), title: `Tarefa ${id}`, status: 'pending', type: 'feat', order }) as Task;
+
+const ids = (ts: readonly Task[]) => ts.map((t) => String(t.id));
+
+/**
+ * Numeracao inicial de prioridade.
+ *
+ * Existe para eliminar o estado que custa caro: um projeto **meio numerado**.
+ * Enquanto metade das tarefas nao tem `order`, dar numero a uma do meio obriga a
+ * numerar todos os antecessores — 124 arquivos num projeto de 500, medido. Com o
+ * projeto inteiro numerado de uma vez, num ato deliberado, todo movimento
+ * seguinte custa um arquivo.
+ *
+ * A funcao devolve **so** o que precisa mudar, e nao a lista inteira: quem chama
+ * grava exatamente isso.
+ */
+describe('numerarPrioridade', () => {
+  it('num projeto sem nenhuma prioridade, numera todas preservando a ordem', () => {
+    const tarefas = [tarefa('001'), tarefa('002'), tarefa('003')];
+
+    const mudancas = numerarPrioridade(tarefas);
+
+    expect(ids(mudancas)).toEqual(['001', '002', '003']);
+    expect(mudancas.map((t) => t.order)).toEqual([100, 200, 300]);
+  });
+
+  /*
+   * Quem ja priorizou tomou uma decisao, e o comando preenche as lacunas em
+   * volta dela em vez de reescreve-la.
+   */
+  it('mantem o numero de quem ja tem, e so preenche as lacunas', () => {
+    const tarefas = [tarefa('001', 50), tarefa('002'), tarefa('003', 900)];
+
+    const mudancas = numerarPrioridade(tarefas);
+
+    expect(ids(mudancas)).toEqual(['002']);
+    const nova = mudancas[0]?.order ?? 0;
+    expect(nova).toBeGreaterThan(50);
+    expect(nova).toBeLessThan(900);
+  });
+
+  /*
+   * Seguro de pôr num script ou num hook: a segunda passada nao escreve nada.
+   */
+  it('rodar de novo nao muda nada', () => {
+    const tarefas = [tarefa('001'), tarefa('002'), tarefa('003')];
+
+    const primeira = numerarPrioridade(tarefas);
+    const segunda = numerarPrioridade(primeira.length ? aplicar(tarefas, primeira) : tarefas);
+
+    expect(segunda).toEqual([]);
+  });
+
+  it('nao devolve nada quando todas ja estao numeradas e em ordem', () => {
+    expect(numerarPrioridade([tarefa('001', 100), tarefa('002', 200)])).toEqual([]);
+  });
+});
+
+/** Aplica as mudancas devolvidas, como quem grava faria. */
+function aplicar(tarefas: readonly Task[], mudancas: readonly Task[]): Task[] {
+  const por = new Map(mudancas.map((t) => [String(t.id), t]));
+  return tarefas.map((t) => por.get(String(t.id)) ?? t);
+}

package/src/numerar-prioridade/numerar-prioridade.ts

@@ -0,0 +1,80 @@
+import type { Task } from '@opentask/taskin-types';
+
+/**
+ * Passo largo de proposito.
+ *
+ * Com 100 cabem muitos movimentos entre dois vizinhos antes de a renumeracao
+ * local precisar acontecer. Com 10 — o passo que o quadro de priorizacao usava —
+ * o espaco acaba depressa, e cada esgotamento custa escrita em arquivo.
+ */
+export const PASSO_DE_PRIORIDADE = 100;
+
+/**
+ * Devolve as tarefas que precisam de um `order` novo, e so elas.
+ *
+ * ## Por que isto existe
+ *
+ * O custo de reordenar no quadro de priorizacao ja e de um arquivo por
+ * movimento — **exceto** num projeto meio numerado. Ali, dar numero a uma tarefa
+ * do meio obriga a numerar todos os antecessores, porque uma tarefa sem `order`
+ * ordena por ultimo e nao tem posicao propria entre as numeradas. Num projeto de
+ * 500 tarefas com metade sem numero, isso chegou a 124 arquivos.
+ *
+ * A saida nao e um algoritmo mais esperto: e acabar com o estado meio numerado.
+ * Depois desta passada, ou o projeto inteiro tem numero, ou nunca foi priorizado
+ * — e todo movimento seguinte custa um arquivo.
+ *
+ * ## O que ela preserva
+ *
+ * A ordem relativa em que as tarefas chegaram, e o numero de quem ja tem um.
+ * Quem priorizou tomou uma decisao; o comando preenche as lacunas em volta dela
+ * em vez de reescreve-la.
+ *
+ * @param tarefas - Na ordem em que devem ficar
+ * @returns Copias apenas das tarefas que mudaram, prontas para gravar. Vazio
+ *   quando nao ha nada a fazer — o que torna uma segunda passada inofensiva.
+ * @public
+ */
+export function numerarPrioridade(tarefas: readonly Task[], passo = PASSO_DE_PRIORIDADE): Task[] {
+  const mudancas: Task[] = [];
+  let anterior = 0;
+
+  for (let i = 0; i < tarefas.length; i++) {
+    const atual = tarefas[i];
+    if (!atual) continue;
+
+    if (atual.order !== undefined && atual.order > anterior) {
+      anterior = atual.order;
+      continue;
+    }
+
+    /*
+     * Precisa de numero. O teto e o proximo valor ja existente que ainda esta a
+     * frente — respeita-lo e o que preserva a decisao de quem priorizou.
+     */
+    const teto = tarefas.slice(i + 1).find((t) => t?.order !== undefined && t.order > anterior)?.order;
+    const valor = teto === undefined ? anterior + passo : Math.floor((anterior + teto) / 2);
+
+    if (!(valor > anterior) || (teto !== undefined && valor >= teto)) {
+      /*
+       * Sem espaco entre os vizinhos: abre espaco andando para a frente e para
+       * no primeiro que ja estiver alem. A renumeracao fica na vizinhanca.
+       */
+      let corrido = anterior;
+      for (let j = i; j < tarefas.length; j++) {
+        const item = tarefas[j];
+        if (!item) continue;
+        if (j > i && item.order !== undefined && item.order > corrido) break;
+        corrido += passo;
+        mudancas.push({ ...item, order: corrido });
+      }
+      anterior = corrido;
+      continue;
+    }
+
+    mudancas.push({ ...atual, order: valor });
+    anterior = valor;
+  }
+
+  return mudancas;
+}

package/src/ordenar-tarefas/index.ts

@@ -0,0 +1 @@
+export * from './ordenar-tarefas.js';

package/src/ordenar-tarefas/ordenar-tarefas.test.ts

@@ -0,0 +1,92 @@
+import type { Task } from '@opentask/taskin-types';
+import { parseGroupId, parseTaskId } from '@opentask/taskin-types';
+import { describe, expect, it } from 'vitest';
+import { agruparTarefas, ordenarTarefas } from './ordenar-tarefas.js';
+
+const t = (id: string, extra: Partial<Task> = {}): Task =>
+  ({ id: parseTaskId(id), title: `Tarefa ${id}`, status: 'pending', type: 'feat', ...extra }) as Task;
+
+const ids = (ts: readonly Task[]) => ts.map((x) => String(x.id));
+
+/**
+ * A ordenacao que o dashboard ja usava, agora onde as tres superficies alcancam.
+ *
+ * Ela vivia em `use-prioritization.ts`, dentro do pacote **Vue** — inalcancavel
+ * para a CLI e para o servidor MCP. O `taskin list` devolvia as tarefas na
+ * ordem em que o provider as achava, que na pratica e por id: a coluna de
+ * prioridade subia e descia sem padrao, e quem lia precisava reordenar de
+ * cabeca. Foi assim que um agente autonomo escolheu uma tarefa de prioridade 30
+ * tendo uma de 255 na mesma lista.
+ */
+describe('ordenarTarefas', () => {
+  it('manual ordena por prioridade, com quem nao tem por ultimo', () => {
+    const tarefas = [t('001', { order: 30 }), t('002'), t('003', { order: 10 })];
+
+    expect(ids(ordenarTarefas(tarefas, 'manual'))).toEqual(['003', '001', '002']);
+  });
+
+  it('manual e estavel entre empatados', () => {
+    const tarefas = [t('001', { order: 10 }), t('002', { order: 10 }), t('003', { order: 10 })];
+
+    expect(ids(ordenarTarefas(tarefas, 'manual'))).toEqual(['001', '002', '003']);
+  });
+
+  it('difficulty ordena do mais facil ao mais dificil, e o inverso', () => {
+    const tarefas = [t('001', { difficulty: 5 }), t('002', { difficulty: 1 }), t('003', { difficulty: 3 })];
+
+    expect(ids(ordenarTarefas(tarefas, 'diff-asc'))).toEqual(['002', '003', '001']);
+    expect(ids(ordenarTarefas(tarefas, 'diff-desc'))).toEqual(['001', '003', '002']);
+  });
+
+  it('nao altera a lista recebida', () => {
+    const tarefas = [t('001', { order: 30 }), t('002', { order: 10 })];
+    ordenarTarefas(tarefas, 'manual');
+
+    expect(ids(tarefas)).toEqual(['001', '002']);
+  });
+});
+
+/**
+ * Agrupar e separado de ordenar, e de proposito.
+ *
+ * No dashboard as duas coisas vinham juntas porque a arvore era so para
+ * desenhar caixas. Na saida de maquina quem consome decide — e separar deixa a
+ * CLI ordenar sem agrupar quando ninguem pediu grupo.
+ */
+describe('agruparTarefas', () => {
+  const g1 = parseGroupId('g-1');
+
+  it('junta membros do mesmo grupo, esteja onde estiver na ordem', () => {
+    const tarefas = [t('001', { groupId: g1 }), t('002'), t('003', { groupId: g1 })];
+
+    const nos = agruparTarefas(tarefas, { 'g-1': 'Sprint' });
+
+    expect(nos).toHaveLength(2);
+    expect(nos[0]).toMatchObject({ kind: 'group', groupId: 'g-1', groupName: 'Sprint', hidden: 0 });
+    expect(nos[0]?.kind === 'group' && ids(nos[0].tasks)).toEqual(['001', '003']);
+  });
+
+  /*
+   * O grupo parcial, decidido: mostra os membros que casam, e diz quantos o
+   * filtro escondeu. Nunca alarga o filtro para trazer o grupo inteiro.
+   */
+  it('diz quantos membros o filtro deixou de fora', () => {
+    const tarefas = [t('001', { groupId: g1 })];
+
+    const nos = agruparTarefas(tarefas, { 'g-1': 'Sprint' }, { 'g-1': 7 });
+
+    expect(nos[0]).toMatchObject({ kind: 'group', hidden: 6 });
+  });
+
+  it('tarefa sem grupo fica solta, na ordem em que veio', () => {
+    const nos = agruparTarefas([t('001'), t('002')], {});
+
+    expect(nos.map((n) => n.kind)).toEqual(['task', 'task']);
+  });
+
+  it('grupo sem nome no registro ainda aparece, pelo id', () => {
+    const nos = agruparTarefas([t('001', { groupId: g1 })], {});
+
+    expect(nos[0]).toMatchObject({ kind: 'group', groupId: 'g-1', groupName: undefined });
+  });
+});

package/src/ordenar-tarefas/ordenar-tarefas.ts

@@ -0,0 +1,135 @@
+import type { Task } from '@opentask/taskin-types';
+
+/**
+ * Como uma listagem pode ser ordenada.
+ *
+ * O mesmo vocabulario que o quadro de priorizacao do dashboard usa. Manter as
+ * grafias iguais entre as superficies vale mais que elegancia local: quem le a
+ * documentacao de uma reconhece a outra.
+ *
+ * @public
+ */
+export type ModoDeOrdenacao = 'manual' | 'diff-asc' | 'diff-desc';
+
+/**
+ * O que a ordenacao precisa saber, e nada alem disso.
+ *
+ * Exigir `Task` inteira deixaria a funcao inalcancavel para quem tem outra
+ * forma de tarefa — o quadro de priorizacao do dashboard, por exemplo, usa um
+ * modelo de tela proprio. Pedir so os dois campos que ela le e o que permite as
+ * duas superficies compartilharem a regra em vez de cada uma ter a sua copia.
+ *
+ * @public
+ */
+export interface OrdenavelPorPrioridade {
+  readonly order?: number;
+  readonly difficulty?: number;
+}
+
+/** Um no da listagem: uma tarefa solta, ou um grupo com os membros que casaram. */
+export type NoDaListagem<TTask extends Task = Task> =
+  | { readonly kind: 'task'; readonly task: TTask }
+  | {
+      readonly kind: 'group';
+      readonly groupId: string;
+      /** `undefined` quando o registro nao conhece o grupo. */
+      readonly groupName: string | undefined;
+      readonly tasks: readonly TTask[];
+      /** Quantos membros o filtro deixou de fora. Zero quando o grupo veio inteiro. */
+      readonly hidden: number;
+    };
+
+/**
+ * Ordena uma listagem, sem alterar a lista recebida.
+ *
+ * Vivia dentro do pacote Vue do dashboard, inalcancavel para a CLI e para o
+ * servidor MCP — e por isso `taskin list` devolvia as tarefas na ordem em que o
+ * provider as achava, que na pratica e por id.
+ *
+ * `manual` usa o `order`, com quem nao tem por ultimo e estabilidade no resto.
+ * Os dois modos de dificuldade usam o `difficulty`.
+ *
+ * @public
+ */
+export function ordenarTarefas<TTask extends OrdenavelPorPrioridade>(
+  tarefas: readonly TTask[],
+  modo: ModoDeOrdenacao = 'manual',
+): TTask[] {
+  const comIndice = tarefas.map((task, index) => ({ task, index }));
+
+  const campo = (t: TTask) => (modo === 'manual' ? t.order : t.difficulty);
+  const sinal = modo === 'diff-desc' ? -1 : 1;
+
+  comIndice.sort((a, b) => {
+    const va = campo(a.task);
+    const vb = campo(b.task);
+
+    // Quem nao tem valor vai para o fim, qualquer que seja a direcao.
+    if (va === undefined && vb === undefined) return a.index - b.index;
+    if (va === undefined) return 1;
+    if (vb === undefined) return -1;
+    if (va !== vb) return (va - vb) * sinal;
+
+    return a.index - b.index;
+  });
+
+  return comIndice.map(({ task }) => task);
+}
+
+/**
+ * Junta os membros de um grupo num no so, **por identidade**.
+ *
+ * Separado de {@link ordenarTarefas} de proposito. No dashboard as duas coisas
+ * vinham juntas porque a arvore existia para desenhar caixas; aqui quem consome
+ * decide se quer agrupar.
+ *
+ * Agrupa pelo `groupId`, e nao por adjacencia: membros separados por um filtro
+ * ou por uma ordenacao continuam sendo **um** grupo. Agrupar por adjacencia era
+ * o defeito da task-072, que partia o mesmo grupo em dois nos com o mesmo nome.
+ *
+ * @param tarefas - Ja ordenadas; a ordem dos grupos segue a do primeiro membro
+ * @param nomes - O que o registro de grupos sabe, por id
+ * @param totais - Quantos membros cada grupo tem **antes** do filtro. O que
+ *   falta vira `hidden`, para o leitor saber que nao esta vendo o grupo inteiro
+ *   em vez de o filtro se alargar sozinho e trazer o resto.
+ * @public
+ */
+export function agruparTarefas<TTask extends Task>(
+  tarefas: readonly TTask[],
+  nomes: Readonly<Record<string, string>> = {},
+  totais: Readonly<Record<string, number>> = {},
+): NoDaListagem<TTask>[] {
+  const nos: NoDaListagem<TTask>[] = [];
+  const porGrupo = new Map<string, TTask[]>();
+
+  for (const task of tarefas) {
+    const id = task.groupId === undefined ? undefined : String(task.groupId);
+
+    if (id === undefined) {
+      nos.push({ kind: 'task', task });
+      continue;
+    }
+
+    const existente = porGrupo.get(id);
+    if (existente) {
+      existente.push(task);
+      continue;
+    }
+
+    const membros = [task];
+    porGrupo.set(id, membros);
+    nos.push({
+      kind: 'group',
+      groupId: id,
+      groupName: nomes[id],
+      tasks: membros,
+      hidden: 0,
+    });
+  }
+
+  return nos.map((no) =>
+    no.kind === 'group'
+      ? { ...no, hidden: Math.max(0, (totais[no.groupId] ?? no.tasks.length) - no.tasks.length) }
+      : no,
+  );
+}

package/src/task-manager.ts

@@ -1,7 +1,10 @@
 import type { Task, TaskId, TaskStatus } from '@opentask/taskin-types';
+import type { IGroupRegistry } from './group-registry.types';
+import { numerarPrioridade } from './numerar-prioridade/index';
 import type {
   CreateTaskOptions,
   CreateTaskResult,
+  CriterioEmAberto,
   ITaskManager,
   ITaskProvider,
   LintResult,
@@ -65,6 +68,73 @@ export class TaskManager<TTask extends Task = Task> implements ITaskManager<TTas
     return updatedTask;
   }
 
+  /**
+   * Every task the configured provider knows about.
+   *
+   * Pass-through on purpose: the manager owns the state transitions, not the
+   * storage. Having it here is what lets a consumer holding only the manager —
+   * the MCP server — answer "what work exists?".
+   */
+  async getAllTasks(): Promise<TTask[]> {
+    return await this.taskProvider.getAllTasks();
+  }
+
+  /** Repassa o registro do provider, quando ele tem um. */
+  get groupRegistry(): IGroupRegistry | undefined {
+    return (this.taskProvider as { groupRegistry?: IGroupRegistry }).groupRegistry;
+  }
+
+  async prioritizeAll(options: { dryRun?: boolean } = {}): Promise<{
+    total: number;
+    withoutPriority: number;
+    changed: number;
+  }> {
+    const tarefas = await this.taskProvider.getAllTasks();
+
+    /*
+     * Quem ja tem numero define a ordem; quem nao tem entra depois, na sequencia
+     * em que o provider devolveu.
+     */
+    const ordenadas = [...tarefas].sort((a, b) => {
+      if (a.order === undefined && b.order === undefined) return 0;
+      if (a.order === undefined) return 1;
+      if (b.order === undefined) return -1;
+      return a.order - b.order;
+    });
+
+    const mudancas = numerarPrioridade(ordenadas);
+    const semNumero = tarefas.filter((t) => t.order === undefined).length;
+
+    if (!options.dryRun) {
+      for (const tarefa of mudancas) {
+        await this.taskProvider.updateTask(tarefa as TTask);
+      }
+    }
+
+    return { total: tarefas.length, withoutPriority: semNumero, changed: mudancas.length };
+  }
+
+  /**
+   * Conclui a tarefa e **relata** o que ficou em aberto.
+   *
+   * Avisa, e nao recusa. Fechar uma tarefa e um gesto que acontece uma vez,
+   * muitas vezes com pressa; recusar ali torna o comando fragil e ensina a
+   * contornar. O portao duro vive no `lint`, que roda em CI e quebra o build —
+   * aqui o papel e dizer, no momento em que a pessoa ainda esta olhando, o que
+   * ficou para tras.
+   *
+   * Um provider sem a capacidade conclui sem portao nenhum.
+   */
+  async finishTaskComRelato(taskId: TaskId): Promise<{ task: TTask; blockers: CriterioEmAberto[] }> {
+    const task = await this.taskProvider.findTask(taskId);
+    if (!task) throw new Error(`Task with ID '${taskId}' not found.`);
+
+    const blockers = (await this.taskProvider.getCompletionBlockers?.(task)) ?? [];
+    const atualizada = await this.finishTask(taskId);
+
+    return { task: atualizada, blockers };
+  }
+
   async finishTask(taskId: TaskId): Promise<TTask> {
     const task = await this.taskProvider.findTask(taskId);