open-index/open-npm huggingface dataset:
npm package: @marcos_feitoza/devops-tf-circleci
Description: Wrapper Terraform project to manage CircleCI using the local `terraform-circleci` module.
Latest version: 1.0.0

# devops-tf-circleci

Wrapper Terraform project to manage CircleCI using the local `terraform-circleci` module.

## Local run
- Export token:
  - `export TF_VAR_circleci_api_token="<CIRCLECI_PERSONAL_TOKEN>"`
- Plan:
  - `terraform init`
  - `terraform plan -var-file=../devops-tf-account-vars/global.tfvars -var-file=../devops-tf-account-vars/dev/ca-central-1/circleci.tfvars -out=tf_circleci.out`
- Apply:
  - `terraform apply --auto-approve \
  -var-file=../devops-tf-account-vars/dev/ca-central-1/circleci.tfvars tf_circleci.out`

## Notes
- `organization_id` is the CircleCI org UUID (not slug).
- Keep `circleci_api_token` only in CircleCI Context/Env var, never in `tfvars`.

```
circleci info org
```
```
+--------------------------------------+--------------+
|                  ID                  |     NAME     |
+--------------------------------------+------------- |
| b0275876-d123-47cb-91e1-ec5e3ec3a3b1 | MarcosOps    |
+--------------------------------------+--------------+
```


```bash
#!/usr/bin/env bash
set -euo pipefail
set +x

ORG_ID="b0275876-d123-47cb-91e1-ec5e3ec3a3b1"
CTX="shared-ci-secrets"

# 1) cria o context se não existir
if ! circleci context list --org-id "$ORG_ID" --json | jq -e --arg c "$CTX" '.[] | select(.name==$c)' >/dev/null; then
  circleci context create --org-id "$ORG_ID" "$CTX"
fi

# 2) grava/atualiza secrets (sobrescreve se já existir)
printf %s "$DOCKER_PASSWORD" | circleci context store-secret --org-id "$ORG_ID" "$CTX" DOCKER_PASSWORD
printf %s "$DOCKER_REPO"     | circleci context store-secret --org-id "$ORG_ID" "$CTX" DOCKER_REPO
printf %s "$DOCKER_USERNAME" | circleci context store-secret --org-id "$ORG_ID" "$CTX" DOCKER_USERNAME
printf %s "$GH_TOKEN"        | circleci context store-secret --org-id "$ORG_ID" "$CTX" GH_TOKEN
printf %s "$NPM_TOKEN"       | circleci context store-secret --org-id "$ORG_ID" "$CTX" NPM_TOKEN

echo "OK: context e secrets aplicados."
```
```
Elas aparecem em:

Organization Settings > Contexts > shared-ci-secretsElas não aparecem em Project Settings > Environment Variables quando vêm de context.
Elas aparecem em:

Organization Settings > Contexts > shared-ci-secrets
```
npm package: @marcos_feitoza/loki
Description: Este repositório entrega o Loki para armazenamento centralizado de logs Kubernetes.
Latest version: 1.0.0

# Loki (Armazenamento e consulta de logs)

Este repositório entrega o Loki para armazenamento centralizado de logs Kubernetes.

## Papel na arquitetura

- Recebe logs do Vector.
- Indexa por labels e armazena conteúdo.
- Responde consultas LogQL para Grafana.

## Integração com Vector e Grafana

Fluxo:

- `Pods -> Vector -> Loki -> Grafana`

Onde:

- Vector envia JSON com labels (`namespace`, `app`, `pod`, `container`, `node`).
- Grafana usa datasource Loki (`uid: loki`) para dashboards e Explore.

## Configuração principal

Arquivo de referência:

- `helm/prod-values.yaml`

Pontos atuais:

- Imagem: `grafana/loki:3.6.5`
- Serviço: `ClusterIP:3100`
- Retention: `168h` (7 dias)
- Persistência: `disabled` (logs efêmeros em caso de restart)

## Verificação rápida

- Pod Loki:

```bash
kubectl -n monitoring get pods -l app.kubernetes.io/name=loki -o wide
```

- Logs Loki:

```bash
kubectl -n monitoring logs -l app.kubernetes.io/name=loki --tail=200
```

- Teste de saúde via serviço:

```bash
kubectl -n monitoring exec <grafana-pod> -- sh -c "wget -qO- http://loki.monitoring.svc.cluster.local:3100/ready"
```

- Query de teste no Grafana Explore:

```logql
{namespace="monitoring"}
```

## Queries úteis (LogQL)

- Logs de um app:

