@aisac/cli 0.4.0-beta.1 → 0.4.0-beta.10

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.
@@ -47,12 +47,12 @@ export function engineeringLicenseUrl(endpoint) {
47
47
  }
48
48
 
49
49
  /** @param {unknown} value @returns {value is Record<string, unknown>} */
50
- function isRecord(value) {
50
+ export function isRecord(value) {
51
51
  return typeof value === 'object' && value !== null && !Array.isArray(value);
52
52
  }
53
53
 
54
- /** @param {unknown} value */
55
- function isPurchaseUrl(value) {
54
+ /** @param {unknown} value @returns {value is string} */
55
+ export function isPurchaseUrl(value) {
56
56
  if (typeof value !== 'string' || value.length > MAX_URL_LENGTH) return false;
57
57
  try {
58
58
  const url = new URL(value);
@@ -97,10 +97,14 @@ export function parseLicenseBody(text) {
97
97
  };
98
98
  }
99
99
 
100
- /** @param {Response} response */
101
- async function boundedText(response) {
100
+ /**
101
+ * Read a response body as UTF-8, refusing anything above `limit` bytes.
102
+ * @param {Response} response
103
+ * @param {number} [limit]
104
+ */
105
+ export async function readBoundedText(response, limit = MAX_LICENSE_BODY_BYTES) {
102
106
  const declared = Number(response.headers.get('content-length') ?? '0');
103
- if (declared > MAX_LICENSE_BODY_BYTES) throw new Error('license_body_too_large');
107
+ if (declared > limit) throw new Error('body_too_large');
104
108
  if (response.body === null) return '';
105
109
  const reader = response.body.getReader();
106
110
  /** @type {Uint8Array[]} */
@@ -110,9 +114,9 @@ async function boundedText(response) {
110
114
  const { done, value } = await reader.read();
111
115
  if (done) break;
112
116
  size += value.byteLength;
113
- if (size > MAX_LICENSE_BODY_BYTES) {
117
+ if (size > limit) {
114
118
  await reader.cancel().catch(() => undefined);
115
- throw new Error('license_body_too_large');
119
+ throw new Error('body_too_large');
116
120
  }
117
121
  chunks.push(value);
118
122
  }
@@ -120,12 +124,12 @@ async function boundedText(response) {
120
124
  }
121
125
 
122
126
  /** @param {unknown} error */
123
- function isTimeout(error) {
127
+ export function isTimeout(error) {
124
128
  return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
125
129
  }
126
130
 
127
131
  /** @param {number} status */
128
- function unavailableReasonFor(status) {
132
+ export function unavailableReasonFor(status) {
129
133
  return (
130
134
  UNAVAILABLE_BY_STATUS.get(status) ??
131
135
  (status >= SERVER_ERROR_STATUS ? 'server_error' : 'unexpected_status')
@@ -165,7 +169,7 @@ export async function checkEngineeringLicense(endpoint, token, options = {}) {
165
169
  }
166
170
  let text;
167
171
  try {
168
- text = await boundedText(response);
172
+ text = await readBoundedText(response);
169
173
  } catch (error) {
170
174
  return unavailableLicense(isTimeout(error) ? 'timeout' : 'invalid_response');
171
175
  }
@@ -0,0 +1,310 @@
1
+ // @ts-check
2
+ /**
3
+ * The AISAC Engineering extension catalog (spec aisac-engineering-extensions,
4
+ * FR1, FR2, FR7). It ships with the client and is the only source of hooks
5
+ * and MCP servers: the server and the licensed pack can neither add nor change
6
+ * entries (ADR-0048). Every change to MCP_CATALOG repeats the FR7 review
7
+ * recorded in the spec, and CODEOWNERS covers this file.
8
+ */
9
+
10
+ /** @typedef {'pt-BR' | 'en'} CatalogLocale */
11
+ /** @typedef {'PreToolUse' | 'PostToolUse' | 'UserPromptSubmit' | 'SessionStart' | 'PreCompact' | 'Stop'} HookEvent */
12
+ /** @typedef {'block' | 'advise' | 'context'} HookMode */
13
+ /**
14
+ * @typedef {object} HookBinding
15
+ * @property {HookEvent} event
16
+ * @property {string} [matcher] Tool names (PreToolUse, PostToolUse) or SessionStart sources.
17
+ */
18
+ /**
19
+ * @typedef {object} HookEntry
20
+ * @property {string} id
21
+ * @property {HookMode} mode
22
+ * @property {boolean} defaultOn
23
+ * @property {readonly ('claude' | 'codex')[]} clients
24
+ * @property {readonly HookBinding[]} bindings
25
+ * @property {Readonly<Record<CatalogLocale, string>>} description
26
+ */
27
+
28
+ export const CATALOG_ID = /^[a-z][a-z0-9-]{0,31}$/u;
29
+
30
+ const EDIT_TOOLS = 'Edit|MultiEdit|Write';
31
+
32
+ /** @type {readonly HookEntry[]} */
33
+ export const HOOK_CATALOG = Object.freeze([
34
+ {
35
+ id: 'secrets-guard',
36
+ mode: 'block',
37
+ defaultOn: true,
38
+ clients: ['claude'],
39
+ bindings: [
40
+ { event: 'PreToolUse', matcher: 'Read|Edit|MultiEdit|Write|NotebookEdit|Grep|Bash' },
41
+ ],
42
+ description: {
43
+ en: 'Refuses reading or writing secret files (.env, keys, credentials); decides from names only.',
44
+ 'pt-BR':
45
+ 'Recusa ler ou gravar arquivos de segredo (.env, chaves, credenciais); decide só pelo nome.',
46
+ },
47
+ },
48
+ {
49
+ id: 'git-guard',
50
+ mode: 'block',
51
+ defaultOn: false,
52
+ clients: ['claude'],
53
+ bindings: [{ event: 'PreToolUse', matcher: 'Bash' }],
54
+ description: {
55
+ en: 'Refuses git push to main or master and force pushes (--force-with-lease passes).',
56
+ 'pt-BR': 'Recusa git push na main ou master e push forçado (--force-with-lease passa).',
57
+ },
58
+ },
59
+ {
60
+ id: 'destructive-guard',
61
+ mode: 'block',
62
+ defaultOn: false,
63
+ clients: ['claude'],
64
+ bindings: [{ event: 'PreToolUse', matcher: 'Bash' }],
65
+ description: {
66
+ en: 'Refuses rm -rf on /, ~, . or .. and DROP DATABASE, DROP TABLE or TRUNCATE.',
67
+ 'pt-BR': 'Recusa rm -rf em /, ~, . ou .. e DROP DATABASE, DROP TABLE ou TRUNCATE.',
68
+ },
69
+ },
70
+ {
71
+ id: 'format-on-edit',
72
+ mode: 'advise',
73
+ defaultOn: false,
74
+ clients: ['claude'],
75
+ bindings: [{ event: 'PostToolUse', matcher: EDIT_TOOLS }],
76
+ description: {
77
+ en: "Formats the edited file with the project's own formatter, when one is installed.",
78
+ 'pt-BR': 'Formata o arquivo editado com o formatador do próprio projeto, quando houver.',
79
+ },
80
+ },
81
+ {
82
+ id: 'docs-reminder',
83
+ mode: 'advise',
84
+ defaultOn: true,
85
+ clients: ['claude'],
86
+ bindings: [{ event: 'PostToolUse', matcher: EDIT_TOOLS }, { event: 'UserPromptSubmit' }],
87
+ description: {
88
+ en: 'After a source file changes in a project with docs/, reminds once per turn to update the docs.',
89
+ 'pt-BR':
90
+ 'Quando um arquivo de código muda num projeto com docs/, lembra uma vez por turno de atualizar a documentação.',
91
+ },
92
+ },
93
+ {
94
+ id: 'session-context',
95
+ mode: 'context',
96
+ defaultOn: true,
97
+ clients: ['claude'],
98
+ bindings: [{ event: 'SessionStart', matcher: 'startup|resume|clear' }],
99
+ description: {
100
+ en: 'Starts the session with a short repository snapshot (branch, status, recent commits).',
101
+ 'pt-BR': 'Abre a sessão com um resumo do repositório (branch, status, commits recentes).',
102
+ },
103
+ },
104
+ {
105
+ id: 'compact-continuity',
106
+ mode: 'context',
107
+ defaultOn: true,
108
+ clients: ['claude'],
109
+ bindings: [{ event: 'PreCompact' }, { event: 'SessionStart', matcher: 'compact' }],
110
+ description: {
111
+ en: 'Saves a repository snapshot before a compaction and restores it right after.',
112
+ 'pt-BR': 'Salva um resumo do repositório antes do compact e o devolve logo depois.',
113
+ },
114
+ },
115
+ {
116
+ id: 'continuity-reminder',
117
+ mode: 'block',
118
+ defaultOn: true,
119
+ clients: ['claude'],
120
+ bindings: [
121
+ { event: 'PostToolUse', matcher: EDIT_TOOLS },
122
+ { event: 'UserPromptSubmit' },
123
+ { event: 'Stop' },
124
+ ],
125
+ description: {
126
+ en: 'In a project with NOTES.md, asks once per turn to update NOTES.md, the spec or the CHANGELOG after code changes.',
127
+ 'pt-BR':
128
+ 'Num projeto com NOTES.md, pede uma vez por turno para atualizar NOTES.md, a spec ou o CHANGELOG depois de mudanças no código.',
129
+ },
130
+ },
131
+ ]);
132
+
133
+ /** @param {string} id @returns {HookEntry | undefined} */
134
+ export function hookById(id) {
135
+ return HOOK_CATALOG.find((entry) => entry.id === id);
136
+ }
137
+
138
+ /** @returns {string[]} */
139
+ export function hookIds() {
140
+ return HOOK_CATALOG.map((entry) => entry.id);
141
+ }
142
+
143
+ /**
144
+ * @typedef {object} McpHttpTransport
145
+ * @property {'http'} type
146
+ * @property {string} url Exact URL. Hosts key a stored login by server name and URL.
147
+ * @property {string} [bearerEnv] Environment variable that holds a bearer token. The
148
+ * catalog names it; its value is never stored or read by AISAC.
149
+ */
150
+ /**
151
+ * @typedef {object} McpStdioTransport
152
+ * @property {'stdio'} type
153
+ * @property {'npx'} command
154
+ * @property {readonly string[]} args Pinned to an exact package version (FR7).
155
+ */
156
+ /** @typedef {'host-oauth' | 'optional-oauth' | 'env-token' | 'none'} McpLogin */
157
+ /**
158
+ * @typedef {object} McpEntry
159
+ * @property {string} id
160
+ * @property {false} defaultOn Every catalog server starts off (FR7).
161
+ * @property {readonly ('claude' | 'codex')[]} clients
162
+ * @property {string} publisher
163
+ * @property {string} source The vendor's repository or documentation.
164
+ * @property {McpHttpTransport | McpStdioTransport} transport
165
+ * @property {McpLogin} login
166
+ * @property {string} [setup] A one-time command the user runs before the first use.
167
+ * @property {Readonly<Record<CatalogLocale, string>>} [loginNote] Why and how this login differs.
168
+ * @property {Readonly<Record<CatalogLocale, string>>} description
169
+ * @property {Readonly<Record<CatalogLocale, string>>} reaches What the server can reach (FR7).
170
+ * @property {readonly string[]} [blockedTools] Tools that spend money, removed in both
171
+ * clients whatever the user's permission mode is (FR7.2). Exact names.
172
+ * @property {readonly string[]} [blockedToolPrefixes] Name prefixes removed in Claude Code
173
+ * only, through a glob deny rule; Codex documents exact names only (FR7.2).
174
+ */
175
+
176
+ /** Session name of a catalog server, so it never collides with the user's own. */
177
+ export const MCP_SERVER_PREFIX = 'aisac-';
178
+ const PLAYWRIGHT_PACKAGE = '@playwright/mcp@0.0.83';
179
+
180
+ /**
181
+ * MCP catalog v1 (spec FR7; the owner chose the list on 2026-11-03). The review of
182
+ * each entry (source, transport, login, tools, reach) is recorded in the spec.
183
+ * @type {readonly McpEntry[]}
184
+ */
185
+ export const MCP_CATALOG = Object.freeze([
186
+ {
187
+ id: 'github',
188
+ defaultOn: false,
189
+ clients: ['claude', 'codex'],
190
+ publisher: 'GitHub',
191
+ source: 'https://github.com/github/github-mcp-server',
192
+ transport: {
193
+ type: 'http',
194
+ url: 'https://api.githubcopilot.com/mcp/readonly',
195
+ bearerEnv: 'GITHUB_PERSONAL_ACCESS_TOKEN',
196
+ },
197
+ login: 'env-token',
198
+ loginNote: {
199
+ en: 'GitHub offers no OAuth login for Claude Code or Codex, so this server takes a personal access token. Use a fine-grained token with read-only access to only the repositories you need, and an expiry date: in Claude Code the session’s shell commands can also read this variable.',
200
+ 'pt-BR':
201
+ 'O GitHub não oferece login OAuth para o Claude Code nem para o Codex, então este servidor usa um token de acesso pessoal. Use um token fine-grained, somente leitura, só nos repositórios de que você precisa e com data de validade: no Claude Code os comandos de shell da sessão também conseguem ler essa variável.',
202
+ },
203
+ description: {
204
+ en: "GitHub's hosted server, read-only: repositories, issues, pull requests and users.",
205
+ 'pt-BR':
206
+ 'Servidor hospedado do GitHub, somente leitura: repositórios, issues, pull requests e usuários.',
207
+ },
208
+ reaches: {
209
+ en: 'Reads what your token can see: repository files, commits, branches, releases, issues, pull requests, and user and team profiles. This read-only URL exposes no write tool.',
210
+ 'pt-BR':
211
+ 'Lê o que o seu token enxerga: arquivos, commits, branches e releases dos repositórios, issues, pull requests e perfis de usuários e times. Esta URL somente leitura não expõe ferramenta de escrita.',
212
+ },
213
+ },
214
+ {
215
+ id: 'supabase',
216
+ defaultOn: false,
217
+ clients: ['claude', 'codex'],
218
+ publisher: 'Supabase',
219
+ source: 'https://github.com/supabase-community/supabase-mcp',
220
+ transport: { type: 'http', url: 'https://mcp.supabase.com/mcp?read_only=true' },
221
+ login: 'host-oauth',
222
+ // read_only=true should already leave these out; the vendor does not publish
223
+ // what it removes, so they are blocked as a second layer (FR7.2).
224
+ blockedTools: ['create_project', 'confirm_cost', 'create_branch'],
225
+ description: {
226
+ en: "Supabase's hosted server, read-only: tables, SQL, logs, advisors and docs.",
227
+ 'pt-BR':
228
+ 'Servidor hospedado da Supabase, somente leitura: tabelas, SQL, logs, advisors e documentação.',
229
+ },
230
+ reaches: {
231
+ en: 'Every organization and project of the Supabase account you log in with: database contents through read-only SQL, migrations, logs, advisors, Edge Functions, project URLs and publishable keys. read_only=true runs SQL as a read-only Postgres role and leaves out the write tools; the login grants the scopes you approve on Supabase.',
232
+ 'pt-BR':
233
+ 'Todas as organizações e projetos da conta Supabase em que você entrar: dados do banco por SQL somente leitura, migrations, logs, advisors, Edge Functions, URLs dos projetos e chaves publicáveis. read_only=true executa o SQL com um papel Postgres somente leitura e deixa de fora as ferramentas de escrita; o login concede os escopos que você aprovar na Supabase.',
234
+ },
235
+ },
236
+ {
237
+ id: 'vercel',
238
+ defaultOn: false,
239
+ clients: ['claude', 'codex'],
240
+ publisher: 'Vercel',
241
+ source: 'https://vercel.com/docs/agent-resources/vercel-mcp',
242
+ transport: { type: 'http', url: 'https://mcp.vercel.com' },
243
+ login: 'host-oauth',
244
+ // buy_domain charges the team after a quote, and its confirm flag is a model
245
+ // argument; a domain transfer may be charged (FR7.1, FR7.2).
246
+ blockedTools: ['buy_domain', 'create_or_transfer_domain'],
247
+ blockedToolPrefixes: ['buy_'],
248
+ description: {
249
+ en: "Vercel's hosted server: projects, deployments, logs, domains and environment variables.",
250
+ 'pt-BR':
251
+ 'Servidor hospedado da Vercel: projetos, deploys, logs, domínios e variáveis de ambiente.',
252
+ },
253
+ reaches: {
254
+ en: 'The teams you grant at login, with the access of your Vercel user: projects, deployments, build and runtime logs, domains and DNS, and environment variables, including decrypted values. It also has write tools (deployments, environment variables, DNS records, firewall rules, project settings) and no read-only mode, so keep the confirmation of each call on. Buying domains is blocked by AISAC.',
255
+ 'pt-BR':
256
+ 'Os times que você liberar no login, com o acesso do seu usuário Vercel: projetos, deploys, logs de build e de execução, domínios e DNS, e variáveis de ambiente, inclusive valores decifrados. Também tem ferramentas de escrita (deploys, variáveis de ambiente, registros DNS, regras de firewall, configurações de projeto) e não tem modo somente leitura, então mantenha a confirmação de cada chamada ligada. A compra de domínios é bloqueada pela AISAC.',
257
+ },
258
+ },
259
+ {
260
+ id: 'playwright',
261
+ defaultOn: false,
262
+ clients: ['claude', 'codex'],
263
+ publisher: 'Microsoft',
264
+ source: 'https://github.com/microsoft/playwright-mcp',
265
+ transport: {
266
+ type: 'stdio',
267
+ command: 'npx',
268
+ args: ['-y', PLAYWRIGHT_PACKAGE, '--browser', 'chromium', '--headless', '--isolated'],
269
+ },
270
+ login: 'none',
271
+ setup: `npx -y ${PLAYWRIGHT_PACKAGE} install-browser chrome-for-testing`,
272
+ description: {
273
+ en: 'A local headless browser driven by Playwright, for testing web pages.',
274
+ 'pt-BR': 'Um navegador local sem janela, controlado pelo Playwright, para testar páginas.',
275
+ },
276
+ reaches: {
277
+ en: 'Runs on your machine with a fresh in-memory profile each session, so no saved logins. It opens any URL the agent asks for, including localhost and your local network, can run JavaScript in the page and upload files from the project. Page content is untrusted input.',
278
+ 'pt-BR':
279
+ 'Roda na sua máquina com um perfil novo em memória a cada sessão, sem logins salvos. Abre qualquer URL que o agente pedir, inclusive localhost e a sua rede local, pode executar JavaScript na página e enviar arquivos do projeto. O conteúdo das páginas é entrada não confiável.',
280
+ },
281
+ },
282
+ {
283
+ id: 'context7',
284
+ defaultOn: false,
285
+ clients: ['claude', 'codex'],
286
+ publisher: 'Upstash',
287
+ source: 'https://github.com/upstash/context7',
288
+ transport: { type: 'http', url: 'https://mcp.context7.com/mcp' },
289
+ login: 'optional-oauth',
290
+ description: {
291
+ en: 'Up-to-date documentation and code examples for libraries, from Context7.',
292
+ 'pt-BR': 'Documentação e exemplos de código atualizados de bibliotecas, do Context7.',
293
+ },
294
+ reaches: {
295
+ en: 'Public library documentation only. What the agent asks (library names and questions) goes to Upstash, so keep secrets and private code out of those questions. It works without login, with lower rate limits.',
296
+ 'pt-BR':
297
+ 'Só documentação pública de bibliotecas. O que o agente pergunta (nomes de bibliotecas e dúvidas) vai para a Upstash, então não coloque segredos nem código privado nessas perguntas. Funciona sem login, com limites de uso menores.',
298
+ },
299
+ },
300
+ ]);
301
+
302
+ /** @param {string} id @returns {McpEntry | undefined} */
303
+ export function mcpById(id) {
304
+ return MCP_CATALOG.find((entry) => entry.id === id);
305
+ }
306
+
307
+ /** @returns {string[]} */
308
+ export function mcpIds() {
309
+ return MCP_CATALOG.map((entry) => entry.id);
310
+ }