fg-tracker-mcp 0.9.1 → 0.11.0

package/dist/docs.js

@@ -6,13 +6,13 @@ export const QUICKSTART_URI = 'fg-tracker://docs/quickstart';
 /** @deprecated URI do `stread-track-mcp` ≤ 0.3; ainda registrada como alias, removida na 1.0. */
 export const LEGACY_QUICKSTART_URI = 'stread-track://docs/quickstart';
 export function quickstartMarkdown(endpoint) {
-    return `# FG Track — quickstart
+    return `# FG Tracker — quickstart
 
 APM leve para Node: traces (Express/NestJS/Next.js/Fastify), queries pg, chamadas HTTP de saída, logs e detecção automática de **N+1**, **loops**, **endpoints lentos** e **erros**. API em \`${endpoint}\` (Swagger em \`${endpoint}/docs\`).
 
 ## 1. Projeto e chave
-- \`track_list_projects\` lista os projetos do usuário do token; \`track_create_project { name }\` cria um e devolve \`apiKey\` (\`stk_...\`).
-- \`track_update_allowed_origins { projectId, origins }\` substitui os domínios permitidos (CORS do SDK de navegador); leia a lista atual em \`track_list_projects\` e confirme com o usuário antes.
+- \`tracker_list_projects\` lista os projetos do usuário do token; \`tracker_create_project { name }\` cria um e devolve \`apiKey\` (\`stk_...\`).
+- \`tracker_update_allowed_origins { projectId, origins }\` substitui os domínios permitidos (CORS do SDK de navegador); leia a lista atual em \`tracker_list_projects\` e confirme com o usuário antes.
 - A chave vai no header \`x-fg-tracker-key\` da ingestão e em \`FG_TRACKER_KEY\` no app instrumentado.
 
 ## 2. SDK (\`fg-tracker-sdk\`)
@@ -26,7 +26,7 @@ const tracker = createTracker({
 });
 app.use(tracker.express());                 // Express / NestJS — PRIMEIRO middleware (continua traceparent, lê req.user.id)
 app.use(routes); app.use(tracker.expressErrorHandler()); // exceção real no span → issues por causa, não por status
-tracker.instrumentPg(pool); // pg only; use track_detect_databases for other drivers                 // pg.Pool → spans db.query
+tracker.instrumentPg(pool); // pg only; use tracker_detect_databases for other drivers                 // pg.Pool → spans db.query
 const fetchTracked = tracker.wrapFetch();   // fetch → spans http.client
 export const GET = tracker.wrapNextRoute(async (req) => Response.json({ ok: true }));   // Next.js
 await tracker.span('custom', 'send-email', async (span) => { /* ... */ });
@@ -35,7 +35,7 @@ await tracker.checkIn('backup-diario', () => runBackup(), { intervalSeconds: 864
 await tracker.shutdown();                   // no SIGTERM
 \`\`\`
 No deploy: \`npx fg-tracker-release --service minha-app --previous-sha $PREV\` registra a release com commits/arquivos (commits suspeitos nas issues, comparação de latência entre versões).
-Use \`track_instrumentation_guide { framework, projectId }\` para o passo a passo completo por framework com a chave real.
+Use \`tracker_instrumentation_guide { framework, projectId }\` para o passo a passo completo por framework com a chave real.
 
 ## 3. Logs
 \`\`\`ts
@@ -64,13 +64,13 @@ curl -X POST ${endpoint}/v1/logs -H 'content-type: application/json' -H 'x-fg-tr
 Kinds de span: \`http.server\` (raiz por request), \`db.query\` (nome = SQL normalizado), \`http.client\`, \`custom\`.
 
 ## 5. Verificar e explorar
-- \`track_verify_ingest { projectId }\` — confirma spans/logs recentes.
-- \`track_get_overview { projectId, range }\` — requests, erro, p50/p95/p99, apdex, top lentos.
-- \`track_list_endpoints\`, \`track_list_issues\`, \`track_list_traces\` → \`track_get_trace { traceId }\` (waterfall).
-- \`track_search_logs { projectId, q, service, level, range }\` — sintaxe: texto livre, \`"frase"\`, \`key=value\`, \`~substring\`.
-- \`track_get_issue { projectId, issueId }\` — ocorrências, usuários afetados, releases, regressões e commits/PRs suspeitos.
-- \`track_list_releases { projectId, version? }\`, \`track_register_release\`, \`track_endpoint_history { projectId, name, days }\` — saúde por deploy e latência por rota ao longo do tempo.
-- \`track_list_providers { projectId, range }\` (chamadas de saída por host) e \`track_list_monitors { projectId }\` (uptime e jobs).
+- \`tracker_verify_ingest { projectId }\` — confirma spans/logs recentes.
+- \`tracker_get_overview { projectId, range }\` — requests, erro, p50/p95/p99, apdex, top lentos.
+- \`tracker_list_endpoints\`, \`tracker_list_issues\`, \`tracker_list_traces\` → \`tracker_get_trace { traceId }\` (waterfall, 80 spans por página: \`spanOffset\`, filtros \`kind\`/\`service\`/\`name\`).
+- \`tracker_search_logs { projectId, q, service, level, env, requestId, range }\` — sintaxe: texto livre, \`"frase"\`, \`key=value\`, \`~substring\`.
+- \`tracker_get_issue { projectId, issueId }\` — ocorrências, usuários afetados, releases, regressões e commits/PRs suspeitos.
+- \`tracker_list_releases { projectId, version? }\`, \`tracker_register_release\`, \`tracker_endpoint_history { projectId, name, days }\` — saúde por deploy e latência por rota ao longo do tempo.
+- \`tracker_list_providers { projectId, range }\` (chamadas de saída por host) e \`tracker_list_monitors { projectId }\` (uptime e jobs) → \`tracker_get_monitor { projectId, monitorId }\` (histórico de checks com o trace de cada execução).
 
 ## 6. Detectores (rodam na ingestão)
 | tipo | regra |
@@ -82,7 +82,7 @@ Kinds de span: \`http.server\` (raiz por request), \`db.query\` (nome = SQL norm
 | ERROR | raiz com status ≥ 500 ou \`error != null\` |
 
 ## 7. Infraestrutura (AWS)
-Prompt \`connect-infrastructure\` guia o fluxo completo: o agente detecta sozinho contas, ambientes e regiões. Nenhuma tool altera recursos na AWS; a única mudança é o stack de conexão, criado com o comando devolvido e só com confirmação do usuário. Mudanças de infra só pelo FG Track, com aprovação humana.
+Prompt \`connect-infrastructure\` guia o fluxo completo: o agente detecta sozinho contas, ambientes e regiões. Nenhuma tool altera recursos na AWS; a única mudança é o stack de conexão, criado com o comando devolvido e só com confirmação do usuário. Mudanças de infra só pelo FG Tracker, com aprovação humana.
 0. \`infra_detect_environments { profiles?, includeRegions? }\` — perfis do \`~/.aws\` → conta (STS), ambiente sugerido e regiões em uso (local, somente leitura).
 1. Por ambiente: \`infra_connect_account { projectId, level: 'read'|'operate', environment?, regions?, name?, profile? }\` → template \`./fg-tracker-connection-<ambiente>.json\` + \`aws cloudformation deploy ... --profile --region\` (confirmar com o usuário antes) → \`infra_verify_connection { projectId, connectionId, profile }\`.
 2. \`infra_discover { projectId, regions?, profile? }\` — inventário com credenciais locais (Resource Explorer/Tagging API + CloudFormation) enviado como snapshot.
@@ -98,9 +98,9 @@ Ranges aceitos: \`15m|1h|6h|24h|7d|30d\`.
 export function instrumentProjectPrompt(args, endpoint) {
     const fw = args.framework ? `O usuário indicou o framework **${args.framework}**; confirme lendo o código antes de seguir.` : 'O framework NÃO foi informado: detecte-o.';
     const proj = args.projectName
-        ? `Use (ou crie) o projeto chamado **${args.projectName}** no FG Track.`
+        ? `Use (ou crie) o projeto chamado **${args.projectName}** no FG Tracker.`
         : 'Nenhum nome de projeto foi informado: use o nome do pacote (`package.json#name`) ou o nome do diretório.';
-    return `Você vai conectar o projeto de código atual ao FG Track (APM em ${endpoint}) usando as tools deste servidor MCP. Trabalhe passo a passo, mostre o que fez em cada etapa e só avance quando a anterior estiver ok.
+    return `Você vai conectar o projeto de código atual ao FG Tracker (APM em ${endpoint}) usando as tools deste servidor MCP. Trabalhe passo a passo, mostre o que fez em cada etapa e só avance quando a anterior estiver ok.
 
 ${fw} ${proj}
 
@@ -108,20 +108,20 @@ ${fw} ${proj}
 
 1. **Detectar framework e logger.** Leia \`package.json\` (dependências: express, @nestjs/core, next, fastify; pino, winston; pg, drizzle-orm, kysely, knex) e o ponto de entrada (\`src/main.ts\`, \`src/index.ts\`, \`app/\`). Anote: framework HTTP, logger, os drivers e os pontos de criação dos clientes, gerenciador de pacotes (lockfile) e como o app é iniciado.
 
-2. **Detectar bancos.** Chame \`track_detect_databases { projectPath, serviceName }\`. Confirme os imports e pontos de criação retornados; siga o adapter de cada driver ativo. Não suponha pg.Pool para Postgres.js, Prisma ou outro driver.
+2. **Detectar bancos.** Chame \`tracker_detect_databases { projectPath, serviceName }\`. Confirme os imports e pontos de criação retornados; siga o adapter de cada driver ativo. Não suponha pg.Pool para Postgres.js, Prisma ou outro driver.
 
-2b. **Checar o FG Track.** Chame \`track_status\`. Se a API estiver fora do ar ou faltar \`FG_TRACKER_TOKEN\`, pare e explique ao usuário o que configurar.
+2b. **Checar o FG Tracker.** Chame \`tracker_status\`. Se a API estiver fora do ar ou faltar \`FG_TRACKER_TOKEN\`, pare e explique ao usuário o que configurar.
 
-3. **Escolher ou criar o projeto.** Chame \`track_list_projects\`. Se já existe um projeto com o nome esperado, use-o; senão \`track_create_project { name }\`. Guarde \`projectId\` e \`apiKey\`. Nunca imprima a chave em commits/logs — só em \`.env\` (confira que \`.env\` está no \`.gitignore\`; adicione a variável em \`.env.example\` sem o valor).
+3. **Escolher ou criar o projeto.** Chame \`tracker_list_projects\`. Se já existe um projeto com o nome esperado, use-o; senão \`tracker_create_project { name }\`. Guarde \`projectId\` e \`apiKey\`. Nunca imprima a chave em commits/logs — só em \`.env\` (confira que \`.env\` está no \`.gitignore\`; adicione a variável em \`.env.example\` sem o valor).
 
-4. **Obter o guia.** Chame \`track_instrumentation_guide { framework, projectId }\` para o framework detectado. Se o app tem pino ou winston, chame também com \`framework: "pino"\` ou \`"winston"\`.
+4. **Obter o guia.** Chame \`tracker_instrumentation_guide { framework, projectId }\` para o framework detectado. Se o app tem pino ou winston, chame também com \`framework: "pino"\` ou \`"winston"\`.
 
 5. **Instalar o SDK.** \`pnpm add fg-tracker-sdk\` (ou npm/yarn conforme o lockfile). Se o projeto já usa \`stread-track-sdk\`, troque pelo \`fg-tracker-sdk\` (mesma API).
 
 6. **Aplicar a instrumentação** seguindo o guia, com edits mínimos e idiomáticos ao projeto:
    - criar o tracker (um por processo) com \`apiKey\` de \`process.env.FG_TRACKER_KEY\` e \`endpoint\` de \`FG_TRACKER_URL\`;
    - registrar \`tracker.express()\` como PRIMEIRO middleware (Express/Nest), \`wrapNextRoute\` nos route handlers (Next) ou o hook \`onRequest\` (Fastify);
-   - aplicar o adapter retornado por \`track_detect_databases\` ao cliente real antes de passá-lo ao ORM; para drivers desconhecidos envolver a conclusão da operação com \`traceDatabase\` ou \`traceDatabaseSync\`;
+   - aplicar o adapter retornado por \`tracker_detect_databases\` ao cliente real antes de passá-lo ao ORM; para drivers desconhecidos envolver a conclusão da operação com \`traceDatabase\` ou \`traceDatabaseSync\`;
    - \`tracker.wrapFetch()\` para chamadas HTTP de saída relevantes;
    - transport de logs (pino/winston/nest) com \`createLogShipper\`;
    - \`tracker.shutdown()\` no encerramento (SIGTERM / \`onApplicationShutdown\` / \`onClose\`).
@@ -130,11 +130,11 @@ ${fw} ${proj}
 
 8. **Rodar e gerar tráfego.** Inicie o app, faça algumas requisições reais (curl nas rotas principais, inclusive uma que consulte o banco) e aguarde ~3 s.
 
-9. **Verificar.** Chame \`track_verify_ingest { projectId }\`. Se chegaram spans (e logs, quando configurados), mostre um resumo com \`track_get_overview { projectId, range: "15m" }\` e \`track_list_issues\`.
+9. **Verificar.** Chame \`tracker_verify_ingest { projectId }\`. Se chegaram spans (e logs, quando configurados), mostre um resumo com \`tracker_get_overview { projectId, range: "15m" }\` e \`tracker_list_issues\`.
 
 10. **Corrigir.** Se nada chegou: confira a chave (o SDK loga "4xx" uma vez quando ela é inválida), a ordem do middleware, se o tracker foi criado antes do app subir, se o processo consegue alcançar ${endpoint} (\`curl ${endpoint}/v1/health\`) e se há \`enabled: false\`. Ajuste e repita o passo 8.
 
-Ao final, liste os arquivos alterados, as variáveis adicionadas e o resultado de \`track_verify_ingest\`.`;
+Ao final, liste os arquivos alterados, as variáveis adicionadas e o resultado de \`tracker_verify_ingest\`.`;
 }
 // Database driver detection must precede selection of an integration adapter.
 //# sourceMappingURL=docs.js.map