```logql
{namespace="app", app="personal-finance-backend-market-data-crypto"}
```

- Busca por texto no payload:

```logql
{namespace="app", app=~".*crypto.*"} |= "Finished Investment Balance Calculation"
```

- Busca ampla por termo:

```logql
{namespace="app"} |~ "(?i)crypto"
```

## Troubleshooting comum

- Explore funciona, dashboard não:
  - Revisar variáveis e filtros do painel.
  - Validar datasource do painel (`Loki`, `uid=loki`).
- Sem ingestão:
  - Checar logs do Vector e endpoint Loki.
  - Verificar readiness de Loki.
- Perda de histórico após restart:
  - Esperado com `persistence.enabled: false`.

## Recomendações

- Para retenção real em homelab, habilitar `persistence`.
- Manter estratégia de labels estáveis para consultas eficientes.
npm package: @marcos_feitoza/personal-finance-backen-trades-assets
Description: Este projeto contém a lógica de negócios e os modelos de dados específicos para o gerenciamento de `Trades` (transações de compra/venda de ativos) e `Assets` (ativos como ações, criptomoedas, etc.).
Latest version: 1.2.4

# Biblioteca de Trades e Ativos - Personal Finance Backend

Este projeto contém a lógica de negócios e os modelos de dados específicos para o gerenciamento de `Trades` (transações de compra/venda de ativos) e `Assets` (ativos como ações, criptomoedas, etc.).

## Propósito

O objetivo desta biblioteca é encapsular toda a lógica de criação, leitura, atualização e exclusão (soft-delete) de trades e ativos. Ela interage com serviços externos (como o `market-data-service` para buscar detalhes de ativos) e com o banco de dados via `personal-finance-backend-shared`.

## Conteúdo Principal

- **`routers/trades.py`**: Define endpoints para a criação, listagem e exclusão (soft-delete) de trades.
- **`routers/assets.py`**: Define endpoints para a listagem e gerenciamento de ativos.

## Regras de Plano (Acesso)

As rotas desta biblioteca estão protegidas por plano mínimo `plus`:

- `GET/POST /api/trades/*`
- `GET/POST /api/assets/*`

Usuários `free` recebem `403` com payload de `plan_upgrade_required`.
Isso garante consistência com a política de monetização do `backend-core`.

## Tecnologias

- **Framework**: FastAPI (seus routers são usados por outros serviços)
- **Busca de Dados Externos**: Utiliza `httpx` para comunicação com o `market-data-service`.
- **Banco de Dados**: Interage com o PostgreSQL através da `personal-finance-backend-shared`.
- **Dependências Locais**:
  - `personal-finance-backend-shared`: Para acesso aos modelos, `crud` e utilitários.

---

## Como Usar (Instalação como Dependência)

Este projeto não é um serviço executável por si só. Ele é projetado para ser instalado como uma dependência local por outros serviços do backend (ex: `personal-finance-backend-core`).

Para incluir esta biblioteca como uma dependência editável em outro serviço (por exemplo, no `requirements.txt` do `personal-finance-backend-core`), adicione a seguinte linha no `requirements.txt` do serviço consumidor:

```
-e ./personal-finance-backend-trades-assets
```

**Importante:** Certifique-se de que o contexto de build do Docker (`Dockerfile`) ou o script de build (`dockerbuild.sh`) do serviço consumidor está copiando corretamente o diretório `personal-finance-backend-trades-assets` para o local esperado para que o `pip install -e` funcione.
npm package: @marcos_feitoza/personal-finance-build
Description: Build/deploy helper scripts for the Personal Finance monorepo (Podman + Docker Hub + Kubernetes rollout support).
Latest version: 1.1.1

# Personal Finance Build Utilities

Build/deploy helper scripts for the Personal Finance monorepo (Podman + Docker Hub + Kubernetes rollout support).

## Purpose

Provide a single script flow to build and push service images used by Argo CD deployment in the cluster.

## Main Script

- `podman-build.sh`

Supported services:

- `core`
- `balance`
- `market-data`
- `crypto`
- `ai-insights`
- `ai-advisor`
- `frontend`

## AI Services Support (Updated)

`ai-insights` is fully integrated in build flow:

```bash
./podman-build.sh ai-insights --push
```

Optional rollout:

```bash
./podman-build.sh ai-insights --push --rollout --wait
```

`ai-advisor` is also integrated:

```bash
./podman-build.sh ai-advisor --push
```

## Typical Workflow

1. Build and push image using service alias.
2. Update Helm values/image tag when needed.
3. Argo CD reconciles target app.
4. Validate pod health and API endpoints.

