@aelinrezende/pipa-core 1.0.0 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +131 -131
  2. package/index.js +66 -66
  3. package/package.json +2 -2
  4. package/pipa.config.d.ts.map +1 -1
package/README.md CHANGED
@@ -1,131 +1,131 @@
1
- # pipa-core
2
-
3
- SDK para criar extensões do Pi com features reutilizáveis, API de execução e eventos de domínio tipados.
4
-
5
- Inclui `applyFeatures`, `PipaBaseFeature`, `PipaEvent`, `PipaApi` e o mapa `DomainEventMap`.
6
-
7
- ## Instalação local
8
-
9
- No clone deste repositório, gere o pacote e instale o diretório produzido no projeto consumidor:
10
-
11
- ```bash
12
- cd /caminho/para/pipa/.pi
13
- bun run scripts/build-core.ts
14
-
15
- cd /caminho/do/projeto-consumidor
16
- npm install /caminho/para/pipa/.pi/dist-core
17
- ```
18
-
19
- O build gera `dist-core/`, incluindo `index.js`, declarações TypeScript, `package.json` e uma cópia deste README.
20
-
21
- ## Uso
22
-
23
- Registre no `ExtensionAPI` as features necessárias:
24
-
25
- ```ts
26
- import { applyFeatures, DocsFeature, PipaBaseFeature } from '@aelinrezende/pipa-core';
27
- import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
28
-
29
- class AuditFeature extends PipaBaseFeature {
30
- initialize(pi: ExtensionAPI): void {
31
- pi.registerTool({ name: 'audit' /* ... */ });
32
- }
33
- }
34
-
35
- await applyFeatures(pi, [DocsFeature, AuditFeature]);
36
- ```
37
-
38
- Para cada construtor informado, `applyFeatures` cria uma instância e chama `initialize(pi)`, se implementado. Em seguida, registra métodos decorados com `@PipaEvent`. A propriedade `feature.pipa` é construída e atribuída imediatamente antes da execução de cada handler decorado; use o argumento `pipa` do handler quando precisar da API no evento.
39
-
40
- ## Features incluídas
41
-
42
- | Feature | Responsabilidade |
43
- | --- | --- |
44
- | `DocsFeature` | Documentos e publicação da base de conhecimento. |
45
- | `TaskFeature` | Tarefas operacionais e dependências. |
46
- | `TeammateFeature` | Ciclo de vida e comunicação entre colegas. |
47
- | `TodoFeature` | Checklist operacional do agente. |
48
- | `BacklogFeature` | Backlog persistente do projeto. |
49
- | `PermissionFeature` | Guardas de terminal e custom tools. |
50
- | `OnboardingFeature` | Perfil e onboarding do agente principal. |
51
- | `ReminderCleanerFeature` | Remove notificações já consumidas do contexto. |
52
- | `ToolResultCompactorFeature` | Compacta resultados antigos e volumosos de tools. |
53
-
54
- As sete primeiras são exports do SDK. As duas últimas são ativadas pela extensão Pipa para higiene de contexto e não são exports do pacote.
55
-
56
- ## Eventos
57
-
58
- `@PipaEvent` aceita eventos do agente e eventos de domínio. Eventos do agente são registrados em `pi.on`; eventos de domínio são observados em `pi.events`. Handlers recebem o payload e a `PipaApi`:
59
-
60
- ```ts
61
- import { PipaBaseFeature, PipaEvent } from '@aelinrezende/pipa-core';
62
- import type { PipaApi, PipaPayload } from '@aelinrezende/pipa-core';
63
-
64
- class ListenerFeature extends PipaBaseFeature {
65
- @PipaEvent('doc_created')
66
- onDocCreated(item: PipaPayload<'doc_created'>, pipa: PipaApi): void {
67
- console.log(`${item.code}: ${item.title}`);
68
- }
69
- }
70
- ```
71
-
72
- Os handlers de domínio são reações ao fato já consumado. Para emitir um evento, use a API disponível no handler ou na feature:
73
-
74
- ```ts
75
- this.pipa.events.emit('doc_created', item);
76
- ```
77
-
78
- ### DomainEventMap (eventos nativos)
79
-
80
- | Domínio | Evento | Payload | Action de origem |
81
- | --- | --- | --- | --- |
82
- | Docs | `doc_created` | `DocItem` | `instantiate` |
83
- | Docs | `doc_updated` | `DocItem` | `update-frontmatter`, `update-body` |
84
- | Docs | `doc_removed` | `DocItem` | `remove` |
85
- | Docs | `doc_published` | `{ path, url }` | `publish` |
86
- | Backlog | `backlog_created` | `BacklogItem` | `instantiate` |
87
- | Backlog | `backlog_updated` | `BacklogItem` | `update-frontmatter`, `update-body`, `update-metadata` |
88
- | Backlog | `backlog_removed` | `BacklogItem` | `remove` |
89
- | Task | `task_created` | `Task` | `instantiate` |
90
- | Task | `task_claimed` | `Task` | `claim` |
91
- | Task | `task_updated` | `Task` | `setup`, `update` |
92
- | Task | `task_completed` | `Task` | `complete` |
93
- | Task | `task_removed` | `Task` | `remove` |
94
- | Todo | `todo_created` | `TodoItem` | `instantiate` |
95
- | Todo | `todo_updated` | `TodoItem` | `update` |
96
- | Todo | `todo_removed` | `TodoItem` | `remove` |
97
- | Todo | `todo_cleared` | `{ sessionId }` | `clear` |
98
- | Teammate | `teammate_created` | `TeammateEventPayload` | `instantiate` |
99
- | Teammate | `teammate_removed` | `{ dismissed, count, reason }` | `dismiss` |
100
-
101
- Leituras não emitem eventos. Além das actions da tabela, `task_updated` também pode ser emitido quando a alteração de uma subtarefa sincroniza o status da tarefa pai.
102
-
103
- ### Estendendo o mapa
104
-
105
- `DomainEventMap` é uma interface e aceita declaration merging:
106
-
107
- ```ts
108
- import type { PipaPayload } from '@aelinrezende/pipa-core';
109
-
110
- declare module '@aelinrezende/pipa-core' {
111
- interface DomainEventMap {
112
- audit_recorded: { id: string };
113
- }
114
- }
115
-
116
- this.pipa.events.emit('audit_recorded', { id: 'audit-1' });
117
-
118
- @PipaEvent('audit_recorded')
119
- onAuditRecorded(item: PipaPayload<'audit_recorded'>): void {
120
- console.log(item.id);
121
- }
122
- ```
123
-
124
- ## Exports principais
125
-
126
- - `applyFeatures(pi, features)` — instancia features, chama sua inicialização e registra handlers decorados.
127
- - `buildPipaApi(pi, context)` e `pipa()` — API da Pipa e acesso à instância principal.
128
- - `PipaEvent(event)` — decorator para `PiEvent` ou `DomainEventName`.
129
- - `PipaBaseFeature` — base com `pi`, `pipa` e `initialize?`.
130
- - `DomainEventMap`, `DomainEventName`, `PipaPayload<E>` e `DomainEventHandler<E>` — tipos de eventos de domínio.
131
- - Hubs e estado: `DocsHub`, `DocsState`, `TaskHub`, `TaskState`, `TeammateHub`, `TeammateState` e `PipaStore`.
1
+ # pipa-core
2
+
3
+ SDK para criar extensões do Pi com features reutilizáveis, API de execução e eventos de domínio tipados.
4
+
5
+ Inclui `applyFeatures`, `PipaBaseFeature`, `PipaEvent`, `PipaApi` e o mapa `DomainEventMap`.
6
+
7
+ ## Instalação local
8
+
9
+ No clone deste repositório, gere o pacote e instale o diretório produzido no projeto consumidor:
10
+
11
+ ```bash
12
+ cd /caminho/para/pipa/.pi
13
+ bun run scripts/build-core.ts
14
+
15
+ cd /caminho/do/projeto-consumidor
16
+ npm install /caminho/para/pipa/.pi/dist-core
17
+ ```
18
+
19
+ O build gera `dist-core/`, incluindo `index.js`, declarações TypeScript, `package.json` e uma cópia deste README.
20
+
21
+ ## Uso
22
+
23
+ Registre no `ExtensionAPI` as features necessárias:
24
+
25
+ ```ts
26
+ import { applyFeatures, DocsFeature, PipaBaseFeature } from '@aelinrezende/pipa-core';
27
+ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
28
+
29
+ class AuditFeature extends PipaBaseFeature {
30
+ initialize(pi: ExtensionAPI): void {
31
+ pi.registerTool({ name: 'audit' /* ... */ });
32
+ }
33
+ }
34
+
35
+ await applyFeatures(pi, [DocsFeature, AuditFeature]);
36
+ ```
37
+
38
+ Para cada construtor informado, `applyFeatures` cria uma instância e chama `initialize(pi)`, se implementado. Em seguida, registra métodos decorados com `@PipaEvent`. A propriedade `feature.pipa` é construída e atribuída imediatamente antes da execução de cada handler decorado; use o argumento `pipa` do handler quando precisar da API no evento.
39
+
40
+ ## Features incluídas
41
+
42
+ | Feature | Responsabilidade |
43
+ | --- | --- |
44
+ | `DocsFeature` | Documentos e publicação da base de conhecimento. |
45
+ | `TaskFeature` | Tarefas operacionais e dependências. |
46
+ | `TeammateFeature` | Ciclo de vida e comunicação entre colegas. |
47
+ | `TodoFeature` | Checklist operacional do agente. |
48
+ | `BacklogFeature` | Backlog persistente do projeto. |
49
+ | `PermissionFeature` | Guardas de terminal e custom tools. |
50
+ | `OnboardingFeature` | Perfil e onboarding do agente principal. |
51
+ | `ReminderCleanerFeature` | Remove notificações já consumidas do contexto. |
52
+ | `ToolResultCompactorFeature` | Compacta resultados antigos e volumosos de tools. |
53
+
54
+ As sete primeiras são exports do SDK. As duas últimas são ativadas pela extensão Pipa para higiene de contexto e não são exports do pacote.
55
+
56
+ ## Eventos
57
+
58
+ `@PipaEvent` aceita eventos do agente e eventos de domínio. Eventos do agente são registrados em `pi.on`; eventos de domínio são observados em `pi.events`. Handlers recebem o payload e a `PipaApi`:
59
+
60
+ ```ts
61
+ import { PipaBaseFeature, PipaEvent } from '@aelinrezende/pipa-core';
62
+ import type { PipaApi, PipaPayload } from '@aelinrezende/pipa-core';
63
+
64
+ class ListenerFeature extends PipaBaseFeature {
65
+ @PipaEvent('doc_created')
66
+ onDocCreated(item: PipaPayload<'doc_created'>, pipa: PipaApi): void {
67
+ console.log(`${item.code}: ${item.title}`);
68
+ }
69
+ }
70
+ ```
71
+
72
+ Os handlers de domínio são reações ao fato já consumado. Para emitir um evento, use a API disponível no handler ou na feature:
73
+
74
+ ```ts
75
+ this.pipa.events.emit('doc_created', item);
76
+ ```
77
+
78
+ ### DomainEventMap (eventos nativos)
79
+
80
+ | Domínio | Evento | Payload | Action de origem |
81
+ | --- | --- | --- | --- |
82
+ | Docs | `doc_created` | `DocItem` | `instantiate` |
83
+ | Docs | `doc_updated` | `DocItem` | `update-frontmatter`, `update-body` |
84
+ | Docs | `doc_removed` | `DocItem` | `remove` |
85
+ | Docs | `doc_published` | `{ path, url }` | `publish` |
86
+ | Backlog | `backlog_created` | `BacklogItem` | `instantiate` |
87
+ | Backlog | `backlog_updated` | `BacklogItem` | `update-frontmatter`, `update-body`, `update-metadata` |
88
+ | Backlog | `backlog_removed` | `BacklogItem` | `remove` |
89
+ | Task | `task_created` | `Task` | `instantiate` |
90
+ | Task | `task_claimed` | `Task` | `claim` |
91
+ | Task | `task_updated` | `Task` | `setup`, `update` |
92
+ | Task | `task_completed` | `Task` | `complete` |
93
+ | Task | `task_removed` | `Task` | `remove` |
94
+ | Todo | `todo_created` | `TodoItem` | `instantiate` |
95
+ | Todo | `todo_updated` | `TodoItem` | `update` |
96
+ | Todo | `todo_removed` | `TodoItem` | `remove` |
97
+ | Todo | `todo_cleared` | `{ sessionId }` | `clear` |
98
+ | Teammate | `teammate_created` | `TeammateEventPayload` | `instantiate` |
99
+ | Teammate | `teammate_removed` | `{ dismissed, count, reason }` | `dismiss` |
100
+
101
+ Leituras não emitem eventos. Além das actions da tabela, `task_updated` também pode ser emitido quando a alteração de uma subtarefa sincroniza o status da tarefa pai.
102
+
103
+ ### Estendendo o mapa
104
+
105
+ `DomainEventMap` é uma interface e aceita declaration merging:
106
+
107
+ ```ts
108
+ import type { PipaPayload } from '@aelinrezende/pipa-core';
109
+
110
+ declare module '@aelinrezende/pipa-core' {
111
+ interface DomainEventMap {
112
+ audit_recorded: { id: string };
113
+ }
114
+ }
115
+
116
+ this.pipa.events.emit('audit_recorded', { id: 'audit-1' });
117
+
118
+ @PipaEvent('audit_recorded')
119
+ onAuditRecorded(item: PipaPayload<'audit_recorded'>): void {
120
+ console.log(item.id);
121
+ }
122
+ ```
123
+
124
+ ## Exports principais
125
+
126
+ - `applyFeatures(pi, features)` — instancia features, chama sua inicialização e registra handlers decorados.
127
+ - `buildPipaApi(pi, context)` e `pipa()` — API da Pipa e acesso à instância principal.
128
+ - `PipaEvent(event)` — decorator para `PiEvent` ou `DomainEventName`.
129
+ - `PipaBaseFeature` — base com `pi`, `pipa` e `initialize?`.
130
+ - `DomainEventMap`, `DomainEventName`, `PipaPayload<E>` e `DomainEventHandler<E>` — tipos de eventos de domínio.
131
+ - Hubs e estado: `DocsHub`, `DocsState`, `TaskHub`, `TaskState`, `TeammateHub`, `TeammateState` e `PipaStore`.