package/dist/docs.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,8BAA8B,CAAC;AAC7D,iGAAiG;AACjG,MAAM,CAAC,MAAM,qBAAqB,GAAG,gCAAgC,CAAC;AAEtE,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO;;gMAEuL,QAAQ,oBAAoB,QAAQ;;;;;;;;;;;oDAWhL,QAAQ;;;;;;;;;;;;;;;;;;;;;wDAqBJ,QAAQ;;;;;;;;;eASjD,QAAQ;;;;;;;;eAQR,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCtB,CAAC;AACF,CAAC;AAOD,MAAM,UAAU,uBAAuB,CAAC,IAA0B,EAAE,QAAgB;IAClF,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,mCAAmC,IAAI,CAAC,SAAS,8CAA8C,CAAC,CAAC,CAAC,2CAA2C,CAAC;IAC1K,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW;QAC3B,CAAC,CAAC,qCAAqC,IAAI,CAAC,WAAW,iBAAiB;QACxE,CAAC,CAAC,0GAA0G,CAAC;IAE/G,OAAO,mEAAmE,QAAQ;;EAElF,EAAE,IAAI,IAAI;;;;;;;;;;;;;;;;;;;;;;;;wFAwB4E,QAAQ;;;;;;yMAMyG,QAAQ,YAAY,QAAQ;;0GAE3H,CAAC;AAC3G,CAAC;AAED,8EAA8E"}
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,8BAA8B,CAAC;AAC7D,iGAAiG;AACjG,MAAM,CAAC,MAAM,qBAAqB,GAAG,gCAAgC,CAAC;AAEtE,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO;;gMAEuL,QAAQ,oBAAoB,QAAQ;;;;;;;;;;;oDAWhL,QAAQ;;;;;;;;;;;;;;;;;;;;;wDAqBJ,QAAQ;;;;;;;;;eASjD,QAAQ;;;;;;;;eAQR,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCtB,CAAC;AACF,CAAC;AAOD,MAAM,UAAU,uBAAuB,CAAC,IAA0B,EAAE,QAAgB;IAClF,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,mCAAmC,IAAI,CAAC,SAAS,8CAA8C,CAAC,CAAC,CAAC,2CAA2C,CAAC;IAC1K,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW;QAC3B,CAAC,CAAC,qCAAqC,IAAI,CAAC,WAAW,mBAAmB;QAC1E,CAAC,CAAC,0GAA0G,CAAC;IAE/G,OAAO,qEAAqE,QAAQ;;EAEpF,EAAE,IAAI,IAAI;;;;;;;;;;;;;;;;;;;;;;;;wFAwB4E,QAAQ;;;;;;yMAMyG,QAAQ,YAAY,QAAQ;;4GAEzH,CAAC;AAC7G,CAAC;AAED,8EAA8E"}

