@opentask/taskin-task-manager 3.1.0 → 3.2.0

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

@@ -0,0 +1,175 @@
+import { TaskStatusSchema, TaskTypeSchema } from '@opentask/taskin-types';
+import { z } from 'zod';
+
+/**
+ * Os criterios que restringem uma listagem, definidos **uma vez so**.
+ *
+ * Antes cada criterio existia em cinco lugares escritos a mao: o tipo, a flag da
+ * CLI, o mapeamento da CLI, o schema JSON do MCP e o mapeamento do MCP.
+ * Acrescentar um exigia lembrar dos cinco, e esquecer nao quebrava nada — so
+ * fazia uma superficie ficar para tras, em silencio. O sintoma ja tinha
+ * aparecido: o criterio chamava-se `assignee` e a flag da CLI chamava-se
+ * `--user`, duas grafias para a mesma coisa que ninguem decidiu.
+ *
+ * Aqui o schema e a fonte. As superficies **derivam** dele:
+ *
+ * - `TaskFilterCriteria` e `z.infer` deste schema — o tipo nao se escreve a mao.
+ * - O schema JSON do `list_tasks` sai de `filterCriteriaJsonSchema`.
+ * - As opcoes do `taskin list` saem de `filterCriteriaCliOptions`.
+ * - A validacao e a conversao saem de `parseFilterCriteria` — os dois
+ *   mapeamentos a mao desaparecem.
+ *
+ * O portao que fecha o circuito e o `satisfies Record<keyof TaskFilterCriteria,
+ * ...>` em {@link FILTER_CRITERIA_SURFACES}: acrescentar um criterio ao schema e
+ * **nao** ligar a superficie vira erro de compilacao, que e o unico lembrete que
+ * nao depende de ninguem lembrar.
+ *
+ * **Como acrescentar um criterio novo.** Duas linhas, e o compilador cobra a
+ * segunda:
+ *
+ * 1. uma propriedade `.optional()` em {@link FilterCriteriaSchema};
+ * 2. a entrada correspondente em {@link FILTER_CRITERIA_SURFACES} (descricao +
+ *    onde mora na CLI).
+ *
+ * A CLI, o schema JSON do MCP e a validacao passam a conhece-lo sem mais nenhuma
+ * edicao. Esquecer o passo 2 nao compila.
+ */
+export const FilterCriteriaSchema = z.object({
+  status: TaskStatusSchema.optional(),
+  type: TaskTypeSchema.optional(),
+  assignee: z.string().optional(),
+  open: z.boolean().optional(),
+  closed: z.boolean().optional(),
+  active: z.boolean().optional(),
+  text: z.string().optional(),
+});
+
+/**
+ * O que restringe uma listagem de tarefas.
+ *
+ * Todos os campos sao opcionais e **se somam**: informar dois exige os dois. Um
+ * criterio ausente nao restringe nada. Derivado de {@link FilterCriteriaSchema}
+ * — mudar o schema muda o tipo.
+ *
+ * @public
+ */
+export type TaskFilterCriteria = z.infer<typeof FilterCriteriaSchema>;
+
+/** Onde um criterio aparece na linha de comando. */
+export type CriterionCli = { readonly kind: 'positional' } | { readonly kind: 'flag'; readonly short?: string };
+
+/**
+ * O que uma superficie precisa saber de um criterio alem da sua forma: o texto
+ * de ajuda (compartilhado entre `--help` da CLI e a propriedade do MCP) e onde
+ * ele mora na linha de comando.
+ */
+export interface CriterionSurface {
+  readonly description: string;
+  readonly cli: CriterionCli;
+}
+
+/**
+ * A superficie de cada criterio, gateada a cobrir **todos** os campos de
+ * {@link TaskFilterCriteria}.
+ *
+ * O `satisfies Record<keyof TaskFilterCriteria, ...>` e o portao: acrescentar um
+ * criterio ao schema sem uma entrada aqui nao compila.
+ */
+export const FILTER_CRITERIA_SURFACES = {
+  status: { description: 'Exact status (pending, in-progress, done, ...)', cli: { kind: 'flag', short: 's' } },
+  type: { description: 'Exact type (feat, fix, chore, ...)', cli: { kind: 'flag', short: 't' } },
+  assignee: { description: 'Assignee id or name, whole or in part', cli: { kind: 'flag', short: 'u' } },
+  open: { description: 'Only tasks still open', cli: { kind: 'flag' } },
+  closed: { description: 'Only tasks already closed', cli: { kind: 'flag' } },
+  active: {
+    description: 'Only tasks started and not finished (in-progress, paused, in-review)',
+    cli: { kind: 'flag' },
+  },
+  text: { description: 'Free text over id, title, status and assignee', cli: { kind: 'positional' } },
+} satisfies Record<keyof TaskFilterCriteria, CriterionSurface>;
+
+type SurfaceMap = Record<string, CriterionSurface>;
+
+/** O schema JSON de entrada de uma ferramenta MCP: objeto com propriedades. */
+export interface FilterJsonSchema {
+  readonly type: 'object';
+  readonly properties: Record<string, unknown>;
+  readonly required: string[];
+}
+
+/** Uma opcao de CLI, na forma que o `commander` (e o `defineCommand`) consome. */
+export interface FilterCliOption {
+  readonly flags: string;
+  readonly description: string;
+}
+
+/**
+ * O schema JSON das propriedades de filtro, derivado do zod.
+ *
+ * Nao e aposta: o `packages/types-ts` ja gera JSON Schema de schemas zod pelo
+ * mesmo `z.toJSONSchema()` desde a migracao para o zod 4. Aqui e o mesmo
+ * mecanismo, aplicado ao schema de filtro, com a descricao de cada campo vinda
+ * da superficie unica.
+ *
+ * Recebe schema e superficies para poder ser exercitado com um criterio
+ * ficticio nos testes — a prova de que deriva, em vez de repetir a mao.
+ */
+export function filterCriteriaJsonSchema(
+  schema: z.ZodObject = FilterCriteriaSchema,
+  surfaces: SurfaceMap = FILTER_CRITERIA_SURFACES,
+): FilterJsonSchema {
+  const described = z.object(
+    Object.fromEntries(
+      Object.entries(schema.shape).map(([key, prop]) => [
+        key,
+        (prop as z.ZodType).describe(surfaces[key]?.description ?? ''),
+      ]),
+    ),
+  );
+
+  const json = z.toJSONSchema(described, { target: 'draft-7', io: 'output' }) as {
+    properties?: Record<string, unknown>;
+  };
+
+  return { type: 'object', properties: json.properties ?? {}, required: [] };
+}
+
+/**
+ * As opcoes do `taskin list`, derivadas das superficies.
+ *
+ * Um criterio `positional` (o texto livre) nao vira flag: ele e o argumento
+ * `[filter]` do comando. Um criterio booleano nao leva valor (`--open`); os
+ * demais levam (`-s, --status <status>`). O tipo — booleano ou nao — sai do
+ * proprio schema JSON, e nao de uma segunda lista.
+ */
+export function filterCriteriaCliOptions(
+  schema: z.ZodObject = FilterCriteriaSchema,
+  surfaces: SurfaceMap = FILTER_CRITERIA_SURFACES,
+): FilterCliOption[] {
+  const { properties } = filterCriteriaJsonSchema(schema, surfaces);
+  const options: FilterCliOption[] = [];
+
+  for (const [key, surface] of Object.entries(surfaces)) {
+    if (surface.cli.kind !== 'flag') continue;
+
+    const short = surface.cli.short ? `-${surface.cli.short}, ` : '';
+    const takesValue = (properties[key] as { type?: string } | undefined)?.type !== 'boolean';
+    const flags = takesValue ? `${short}--${key} <${key}>` : `${short}--${key}`;
+
+    options.push({ flags, description: surface.description });
+  }
+
+  return options;
+}
+
+/**
+ * Valida os argumentos crus e os converte em {@link TaskFilterCriteria}.
+ *
+ * E o `parse` do proprio schema, sem mapeamento a mao. Chaves desconhecidas sao
+ * descartadas (o `--json` do CLI, por exemplo, nao e criterio); um valor com o
+ * tipo errado — um status fora do conjunto — passa a **falhar barulhento**, em
+ * vez de devolver lista vazia como se nao houvesse tarefa.
+ */
+export function parseFilterCriteria(raw: unknown): TaskFilterCriteria {
+  return FilterCriteriaSchema.parse(raw);
+}

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