## Useful Flags

- `--push`
- `--rollout`
- `--wait`
- `--logs`
- `--platform` (default `linux/arm64`)
- `--tests` (python services)

## Notes

- Script is optimized for Raspberry Pi/Kubernetes environment (arm64 default).
- Image target pattern: `docker.io/<user>/<service>:<tag>`
- For AI stack updates, deploy order is typically:
  1. `ai-insights`
  2. `ai-advisor`
  3. `backend-core`
  4. frontend packages/app
npm package: @marcos_feitoza/personal-finance-frontend-feature-charts
Description: Este pacote contém a implementação de diversas telas de gráficos financeiros para a aplicação Personal Finance Frontend.
Latest version: 1.1.1

# Feature: Gráficos (Frontend Flutter)

Este pacote contém a implementação de diversas telas de gráficos financeiros para a aplicação Personal Finance Frontend.

## Propósito

O objetivo deste pacote é fornecer ao usuário uma representação visual clara e intuitiva de suas finanças, ajudando na análise de tendências de receitas e despesas.

## Conteúdo Principal

-   **`lib/screens/salary_chart_screen.dart`**: Gráfico para visualizar tendências de salários e receitas.
-   **`lib/screens/expense_chart_screen.dart`**: Gráfico para visualizar tendências e distribuição de despesas.
-   **`viewmodels/salary_chart_viewmodel.dart`**: Lógica para a gestão de dados do gráfico de salários.

---

## Como Usar (Instalação como Dependência)

Este pacote é uma dependência local para a aplicação principal (`personal-finance-frontend`).

No `pubspec.yaml` da aplicação principal, adicione a seguinte linha em `dependencies`:

```yaml
personal_finance_frontend_feature_charts:
  path: ../personal-finance-frontend-feature-charts
```

## Features

-   **Visualização de Tendências**: Gráficos para acompanhar a evolução de salários e despesas ao longo do tempo.
-   **Análise de Distribuição**: Gráficos que mostram a proporção de gastos por categoria.
-   **Interatividade**: Permite interações básicas com os gráficos (ex: tooltips).
npm package: @marcos_feitoza/personal-finance-frontend-feature-profile
Description: User profile and personal settings feature package.
Latest version: 1.2.0

# Feature: Profile (Flutter)

User profile and personal settings feature package.

## Purpose

Provide profile management, user settings, and notification center access.

## Notifications Center (Updated)

`NotificationsScreen` is now a real message inbox for AI notifications (not placeholder-only).

Capabilities:

- load backend notifications
- mark all as read when opened
- refresh list
- show each message with timestamp
- show informational timer for next AI notification eligibility
- collect per-message feedback (thumbs up/down)

Feedback from notifications is sent to AI feedback API and is visible in AI observability metrics.

## Key Files

- `lib/screens/notifications_screen.dart`
- `lib/screens/profile_screen.dart`

## Dependencies

- `core-services` (`NotificationService`, `AiService`)
- `core-ui` notification widgets

## Conteúdo Principal

-   **`lib/screens/profile_screen.dart`**: A tela principal que exibe o formulário de perfil e a seção de segurança. Organiza as informações em seções editáveis individualmente.
-   **`lib/screens/change_password_form.dart`**: O formulário dedicado para a funcionalidade de alteração de senha, integrado à seção 'Login & Security'.
-   **`lib/viewmodels/profile_viewmodel.dart`**: O `ChangeNotifier` (ViewModel) que gerencia o estado da tela, incluindo a busca dos dados do perfil do usuário via API, o envio de atualizações e a lógica para alteração de senha.
-   **`lib/screens/categories_settings_screen.dart`**: Tela de configuração de categorias/subcategorias do usuário (CRUD) usada para personalizar dropdowns do app.

---

## Como Usar (Instalação como Dependência)

Este pacote é uma dependência local para a aplicação principal (`personal-finance-frontend`) e outros pacotes de feature que precisem navegar para a tela de perfil (como o `feature-dashboard`).

No `pubspec.yaml` do pacote consumidor, adicione a seguinte linha em `dependencies`:

```yaml
personal_finance_frontend_feature_profile:
  path: ../personal-finance-frontend-feature-profile
```

## Features