package/dist/format.d.ts

@@ -1,27 +1,92 @@
+/** Link para um recurso (MCP `resource_link`): o painel ou um `fg-tracker://…` legível pelo servidor. */
+export interface ResourceLink {
+    type: 'resource_link';
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+}
 export interface ToolText {
     [x: string]: unknown;
     content: Array<{
         type: 'text';
         text: string;
-    }>;
+    } | ResourceLink>;
+    structuredContent?: Record<string, unknown>;
     isError?: boolean;
 }
 export declare const MAX_SERIES_POINTS = 48;
+/** Arrays internos (amostras, ocorrências, checks dentro de um objeto). */
 export declare const MAX_LIST_ITEMS = 25;
 export declare const MAX_TRACE_SPANS = 80;
+/** Default de FG_TRACKER_MAX_ITEMS: teto da lista principal de uma ferramenta. */
+export declare const DEFAULT_MAX_ITEMS = 200;
+/** Maior valor aceito em FG_TRACKER_MAX_ITEMS e nos `limit` sem teto próprio da API. */
+export declare const MAX_ITEMS_CEILING = 1000;
+/** Linhas de prévia no texto de uma lista longa; o JSON que segue traz todos os itens. */
+export declare const PREVIEW_LINES = 25;
 export declare function text(value: string): ToolText;
 export declare function json(value: unknown, preface?: string): ToolText;