@@ -82,3 +82,48 @@ describe('filterTasks', () => {
     expect(TAREFAS).toEqual(original);
   });
 });
+
+/**
+ * "Em andamento" nao e `in-progress`, e nao e `open`.
+ *
+ * `open` inclui `pending` — o que ainda nao comecou, e que no painel e ruido.
+ * `in-progress` sozinho e estreito demais: uma tarefa some da tela no instante
+ * em que alguem a pausa ou a manda para revisao, o que e enganoso.
+ *
+ * `active` e o meio que faltava: **comecou e nao terminou**. `blocked` fica de
+ * fora por decisao declarada — ninguem esta trabalhando numa bloqueada agora.
+ */
+describe('filtro active', () => {
+  const tarefas = [
+    tarefa({ id: '001', status: 'pending' }),
+    tarefa({ id: '002', status: 'in-progress' }),
+    tarefa({ id: '003', status: 'paused' }),
+    tarefa({ id: '004', status: 'in-review' }),
+    tarefa({ id: '005', status: 'blocked' }),
+    tarefa({ id: '006', status: 'done' }),
+    tarefa({ id: '007', status: 'canceled' }),
+  ];
+
+  it('traz o que comecou e nao terminou', () => {
+    const ids = filterTasks(tarefas, { active: true }).map((t) => String(t.id));
+
+    expect(ids).toEqual(['002', '003', '004']);
+  });
+
+  it('deixa pending de fora — nao comecou', () => {
+    expect(filterTasks(tarefas, { active: true }).map((t) => String(t.id))).not.toContain('001');
+  });
+
+  it('deixa blocked de fora, por decisao declarada', () => {
+    expect(filterTasks(tarefas, { active: true }).map((t) => String(t.id))).not.toContain('005');
+  });
+
+  it('e mais estreito que open e mais largo que in-progress', () => {
+    const abertas = filterTasks(tarefas, { open: true }).length;
+    const ativas = filterTasks(tarefas, { active: true }).length;
+    const emProgresso = filterTasks(tarefas, { status: 'in-progress' }).length;
+
+    expect(ativas).toBeLessThan(abertas);
+    expect(ativas).toBeGreaterThan(emProgresso);
+  });
+});

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