-   **Visualização de Dados Detalhados**: Exibe informações registradas (e-mail de login, nome, sobrenome) como somente leitura, e outros detalhes pessoais (nome preferido, gênero, estado civil), contato, endereço e ocupação em seções separadas.
-   **Edição de Perfil por Seção**: Permite que o usuário edite e salve informações específicas em cada seção de forma independente ('Personal Details', 'Contact', 'Address', 'Occupation'), mantendo o restante do perfil como somente leitura até que o modo de edição seja ativado para aquela seção.
-   **Alteração de Senha Segura**: Oferece um formulário dedicado na seção 'Login & Security' para alterar a senha, com validação da senha atual e confirmação da nova senha.
-   **Comunicação com Backend**: Utiliza o `UserService` do pacote `core-services` para buscar, salvar informações do perfil e alterar a senha na API.
npm package: @marcos_feitoza/personal-finance-frontend-feature-reports
Description: Este pacote contém a implementação de diversas telas de relatórios financeiros para a aplicação Personal Finance Frontend.
Latest version: 1.2.1

# Feature: Relatórios (Frontend Flutter)

Este pacote contém a implementação de diversas telas de relatórios financeiros para a aplicação Personal Finance Frontend.

## Propósito

O objetivo deste pacote é fornecer ao usuário uma visão detalhada e analítica de suas finanças através de diferentes tipos de relatórios, permitindo um acompanhamento aprofundado de receitas, despesas e movimentações.

## Conteúdo Principal

-   **`lib/screens/salary_report_screen.dart`**: Relatório detalhado sobre salários e outras receitas.
-   **`lib/screens/expense_report_screen.dart`**: Relatório detalhado sobre despesas, categorizadas.
-   **`lib/screens/summary_report_screen.dart`**: Relatório resumido das finanças.
-   **`lib/screens/move_money_report_screen.dart`**: Relatório sobre movimentações de dinheiro entre contas de investimento.
-   **`viewmodels/expense_report_viewmodel.dart`**: Lógica para a gestão de dados do relatório de despesas.

---

## Como Usar (Instalação como Dependência)

Este pacote é uma dependência local para a aplicação principal (`personal-finance-frontend`).

No `pubspec.yaml` da aplicação principal, adicione a seguinte linha em `dependencies`:

```yaml
personal_finance_frontend_feature_reports:
  path: ../personal-finance-frontend-feature-reports
```

## Features

-   **Relatórios Financeiros Diversos**: Inclui relatórios de salários, despesas, resumos e movimentações de dinheiro.
-   **Visualização Detalhada**: Apresenta os dados de forma tabulada para fácil análise.
-   **Filtros e Agrupamentos**: Permite filtrar e agrupar dados para uma análise mais específica.
npm package: @marcos_feitoza/personal-finance-market-data
Description: Este projeto é um microsserviço independente responsável por buscar dados de mercado para ações.
Latest version: 1.1.5

# Serviço de Dados de Mercado (Ações) - Personal Finance

Este projeto é um microsserviço independente responsável por buscar dados de mercado para ações.

## Propósito

Este serviço atua como um proxy e um adaptador para a API do Yahoo Finance (`yfinance`). Sua responsabilidade é fornecer dados de mercado, como preços ao vivo e detalhes de ativos, para outros serviços no sistema, centralizando a lógica de acesso a dados de mercado de ações em um único lugar.

## Tecnologias

- **Framework**: FastAPI
- **Fonte de Dados**: Biblioteca `yfinance`
- **Deploy**: Docker & Kubernetes (via Helm)
- **Dependências Locais**:
  - `personal-finance-backend-shared`: Para utilitários compartilhados, como o de logging.

---

## Como Começar

### Pré-requisitos

- Python 3.9+
- Docker
- Acesso ao repositório `personal-finance-backend-shared` no mesmo nível de diretório.

### Instalação

1.  Navegue até o diretório raiz do monorepo.
2.  Instale as dependências. O uso de um ambiente virtual (`venv`) é recomendado.
    ```bash
    pip install -r personal-finance-backend-market-data/requirements.txt
    ```
    *Nota: O `requirements.txt` deste serviço espera que a `personal-finance-backend-shared` seja instalada em modo editável.*

---

## Como Executar

### Localmente para Desenvolvimento

A partir do diretório raiz (`finace`), execute o seguinte comando para iniciar o servidor com hot-reload:

```bash
uvicorn personal-finance-backend-market-data.app.main:app --reload --app-dir .
```
Isso iniciará o serviço em `http://127.0.0.1:8000`.

### Via Docker (Produção)

1.  Navegue para o diretório deste serviço (`personal-finance-backend-market-data`).
2.  O script `dockerbuild.sh` automatiza o processo de:
    - Copiar a biblioteca compartilhada para um diretório local temporário.
    - Construir a imagem Docker multiplataforma.
    - Publicar a imagem no Docker Hub.
    ```bash
    ./dockerbuild.sh
    ```