+/**
+ * Resultado com `structuredContent` (o que o `outputSchema` descreve) e o texto de sempre:
+ * o resumo e, depois de uma linha em branco, o JSON de `body` (default: o próprio `data`).
+ * `body` existe para manter o JSON antigo do texto quando o estruturado mudou de forma
+ * (ex.: lista que virou `{ items }`). `body: null` deixa só o resumo.
+ */
+export declare function structured(data: Record<string, unknown>, summary: string, options?: {
+    body?: unknown;
+    links?: ResourceLink[];
+}): ToolText;
 export declare function errorResult(err: unknown): ToolText;
 /** Executa `fn` e converte qualquer exceção em resultado `isError`. */
 export declare function guard(fn: () => Promise<ToolText>): Promise<ToolText>;
-/** Reduz uma série mantendo a distribuição (amostragem uniforme). */
+/**
+ * Reduz uma série a `max` pontos por amostragem uniforme, sempre com o primeiro e o
+ * último: numa série em ordem de tempo, o ponto mais recente nunca fica de fora.
+ */
 export declare function sampleSeries<T>(series: T[], max?: number): T[];
 export declare function truncateList<T>(list: T[], max?: number): {
     items: T[];
     truncated: number;
 };
-/** Compacta recursivamente: `series` viram amostras, arrays longos são cortados. */
+export interface MaxItemsSetting {
+    value: number;
+    /** Presente quando FG_TRACKER_MAX_ITEMS foi ignorado ou reduzido. */
+    warning?: string;
+}
+/** Teto da lista principal: FG_TRACKER_MAX_ITEMS (inteiro de 1 a 1000, default 200). */
+export declare function maxItemsFromEnv(env?: NodeJS.ProcessEnv): MaxItemsSetting;
+/** Limite efetivo da lista principal: o `limit` pedido, até `maxItems`. */
+export declare function clampLimit(requested: number, maxItems: number): {
+    limit: number;
+    capped: boolean;
+};
+/** Aviso para quando `clampLimit` reduziu o pedido. */
+export declare function cappedNote(requested: number, limit: number): string;
+export interface ListPage {
+    total: number;
+    returned: number;
+    truncated: boolean;
+    items: unknown[];
+}
+/** Prévia em texto de uma lista: até PREVIEW_LINES linhas e, se cortou, onde está o resto. */
+export declare function preview(lines: string[]): string;
+/**
+ * Lista principal de uma API sem paginação: os primeiros `limit` itens (cada um
+ * compactado) e quanto ficou de fora. Não há cursor: para ver o resto, aumente
+ * `limit` ou filtre.
+ */
+export declare function listPage(list: unknown[], limit: number): ListPage;
+/**
+ * Compacta recursivamente: `series` viram amostras e arrays internos de um objeto
+ * ficam com até 25 itens (`<campo>Omitted` diz quantos saíram). Um array passado
+ * direto também é cortado em 25; a lista principal de uma ferramenta deve ser
+ * limitada antes (API ou `listPage`) e compactada item a item.
+ */
 export declare function compact(value: unknown, depth?: number): unknown;
 export declare function ms(value: number | null | undefined): string;
 export declare function pct(value: number | null | undefined): string;
+/** Tempo até `iso` ("em 3.5 d"); no passado vira `ago`. */
+export declare function until(iso: string, now?: number): string;
 export declare function ago(iso: string, now?: number): string;

package/dist/format.js

@@ -1,19 +1,48 @@
 /**
- * Helpers de saída: compactação de payloads grandes (mesma regra do §7 do
- * contrato — séries ≤ 48 pontos, listas ≤ 25 itens, traces ≤ 80 spans) e
- * conversão para o formato de resultado do MCP.
+ * Helpers de saída: compactação de payloads grandes e conversão para o formato
+ * de resultado do MCP. Regras (docs/mcp.md, "Limites de saída"):
+ * - lista principal de uma ferramenta: respeita `limit` até FG_TRACKER_MAX_ITEMS
+ *   (default 200, teto 1000), cortada na API (cursor) ou por `listPage`, sempre
+ *   com metadados de truncamento;
+ * - arrays internos de um objeto: ≤ 25 itens, com `<campo>Omitted`;
+ * - séries ≤ 48 pontos, amostradas por igual e sempre com o primeiro e o último
+ *   (o período recente nunca some); `markers` ficam com os 25 mais recentes;
+ * - traces ≤ 80 spans por página (tracker_get_trace pagina).
+ *
+ * Toda ferramenta de leitura devolve também `structuredContent` (validado contra o
+ * `outputSchema` da ferramenta), com o texto de antes mantido para compatibilidade.
  */
