@opentask/taskin-task-manager 3.0.2 → 3.2.0

package/src/task-manager.types.ts

@@ -1,4 +1,5 @@
 import type { Task, TaskId, TaskType } from '@opentask/taskin-types';
+import type { IGroupRegistry } from './group-registry.types.js';
 
 /**
  * Options for creating a new task
@@ -40,6 +41,14 @@ export type ValidationSeverity = 'error' | 'warning' | 'info';
  * A validation error or warning found during linting
  * @public
  */
+/** Um criterio que ainda impede a conclusao. */
+export interface CriterioEmAberto {
+  /** O texto do item, como escrito. */
+  readonly texto: string;
+  /** Onde ele esta, quando a fonte sabe dizer. */
+  readonly linha?: number;
+}
+
 export interface ValidationIssue {
   /** The file or task that has the issue */
   file: string;
@@ -130,6 +139,20 @@ export interface ITaskProvider<TTask extends Task = Task> {
    * @returns The lint result with any validation issues found
    */
   lint: (fix?: boolean) => Promise<LintResult>;
+
+  /**
+   * Os criterios de conclusao que ainda bloqueiam esta tarefa, se a fonte tiver
+   * o conceito.
+   *
+   * **Opcional de proposito.** Checklist e uma forma do provider de arquivos: o
+   * Jira tem subtarefas, o GitHub tem itens de lista na descricao. Um provider
+   * sem nada equivalente simplesmente nao implementa, e o `finishTask` conclui
+   * sem portao — em vez de chamar algo que falha.
+   *
+   * O conceito e de dominio ("o que falta para isto estar pronto?"); a
+   * representacao e de provider.
+   */
+  getCompletionBlockers?: (task: TTask) => Promise<CriterioEmAberto[]>;
 }
 
 /**
@@ -154,6 +177,64 @@ export interface ITaskManager<TTask extends Task = Task> {
    */
   finishTask: (taskId: TaskId) => Promise<TTask>;
 
+  /**
+   * Every task the configured provider knows about.
+   *
+   * Delegates to the provider, like {@link ITaskManager.lint} does. Listing is
+   * a domain question — "what work exists?" — and a consumer that only holds a
+   * manager should not need the provider to answer it. The MCP server did, and
+   * shipped a `taskin://tasks` resource that answered with a placeholder.
+   *
+   * @returns The tasks, in whatever order the provider returns them
+   */
+  getAllTasks: () => Promise<TTask[]>;
+
+  /**
+   * Da a cada tarefa um numero de prioridade, de uma vez.
+   *
+   * E operacao de dominio, e nao um `updateTask` generico, por dois motivos.
+   *
+   * O primeiro e de desenho: a regra da numeracao — preservar a ordem, manter o
+   * numero de quem ja tem, abrir espaco quando faltar — passa a viver num lugar
+   * so, em vez de ser reescrita pela CLI e pelo servidor MCP.
+   *
+   * O segundo e de tipo: um metodo que **consome** `TTask` torna a interface
+   * contravariante nele, e um `ITaskManager<TarefaEspecifica>` deixa de poder
+   * ser usado onde se espera `ITaskManager<Task>`. Uma operacao que so devolve
+   * numeros nao tem esse problema.
+   *
+   * Existe porque um projeto **meio numerado** cobra caro: mover uma tarefa do
+   * meio da regiao sem numero reescreve todos os antecessores — 124 arquivos num
+   * projeto de 500, medido. Depois desta operacao, todo movimento custa um.
+   *
+   * @param options - `dryRun` apenas conta, sem gravar
+   * @returns Quantas existem, quantas estavam sem numero, e quantas mudaram
+   */
+  /**
+   * Os grupos, quando a fonte tem o conceito — `undefined` quando nao tem.
+   *
+   * Opcional de proposito: o GitHub mapeia para milestone, o Redmine para
+   * categoria, e uma fonte sem nada equivalente simplesmente nao oferece. Quem
+   * consome descobre pela ausencia, em vez de chamar algo que falha.
+   */
+  readonly groupRegistry?: IGroupRegistry;
+
+  /**
+   * Conclui a tarefa e relata os criterios que ficaram em aberto.
+   *
+   * Avisa, e nao recusa: fechar e um gesto unico, muitas vezes com pressa, e
+   * recusar ali torna o comando fragil. O portao duro vive no `lint`.
+   *
+   * O relato vem vazio quando o provider nao tem o conceito de checklist.
+   */
+  finishTaskComRelato: (taskId: TaskId) => Promise<{ task: TTask; blockers: CriterioEmAberto[] }>;
+
+  prioritizeAll: (options?: { dryRun?: boolean }) => Promise<{
+    total: number;
+    withoutPriority: number;
+    changed: number;
+  }>;
+
   /**
    * Mark a task as ready for review.
    * Transitions the task from 'in-progress' to 'in-review' status.
@@ -197,4 +278,18 @@ export interface ITaskManager<TTask extends Task = Task> {
    * @returns The lint result with any validation issues found
    */
   lint: (fix?: boolean) => Promise<LintResult>;
+
+  /**
+   * Os criterios de conclusao que ainda bloqueiam esta tarefa, se a fonte tiver
+   * o conceito.
+   *
+   * **Opcional de proposito.** Checklist e uma forma do provider de arquivos: o
+   * Jira tem subtarefas, o GitHub tem itens de lista na descricao. Um provider
+   * sem nada equivalente simplesmente nao implementa, e o `finishTask` conclui
+   * sem portao — em vez de chamar algo que falha.
+   *
+   * O conceito e de dominio ("o que falta para isto estar pronto?"); a
+   * representacao e de provider.
+   */
+  getCompletionBlockers?: (task: TTask) => Promise<CriterioEmAberto[]>;
 }