3.  O deploy no Kubernetes é gerenciado pelo Argo CD a partir do Helm chart em `/helm`.

---

## Estrutura da API

- **`POST /api/market-data/prices`**: Recebe uma lista de símbolos de ações e retorna seus preços ao vivo.
- **`POST /api/market-data/details/{symbol}`**: Retorna detalhes de um ativo específico (nome, indústria, etc.).
- **`GET /api/market-data/validate/{symbol}`**: Valida se um símbolo de ação existe e é encontrável no `yfinance`.

## Logging

O serviço utiliza um sistema de **logging estruturado (JSON)** centralizado na `personal-finance-backend-shared`.

- **Correlation ID**: Todas as requisições que chegam com um header `X-Correlation-ID` (propagado pelo `core-service`) usarão este ID em todos os seus logs. Se nenhuma ID for recebida, uma nova será gerada. Isso permite rastrear uma operação através de todos os microsserviços.
- **Filtragem**: Por ser JSON, os logs são facilmente pesquisáveis e filtráveis em ferramentas de monitoramento.
npm package: @marcos_feitoza/terraform-circleci
Description: Terraform module to manage CircleCI resources base on devops-tf-circleci
Latest version: 1.0.1

# terraform-circleci

Terraform module to manage CircleCI resources base on devops-tf-circleci

## Implemented resources
- `circleci_project`

## Inputs
- `organization_id`: CircleCI organization UUID
- `projects`: map of projects to manage

## Example

```hcl
module "circleci" {
  source = "./terraform-circleci"

  organization_id = var.organization_id

  projects = {
    infra = {
      name = "devops-tf-aws-vpc"
    }
    homelab = {
      name = "raspbery-cluster"
    }
  }
}
```
npm package: @marcos_feitoza/vector
Description: Este repositório entrega o Vector como DaemonSet para coleta de logs dos pods.
Latest version: 1.0.1

# Vector (Coletor de logs)

Este repositório entrega o Vector como DaemonSet para coleta de logs dos pods.

## Papel na arquitetura

- Coleta `stdout/stderr` de pods no nó (`kubernetes_logs`).
- Normaliza campos e labels para consulta no Loki/Grafana.
- Encaminha para `Loki` em `http://loki.monitoring.svc.cluster.local:3100`.

## Integração com Loki e Grafana

Fluxo:

1. Pod escreve log em stdout/stderr.
2. Vector captura no nó.
3. Transform `normalize` define:
   - `namespace`
   - `pod`
   - `container`
   - `node`
   - `app` (fallback por labels e nomes)
4. Sink Loki envia payload JSON + labels.
5. Grafana consulta Loki com LogQL e usa labels para filtros (`namespace`, `app`, `pod`, `container`).

## Arquivos principais

- `helm/prod-values.yaml`: imagem, recursos e endpoint Loki.
- `helm/templates/configmap.yaml`: pipeline Vector (`sources`, `transforms`, `sinks`).

## Mapeamento de label `app`

No transform atual, prioridade:

1. `kubernetes.pod_labels.app`
2. `kubernetes.pod_labels."app.kubernetes.io/name"`
3. `kubernetes.pod_labels."app_kubernetes_io_name"`
4. `kubernetes.pod_labels."app.kubernetes.io/instance"`
5. `container`
6. `pod`
7. fallback `unknown`

Isso reduz casos de `app="unknown"` no Grafana.

## Verificação rápida

- Pods do Vector:

```bash
kubectl -n monitoring get pods -l app.kubernetes.io/name=vector -o wide
```

- Logs do Vector:

```bash
kubectl -n monitoring logs -l app.kubernetes.io/name=vector --tail=200
```

- Teste no Grafana Explore (Loki):

```logql
{namespace="app"}
```

ou com app específico:

```logql
{namespace="app", app=~".*crypto.*"}
```

## Troubleshooting comum

- Sem logs no Grafana:
  - Validar endpoint do Loki no Vector.
  - Conferir conectividade DNS/Service `loki.monitoring.svc.cluster.local`.
- `app=unknown`:
  - Revisar labels dos Deployments.
  - Ajustar fallback do transform em `configmap.yaml`.
- Alta cardinalidade:
  - Evitar labels dinâmicas no app (IDs por requisição, etc.).

## Convenções

- Logs em JSON estruturado quando possível.
- Labels estáveis: `app`, `namespace`, `pod`, `container`, `node`.