-import { TrackApiError } from './client.js';
+import { TrackApiError, readEnv } from './client.js';
 export const MAX_SERIES_POINTS = 48;
+/** Arrays internos (amostras, ocorrências, checks dentro de um objeto). */
 export const MAX_LIST_ITEMS = 25;
 export const MAX_TRACE_SPANS = 80;
+/** Default de FG_TRACKER_MAX_ITEMS: teto da lista principal de uma ferramenta. */
+export const DEFAULT_MAX_ITEMS = 200;
+/** Maior valor aceito em FG_TRACKER_MAX_ITEMS e nos `limit` sem teto próprio da API. */
+export const MAX_ITEMS_CEILING = 1000;
+/** Linhas de prévia no texto de uma lista longa; o JSON que segue traz todos os itens. */
+export const PREVIEW_LINES = 25;
+/** Acima disso o JSON sai sem indentação: a mesma lista ocupa bem menos da saída do cliente MCP. */
+const PRETTY_JSON_MAX_CHARS = 20_000;
 export function text(value) {
     return { content: [{ type: 'text', text: value }] };
 }
 export function json(value, preface) {
-    const body = JSON.stringify(value, null, 2);
+    const pretty = JSON.stringify(value, null, 2);
+    const body = pretty !== undefined && pretty.length > PRETTY_JSON_MAX_CHARS ? JSON.stringify(value) : pretty;
     return text(preface ? `${preface}\n\n${body}` : body);
 }
+/**
+ * Resultado com `structuredContent` (o que o `outputSchema` descreve) e o texto de sempre:
+ * o resumo e, depois de uma linha em branco, o JSON de `body` (default: o próprio `data`).
+ * `body` existe para manter o JSON antigo do texto quando o estruturado mudou de forma
+ * (ex.: lista que virou `{ items }`). `body: null` deixa só o resumo.
+ */
+export function structured(data, summary, options = {}) {
+    const base = options.body === null ? text(summary) : json(options.body === undefined ? data : options.body, summary);
+    return { ...base, content: [...base.content, ...(options.links ?? [])], structuredContent: data };
+}
 export function errorResult(err) {
     const message = err instanceof TrackApiError ? err.describe() : err instanceof Error ? err.message : String(err);
     return { content: [{ type: 'text', text: message }], isError: true };
@@ -27,14 +56,18 @@ export async function guard(fn) {
         return errorResult(err);
     }
 }