@@ -12,8 +12,22 @@ const EM_ABERTO: readonly TaskStatus[] = ['pending', 'in-progress', 'paused', 'i
 
 const ENCERRADOS: readonly TaskStatus[] = ['done', 'canceled'];
 
+/**
+ * Comecou e nao terminou.
+ *
+ * O meio que faltava entre `open` e `status: 'in-progress'`. `open` inclui
+ * `pending` — o que ainda nao comecou, e que num painel de acompanhamento e
+ * ruido. `in-progress` sozinho e estreito demais: a tarefa some da tela no
+ * instante em que alguem a pausa ou a manda para revisao.
+ *
+ * `blocked` fica de fora por decisao declarada: bloqueada e trabalho comecado,
+ * mas ninguem esta mexendo nela agora, e quem olha "o que esta andando" nao
+ * quer ve-la ali.
+ */
+const ATIVAS: readonly TaskStatus[] = ['in-progress', 'paused', 'in-review'];
+
 const contem = (valor: string | undefined, procurado: string): boolean =>
-  valor !== undefined && valor.toLowerCase().includes(procurado);
+  valor?.toLowerCase().includes(procurado) ?? false;
 
 /**
  * Casa o responsavel por id ou nome, inteiro ou em parte.
@@ -46,6 +60,8 @@ export function filterTasks(tasks: readonly Task[], criteria: TaskFilterCriteria
       return false;
     } else if (criteria.closed && !ENCERRADOS.includes(task.status)) {
       return false;
+    } else if (criteria.active && !ATIVAS.includes(task.status)) {
+      return false;
     }
 
     if (criteria.type !== undefined && task.type !== criteria.type) return false;
@@ -85,7 +101,6 @@ export function summarizeTask(task: Task): TaskSummary {
     ...(task.assignee && { assignee: { id: task.assignee.id, name: task.assignee.name } }),
     ...(task.order !== undefined && { priority: task.order }),
     ...(task.groupId && { groupId: task.groupId }),
-    ...(task.groupName && { groupName: task.groupName }),
     ...(task.difficulty !== undefined && { difficulty: task.difficulty }),
   };
 }

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

@@ -1,30 +1,13 @@
 import type { GroupId, TaskId, TaskStatus, TaskType } from '@opentask/taskin-types';
 
 /**
- * O que restringe uma listagem de tarefas.
+ * O que restringe uma listagem de tarefas — derivado do schema unico.
  *
- * Todos os campos sao opcionais e **se somam**: informar dois exige os dois.
- * Um criterio ausente nao restringe nada.
- *
- * @public
+ * 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 interface TaskFilterCriteria {
-  /** Status exato. */
-  readonly status?: TaskStatus;
-  /** Tipo exato. */
-  readonly type?: TaskType;
-  /**
-   * Responsavel, casado por id ou nome — inteiro ou em parte, sem distinguir
-   * maiuscula. Tarefa sem responsavel nunca casa.
-   */
-  readonly assignee?: string;
-  /** Apenas o que ainda esta em aberto. Ignorado quando `status` e informado. */
-  readonly open?: boolean;
-  /** Apenas o que foi encerrado. Ignorado quando `status` e informado. */
-  readonly closed?: boolean;
-  /** Busca livre em id, titulo, status e responsavel. */
-  readonly text?: string;
-}
+export type { TaskFilterCriteria } from './filter-criteria.js';
 
 /**
  * A forma de uma tarefa numa listagem — o que identifica, nao o que ela diz.
@@ -39,6 +22,5 @@ export interface TaskSummary {
   readonly assignee?: { readonly id: string; readonly name: string };
   readonly priority?: number;
   readonly groupId?: GroupId;
-  readonly groupName?: string;
   readonly difficulty?: number;
 }

package/src/filter-tasks/index.ts

@@ -1,2 +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 { TaskFilterCriteria, TaskSummary } from './filter-tasks.types.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,7 +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';