package/src/testing.ts

@@ -0,0 +1,8 @@
+/**
+ * Contratos que as implementacoes provam contra si mesmas.
+ *
+ * Exportado por `@opentask/taskin-task-manager/testing` para o `vitest` nunca
+ * entrar no grafo de execucao do pacote.
+ */
+export * from './group-registry.contract.js';
+export * from './user-registry.contract.js';

package/src/user-registry.contract.ts

@@ -40,7 +40,7 @@ export function runUserRegistryContractTests(createSubject: () => Promise<IUserR
         const user = registry.resolveUser('joao.silva');
         expect(user).toBeDefined();
         expect(user!.id).toBe('joao.silva');
-        expect(user!.avatar).toMatch(/^https:\/\/www\.gravatar\.com\/avatar\/[a-f0-9]{32}\?d=mp$/);
+        expect(user!.avatarHash).toMatch(/^[a-f0-9]{32}$/);
       });
 
       it('should return user by name (case-insensitive)', async () => {
@@ -54,7 +54,7 @@ export function runUserRegistryContractTests(createSubject: () => Promise<IUserR
         const user = registry.resolveUser('Maria Souza');
         expect(user).toBeDefined();
         expect(user!.id).toBe('maria');
-        expect(user!.avatar).toMatch(/^https:\/\/www\.gravatar\.com\/avatar\/[a-f0-9]{32}\?d=mp$/);
+        expect(user!.avatarHash).toMatch(/^[a-f0-9]{32}$/);
       });
 
       it('should return undefined for unknown user', async () => {
@@ -65,21 +65,21 @@ export function runUserRegistryContractTests(createSubject: () => Promise<IUserR
     });
 
     describe('createTemporaryUser', () => {
-      it('should create user with Gravatar URL', async () => {
+      it('should create user with an avatar identity hash', async () => {
         const registry = await createSubject();
         const user = registry.createTemporaryUser('Carlos');
 
         expect(user.id).toBe('carlos');
         expect(user.name).toBe('Carlos');
         expect(user.email).toBe('carlos@example.com');
-        expect(user.avatar).toMatch(/^https:\/\/www\.gravatar\.com\/avatar\/[a-f0-9]{32}\?d=mp$/);
+        expect(user.avatarHash).toMatch(/^[a-f0-9]{32}$/);
       });
 
-      it('should create different Gravatar URLs for different inputs', async () => {
+      it('should create different avatar hashes for different inputs', async () => {
         const registry = await createSubject();
         const user1 = registry.createTemporaryUser('Alice');
         const user2 = registry.createTemporaryUser('Bob');
-        expect(user1.avatar).not.toBe(user2.avatar);
+        expect(user1.avatarHash).not.toBe(user2.avatarHash);
       });
     });