-/** Reduz uma série mantendo a distribuição (amostragem uniforme). */
+/**
+ * Reduz uma série a `max` pontos por amostragem uniforme, sempre com o primeiro e o
+ * último: numa série em ordem de tempo, o ponto mais recente nunca fica de fora.
+ */
 export function sampleSeries(series, max = MAX_SERIES_POINTS) {
     if (series.length <= max)
         return series;
-    const step = series.length / max;
+    if (max <= 1)
+        return series.slice(-1);
     const out = [];
     for (let i = 0; i < max; i++) {
-        const item = series[Math.floor(i * step)];
+        const item = series[Math.round((i * (series.length - 1)) / (max - 1))];
         if (item !== undefined)
             out.push(item);
     }
@@ -45,7 +78,50 @@ export function truncateList(list, max = MAX_LIST_ITEMS) {
         return { items: list, truncated: 0 };
     return { items: list.slice(0, max), truncated: list.length - max };
 }
-/** Compacta recursivamente: `series` viram amostras, arrays longos são cortados. */
+/** Teto da lista principal: FG_TRACKER_MAX_ITEMS (inteiro de 1 a 1000, default 200). */
+export function maxItemsFromEnv(env = process.env) {
+    const raw = readEnv('MAX_ITEMS', env);
+    if (raw === undefined)
+        return { value: DEFAULT_MAX_ITEMS };
+    const parsed = Number(raw);
+    if (!/^\d+$/.test(raw) || !Number.isSafeInteger(parsed) || parsed < 1) {
+        return { value: DEFAULT_MAX_ITEMS, warning: `FG_TRACKER_MAX_ITEMS="${raw.slice(0, 20)}" é inválido (use um inteiro de 1 a ${MAX_ITEMS_CEILING}); usando ${DEFAULT_MAX_ITEMS}.` };
+    }
+    if (parsed > MAX_ITEMS_CEILING)
+        return { value: MAX_ITEMS_CEILING, warning: `FG_TRACKER_MAX_ITEMS=${parsed} passa do teto; usando ${MAX_ITEMS_CEILING}.` };
+    return { value: parsed };
+}
+/** Limite efetivo da lista principal: o `limit` pedido, até `maxItems`. */
+export function clampLimit(requested, maxItems) {
+    return requested > maxItems ? { limit: maxItems, capped: true } : { limit: requested, capped: false };
+}
+/** Aviso para quando `clampLimit` reduziu o pedido. */
+export function cappedNote(requested, limit) {
+    return requested > limit ? ` limit ${requested} reduzido para ${limit} por FG_TRACKER_MAX_ITEMS.` : '';
+}
+/** Prévia em texto de uma lista: até PREVIEW_LINES linhas e, se cortou, onde está o resto. */
+export function preview(lines) {
+    if (lines.length <= PREVIEW_LINES)
+        return lines.join('\n');
+    return [...lines.slice(0, PREVIEW_LINES), `… prévia de ${PREVIEW_LINES} de ${lines.length}; todos os ${lines.length} estão no JSON abaixo.`].join('\n');
+}
+/**
+ * Lista principal de uma API sem paginação: os primeiros `limit` itens (cada um
+ * compactado) e quanto ficou de fora. Não há cursor: para ver o resto, aumente
+ * `limit` ou filtre.
+ */
+export function listPage(list, limit) {
+    const items = list.slice(0, limit).map((item) => compact(item));
+    return { total: list.length, returned: items.length, truncated: items.length < list.length, items };
+}
+/** Campos que são séries temporais em ordem crescente (`points` = histórico de uma rota). */
+const SERIES_KEYS = new Set(['series', 'seriesQueriesPerMin', 'histogram', 'points']);
+/**
+ * Compacta recursivamente: `series` viram amostras e arrays internos de um objeto
+ * ficam com até 25 itens (`<campo>Omitted` diz quantos saíram). Um array passado
+ * direto também é cortado em 25; a lista principal de uma ferramenta deve ser
+ * limitada antes (API ou `listPage`) e compactada item a item.
+ */
 export function compact(value, depth = 0) {
     if (Array.isArray(value)) {
         const { items, truncated } = truncateList(value);
@@ -55,10 +131,16 @@ export function compact(value, depth = 0) {
     if (value && typeof value === 'object') {
         const out = {};
         for (const [k, v] of Object.entries(value)) {
-            if ((k === 'series' || k === 'seriesQueriesPerMin' || k === 'histogram') && Array.isArray(v)) {
+            if (SERIES_KEYS.has(k) && Array.isArray(v)) {
                 out[k] = sampleSeries(v);
                 if (v.length > MAX_SERIES_POINTS)
-                    out[`${k}Points`] = `${v.length} pontos, amostrados para ${MAX_SERIES_POINTS}`;
+                    out[`${k}Points`] = `${v.length} pontos, amostrados para ${MAX_SERIES_POINTS} (inclui o primeiro e o último)`;
+            }
+            else if (k === 'markers' && Array.isArray(v)) {
+                // Marcadores de deploy em ordem de tempo: os mais recentes são os que importam.
+                out[k] = v.slice(-MAX_LIST_ITEMS).map((item) => compact(item, depth + 1));
+                if (v.length > MAX_LIST_ITEMS)
+                    out.markersOmitted = v.length - MAX_LIST_ITEMS;
             }
             else if (k === 'spans' && Array.isArray(v)) {
                 const { items, truncated } = truncateList(v, MAX_TRACE_SPANS);
@@ -69,6 +151,12 @@ export function compact(value, depth = 0) {
             else if (k === 'sparkline' && Array.isArray(v)) {
                 out[k] = v; // 24 pontos, já pequeno
             }
+            else if (Array.isArray(v)) {
+                const { items, truncated } = truncateList(v);
+                out[k] = items.map((item) => compact(item, depth + 1));
+                if (truncated > 0)
+                    out[`${k}Omitted`] = truncated;
+            }
             else {
                 out[k] = compact(v, depth + 1);
             }
@@ -87,6 +175,20 @@ export function pct(value) {
         return '—';
     return `${(value * 100).toFixed(2)}%`;
 }
+/** Tempo até `iso` ("em 3.5 d"); no passado vira `ago`. */
+export function until(iso, now = Date.now()) {
+    const t = Date.parse(iso);
+    if (Number.isNaN(t))
+        return iso;
+    if (t <= now)
+        return ago(iso, now);
+    const s = Math.round((t - now) / 1000);
+    if (s < 3600)
+        return `em ${Math.max(1, Math.round(s / 60))} min`;
+    if (s < 86400)
+        return `em ${(s / 3600).toFixed(1)} h`;
+    return `em ${(s / 86400).toFixed(1)} d`;
+}
 export function ago(iso, now = Date.now()) {
     const t = Date.parse(iso);
     if (Number.isNaN(t))

package/dist/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}

package/dist/guide.d.ts

@@ -8,7 +8,7 @@ export type Framework = (typeof FRAMEWORKS)[number];
 export interface GuideInput {
     framework: Framework;
     databaseDriver?: string;
-    /** URL base da API do FG Track (endpoint do SDK). */
+    /** URL base da API do FG Tracker (endpoint do SDK). */
     endpoint: string;
     /** Chave do projeto; sem ela usa placeholder. */
     apiKey?: string;

package/dist/guide.js

@@ -6,7 +6,7 @@
 export const FRAMEWORKS = ['express', 'nestjs', 'nextjs', 'fastify', 'pino', 'winston'];
 const PLACEHOLDER_KEY = 'stk_SUA_CHAVE_AQUI';
 function envBlock(input) {
-    const key = input.apiKey ?? PLACEHOLDER_KEY;
+    const key = input.apiKey || PLACEHOLDER_KEY;
     return [
         '```bash',
         '# .env (não commitar a chave)',
@@ -23,18 +23,22 @@ function install(extra = []) {
         `# npm install ${pkgs}  |  yarn add ${pkgs}`,
         '```',
         '',
-        '> Dentro do monorepo do FG Track use `"fg-tracker-sdk": "workspace:*"`. Projetos que já usam `stread-track-sdk` só trocam o nome do pacote nos imports (mesma API; as variáveis `STREAD_TRACK_*` continuam lidas como fallback).',
+        '> Dentro do monorepo do FG Tracker use `"fg-tracker-sdk": "workspace:*"`. Projetos que já usam `stread-track-sdk` só trocam o nome do pacote nos imports (mesma API; as variáveis `STREAD_TRACK_*` continuam lidas como fallback).',
     ].join('\n');
 }
 function header(input, title) {
     const lines = [`# ${title}`, ''];
-    if (input.projectName && input.projectId) {
+    if (input.projectName && input.projectId && !input.apiKey) {
+        // Token de leitura (fgt_…) ou papel viewer: a API devolve apiKey ''.
+        lines.push(`Projeto: **${input.projectName}** (\`${input.projectId}\`). A API não devolveu a chave de ingestão (token de leitura \`fgt_…\` ou papel viewer): o código usa o placeholder \`${PLACEHOLDER_KEY}\`. Peça ao usuário para copiar \`FG_TRACKER_KEY\` no painel, em Conectar.`);
+    }
+    else if (input.projectName && input.projectId) {
         lines.push(`Projeto: **${input.projectName}** (\`${input.projectId}\`). A chave abaixo é a chave real deste projeto — trate como segredo.`);
     }
     else {
-        lines.push(`Nenhum projeto informado: o código usa o placeholder \`${PLACEHOLDER_KEY}\`. Crie um projeto com \`track_create_project { name }\` (ou use \`track_list_projects\`) e chame este guia de novo com \`projectId\` para receber a chave real.`);
+        lines.push(`Nenhum projeto informado: o código usa o placeholder \`${PLACEHOLDER_KEY}\`. Crie um projeto com \`tracker_create_project { name }\` (ou use \`tracker_list_projects\`) e chame este guia de novo com \`projectId\` para receber a chave real.`);
     }
-    lines.push('', `API do FG Track: \`${input.endpoint}\`.`, '');
+    lines.push('', `API do FG Tracker: \`${input.endpoint}\`.`, '');
     return lines.join('\n');
 }
 function trackerFile(input, path, service) {
@@ -44,7 +48,7 @@ function trackerFile(input, path, service) {
         `import { createTracker } from 'fg-tracker-sdk';`,
         ``,
         `export const tracker = createTracker({`,
-        `  apiKey: process.env.FG_TRACKER_KEY!,          // ${input.apiKey ?? PLACEHOLDER_KEY}`,
+        `  apiKey: process.env.FG_TRACKER_KEY!,          // ${input.apiKey || PLACEHOLDER_KEY}`,
         `  endpoint: process.env.FG_TRACKER_URL ?? '${input.endpoint}',`,
         `  serviceName: '${service}',`,
         `  flushIntervalMs: 2000,`,
@@ -76,7 +80,7 @@ const FETCH_BLOCK = [
     '```',
 ].join('\n');
 function logsSection(input, service, logger) {
-    const key = input.apiKey ?? PLACEHOLDER_KEY;
+    const key = input.apiKey || PLACEHOLDER_KEY;
     const shipper = [
         '```ts',
         '// src/logs.ts — um shipper por processo; correlaciona traceId/spanId automaticamente',
@@ -127,7 +131,7 @@ function logsSection(input, service, logger) {
         '  format: winston.format.json(),',
         '  transports: [',
         '    new winston.transports.Console(),',
-        '    winstonTransport(logShipper),                  // envia cada log ao FG Track',
+        '    winstonTransport(logShipper),                  // envia cada log ao FG Tracker',
         '  ],',
         '});',
         '```',
@@ -153,9 +157,9 @@ function logsSection(input, service, logger) {
     else if (logger === 'winston')
         parts.push(winston);
     else if (logger === 'nest')
-        parts.push(nest, '', 'Se o app usa pino ou winston, chame `track_instrumentation_guide { framework: "pino" | "winston" }` para o transport correspondente.');
+        parts.push(nest, '', 'Se o app usa pino ou winston, chame `tracker_instrumentation_guide { framework: "pino" | "winston" }` para o transport correspondente.');
     else
-        parts.push(raw, '', 'Com pino ou winston, chame `track_instrumentation_guide { framework: "pino" | "winston" }` para o transport pronto.');
+        parts.push(raw, '', 'Com pino ou winston, chame `tracker_instrumentation_guide { framework: "pino" | "winston" }` para o transport pronto.');
     parts.push('', 'Contrato (§11): o shipper envia lotes para `POST /v1/logs` com o header `x-fg-tracker-key`; níveis `trace|debug|info|warn|error|fatal`; `traceId`/`spanId` são preenchidos automaticamente quando o log acontece dentro de um request instrumentado pelo tracker. Se os exports `fg-tracker-sdk/pino` e `fg-tracker-sdk/winston` ainda não existirem na versão instalada do SDK, envie os logs direto para `POST /v1/logs` (veja o resource `fg-tracker://docs/quickstart`).');
     return parts.join('\n');
 }
@@ -167,14 +171,14 @@ function verifySection(input) {
         '2. Aguarde ~3 s (flush a cada 2 s).',
     ];
     if (input.projectId) {
-        lines.push(`3. Chame \`track_verify_ingest { projectId: "${input.projectId}" }\` — deve reportar spans (e logs) recentes.`);
+        lines.push(`3. Chame \`tracker_verify_ingest { projectId: "${input.projectId}" }\` — deve reportar spans (e logs) recentes.`);
     }
     else {
-        lines.push('3. Chame `track_verify_ingest { projectId }` — deve reportar spans (e logs) recentes.');
+        lines.push('3. Chame `tracker_verify_ingest { projectId }` — deve reportar spans (e logs) recentes.');
     }
     lines.push('4. Se nada chegou: confira `FG_TRACKER_KEY` (4xx no envio = chave inválida, o SDK loga uma vez), se a API responde em `' +
         input.endpoint +
-        '/v1/health`, e se `app.use(tracker.express())` é o PRIMEIRO middleware.', '', 'Depois, `track_get_overview`, `track_list_endpoints` e `track_list_issues` mostram o que foi coletado.');
+        '/v1/health`, e se `app.use(tracker.express())` é o PRIMEIRO middleware.', '', 'Depois, `tracker_get_overview`, `tracker_list_endpoints` e `tracker_list_issues` mostram o que foi coletado.');
     return lines.join('\n');
 }
 export function buildGuide(input) {
@@ -182,7 +186,7 @@ export function buildGuide(input) {
     switch (input.framework) {
         case 'express':
             return [
-                header(input, 'Instrumentar Express com FG Track'),
+                header(input, 'Instrumentar Express com FG Tracker'),
                 '## 1. Instalar',
                 install(),
                 '',
@@ -226,7 +230,7 @@ export function buildGuide(input) {
             ].join('\n');
         case 'nestjs':
             return [
-                header(input, 'Instrumentar NestJS (platform-express) com FG Track'),
+                header(input, 'Instrumentar NestJS (platform-express) com FG Tracker'),
                 '## 1. Instalar',
                 install(),
                 '',
@@ -243,7 +247,7 @@ export function buildGuide(input) {
                 "import { AppModule } from './app.module';",
                 '',
                 'export const tracker = createTracker({',
-                `  apiKey: process.env.FG_TRACKER_KEY!,          // ${input.apiKey ?? PLACEHOLDER_KEY}`,
+                `  apiKey: process.env.FG_TRACKER_KEY!,          // ${input.apiKey || PLACEHOLDER_KEY}`,
                 `  endpoint: process.env.FG_TRACKER_URL ?? '${input.endpoint}',`,
                 `  serviceName: '${service}',`,
                 '});',
@@ -297,7 +301,7 @@ export function buildGuide(input) {
             ].join('\n');
         case 'nextjs':
             return [
-                header(input, 'Instrumentar Next.js (App Router, runtime Node) com FG Track'),
+                header(input, 'Instrumentar Next.js (App Router, runtime Node) com FG Tracker'),
                 '## 1. Instalar',
                 install(),
                 '',
@@ -315,7 +319,7 @@ export function buildGuide(input) {
                 'export const tracker: Tracker =',
                 '  g.__fgTracker ??',
                 '  (g.__fgTracker = createTracker({',
-                `    apiKey: process.env.FG_TRACKER_KEY!,        // ${input.apiKey ?? PLACEHOLDER_KEY}`,
+                `    apiKey: process.env.FG_TRACKER_KEY!,        // ${input.apiKey || PLACEHOLDER_KEY}`,
                 `    endpoint: process.env.FG_TRACKER_URL ?? '${input.endpoint}',`,
                 `    serviceName: '${service}',`,
                 '  }));',
@@ -374,7 +378,7 @@ export function buildGuide(input) {
             ].join('\n');
         case 'fastify':
             return [
-                header(input, 'Instrumentar Fastify com FG Track'),
+                header(input, 'Instrumentar Fastify com FG Tracker'),
                 'O SDK não tem plugin Fastify dedicado; o middleware Express funciona num hook `onRequest` sobre `request.raw`/`reply.raw` (o hook chama `done` dentro do contexto assíncrono do span, então `instrumentPg`, `wrapFetch` e `tracker.span` enxergam o request).',
                 '',
                 '## 1. Instalar',
@@ -447,7 +451,7 @@ export function buildGuide(input) {
             ].join('\n');
         case 'pino':
             return [
-                header(input, 'Enviar logs do pino para o FG Track'),
+                header(input, 'Enviar logs do pino para o FG Tracker'),
                 '## 1. Instalar',
                 install(),
                 '',
@@ -459,7 +463,7 @@ export function buildGuide(input) {
                 '## 4. Correlação com traces',
                 'Se o processo também usa o tracker (`createTracker` + `tracker.express()`), cada log emitido durante um request ganha `traceId`/`spanId` e aparece com link para o trace no console. Sem tracker, os logs chegam normalmente, só sem correlação.',
                 '',
-                '## 5. Sintaxe de busca (`track_search_logs` e página /logs)',
+                '## 5. Sintaxe de busca (`tracker_search_logs` e página /logs)',
                 '- texto livre → busca full-text (`websearch_to_tsquery`); `"frase exata"` entre aspas;',
                 '- `key=value` → filtra `context->>key`;',
                 '- `~trecho` → ILIKE (substring, via trigram).',
@@ -468,7 +472,7 @@ export function buildGuide(input) {
             ].join('\n');
         case 'winston':
             return [
-                header(input, 'Enviar logs do winston para o FG Track'),
+                header(input, 'Enviar logs do winston para o FG Tracker'),
                 '## 1. Instalar',
                 install(),
                 '',
@@ -480,7 +484,7 @@ export function buildGuide(input) {
                 '## 4. Correlação com traces',
                 'Se o processo também usa o tracker (`createTracker` + `tracker.express()`), cada log emitido durante um request ganha `traceId`/`spanId`. Chame `logShipper.flush()` (ou `tracker.shutdown()` + `logShipper.shutdown()`) no encerramento para não perder o último lote.',
                 '',
-                '## 5. Sintaxe de busca (`track_search_logs` e página /logs)',
+                '## 5. Sintaxe de busca (`tracker_search_logs` e página /logs)',
                 '- texto livre → full-text; `"frase exata"` entre aspas; `key=value` → `context->>key`; `~trecho` → substring.',
                 '',
                 verifySection(input),