siesa-agents 2.1.78 → 2.1.80

package/siesa-agents/observability/scripts/sa-init-env.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// sa-init-env.js — Ensure `~/.claude/observability/.env` exists with placeholders for the two
+// OTLP variables the Siesa observability stack needs:
+//   - SA_OTLP_ENDPOINT
+//   - SA_OTLP_HEADERS
+//
+// This script is idempotent. If the file already contains both variables, it exits without
+// touching anything. If the file is missing, it creates it with clearly-fake placeholder
+// values that the user is expected to edit before workflows emit real telemetry. If the file
+// exists but is missing one of the two variables, the missing one is appended — existing
+// values for unrelated keys are preserved exactly.
+//
+// Note: this script does NOT change how sa-emit.js loads configuration. sa-emit.js continues
+// to load only the project-local .env (`process.cwd()/.env`). This script keeps
+// `~/.claude/observability/.env` as a discoverable per-machine template so engineers know
+// which variables they need without having to read sa-emit.js.
+//
+// Modes:
+//   <no args>    Default = --ensure. Creates the file (and parent dir) when needed.
+//   --check      Read-only check. Reports the current state without writing anything.
+//
+// Exit codes:
+//   0  Success (ensure created/updated/no-op, or check ran cleanly)
+//   1  Write or filesystem error
+
+'use strict'
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const TARGET_VARS = ['SA_OTLP_ENDPOINT', 'SA_OTLP_HEADERS']
+
+const PLACEHOLDERS = {
+  SA_OTLP_ENDPOINT: 'https://your-otel-collector.example.com',
+  SA_OTLP_HEADERS:  'Authorization=Bearer YOUR_TOKEN_HERE',
+}
+
+function parseArgs(argv) {
+  const out = {}
+  for (const a of argv) {
+    if (a.startsWith('--')) out[a.slice(2)] = true
+  }
+  return out
+}
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + '\n')
+}
+
+function resolveTarget() {
+  // sa-emit.js uses os.homedir() + '.claude' + 'observability' for its state dir; we mirror
+  // that path so engineers see a single, predictable location across both tools.
+  const dir = path.join(os.homedir(), '.claude', 'observability')
+  const file = path.join(dir, '.env')
+  return { dir, file }
+}
+
+// Parse an existing .env file into an ordered list of entries plus a key index. We track
+// order so we can rewrite the file deterministically without scrambling the user's edits.
+function readEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { exists: false, lines: [], keys: new Set() }
+  }
+  const raw = fs.readFileSync(filePath, 'utf8')
+  const lines = raw.split(/\r?\n/)
+  const keys = new Set()
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq === -1) continue
+    keys.add(trimmed.slice(0, eq).trim())
+  }
+  return { exists: true, lines, keys, raw }
+}
+
+function findMissingVars(keys) {
+  return TARGET_VARS.filter(v => !keys.has(v))
+}
+
+function buildFreshFile() {
+  return [
+    '# Siesa observability — OTLP exporter configuration.',
+    '# This file is a per-machine template. Replace the placeholder values with the real',
+    '# endpoint and headers you received from the observability team. sa-emit.js itself',
+    '# reads only the project-local .env; this file documents which variables are required',
+    '# and gives you one canonical place to keep your personal copy of them.',
+    '',
+    `SA_OTLP_ENDPOINT=${PLACEHOLDERS.SA_OTLP_ENDPOINT}`,
+    `SA_OTLP_HEADERS=${PLACEHOLDERS.SA_OTLP_HEADERS}`,
+    '',
+  ].join('\n')
+}
+
+function appendMissing(existingRaw, missing) {
+  // Append missing vars at the bottom under a clear delimiter so the user can spot the new
+  // additions and replace the placeholders.
+  const needsLeadingNewline = existingRaw.length > 0 && !existingRaw.endsWith('\n')
+  const parts = [existingRaw]
+  if (needsLeadingNewline) parts.push('\n')
+  parts.push('\n# --- added by sa-init-env.js (placeholders, edit before use) ---\n')
+  for (const v of missing) {
+    parts.push(`${v}=${PLACEHOLDERS[v]}\n`)
+  }
+  return parts.join('')
+}
+
+function runCheck() {
+  const { dir, file } = resolveTarget()
+  const env = readEnvFile(file)
+  if (!env.exists) {
+    emit({
+      status: 'missing',
+      message: `~/.claude/observability/.env does not exist. Run without --check to create it with placeholders.`,
+      env_path: file,
+      env_dir: dir,
+      target_vars: TARGET_VARS,
+      present_vars: [],
+      missing_vars: TARGET_VARS.slice(),
+    })
+    return
+  }
+  const missing = findMissingVars(env.keys)
+  if (missing.length === 0) {
+    emit({
+      status: 'already-configured',
+      message: `~/.claude/observability/.env already declares both SA_OTLP_ENDPOINT and SA_OTLP_HEADERS.`,
+      env_path: file,
+      env_dir: dir,
+      target_vars: TARGET_VARS,
+      present_vars: TARGET_VARS.slice(),
+      missing_vars: [],
+    })
+    return
+  }
+  emit({
+    status: 'partial',
+    message: `~/.claude/observability/.env exists but is missing: ${missing.join(', ')}. Run without --check to append placeholders for the missing variables.`,
+    env_path: file,
+    env_dir: dir,
+    target_vars: TARGET_VARS,
+    present_vars: TARGET_VARS.filter(v => env.keys.has(v)),
+    missing_vars: missing,
+  })
+}
+
+function runEnsure() {
+  const { dir, file } = resolveTarget()
+
+  if (!fs.existsSync(dir)) {
+    try {
+      fs.mkdirSync(dir, { recursive: true })
+    } catch (err) {
+      emit({ status: 'error', message: `Failed to create ${dir}: ${err.message}`, env_path: file })
+      process.exit(1)
+    }
+  }
+
+  const env = readEnvFile(file)
+
+  if (!env.exists) {
+    try {
+      fs.writeFileSync(file, buildFreshFile(), { encoding: 'utf8' })
+    } catch (err) {
+      emit({ status: 'error', message: `Failed to write ${file}: ${err.message}`, env_path: file })
+      process.exit(1)
+    }
+    emit({
+      status: 'created',
+      message: `Wrote ${file} with placeholder values. Edit the file and replace the placeholders with the real OTLP endpoint and headers before running workflows that emit telemetry.`,
+      env_path: file,
+      env_dir: dir,
+      target_vars: TARGET_VARS,
+      wrote_vars: TARGET_VARS.slice(),
+      placeholders: PLACEHOLDERS,
+    })
+    return
+  }
+
+  const missing = findMissingVars(env.keys)
+  if (missing.length === 0) {
+    emit({
+      status: 'already-configured',
+      message: `~/.claude/observability/.env already declares both SA_OTLP_ENDPOINT and SA_OTLP_HEADERS. Nothing to do.`,
+      env_path: file,
+      env_dir: dir,
+      target_vars: TARGET_VARS,
+      present_vars: TARGET_VARS.slice(),
+    })
+    return
+  }
+
+  // File exists but is missing one or more target vars. Append the missing ones with
+  // placeholders; never modify existing entries — the user may have already filled in
+  // real values for the keys that are present.
+  try {
+    fs.writeFileSync(file, appendMissing(env.raw, missing), { encoding: 'utf8' })
+  } catch (err) {
+    emit({ status: 'error', message: `Failed to update ${file}: ${err.message}`, env_path: file })
+    process.exit(1)
+  }
+  emit({
+    status: 'updated',
+    message: `Appended placeholders for missing variables to ${file}: ${missing.join(', ')}. Replace the placeholders with real values before running workflows that emit telemetry.`,
+    env_path: file,
+    env_dir: dir,
+    target_vars: TARGET_VARS,
+    appended_vars: missing,
+    placeholders: PLACEHOLDERS,
+  })
+}
+
+const args = parseArgs(process.argv.slice(2))
+if (args['check']) {
+  runCheck()
+} else {
+  runEnsure()
+}

package/siesa-agents/observability/scripts/sa-init-project.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// sa-init-project.js — Initialize a `.siesa-project` file that consolidates observability
+// metrics across multiple sub-repos belonging to the same logical project.
+//
+// Why this exists:
+//   sa-emit.js derives `project_id` from `git remote get-url origin` by default. For projects
+//   split across docs/backend/frontend sub-repos (each with a different remote), the same
+//   logical project ends up fragmented in GCP under several `project_id` values. A
+//   `.siesa-project` file placed in a parent directory above all sub-repos lets sa-emit.js
+//   collapse them under one consistent slug.
+//
+// Two modes:
+//   --detect                       Inspect the cwd, propose a logical slug and list candidate
+//                                  parent directories. Outputs a single JSON object to stdout.
+//   --write --slug <s> --dir <d>   Write `<d>/.siesa-project` with `<s>` as its only line.
+//                                  Outputs a JSON status object. Refuses to overwrite unless
+//                                  `--force` is passed.
+//
+// Exit codes:
+//   0  Success (detect produced a proposal OR write succeeded)
+//   1  Argument / usage error
+//   2  Detection completed but no action is required (single-repo, no remote, already
+//      configured) — the JSON `status` field explains which case
+//   3  Write failed (target exists without --force, permission error, etc.)
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { execSync } = require('child_process')
+
+function parseArgs(argv) {
+  const out = {}
+  let i = 0
+  while (i < argv.length) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const key = a.slice(2)
+      const next = argv[i + 1]
+      if (next !== undefined && !next.startsWith('--')) {
+        out[key] = next
+        i += 2
+      } else {
+        out[key] = true
+        i += 1
+      }
+    } else {
+      i += 1
+    }
+  }
+  return out
+}
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + '\n')
+}
+
+function tryExec(cmd, opts) {
+  try {
+    return execSync(cmd, Object.assign({ encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }, opts || {})).trim()
+  } catch (_) {
+    return null
+  }
+}
+
+// Walk up from `startDir` looking for an existing `.siesa-project`. Returns
+// { path, value } of the first match found, or null.
+function findExistingSiesaProject(startDir) {
+  let cur = path.resolve(startDir)
+  for (let i = 0; i < 40; i++) {
+    const candidate = path.join(cur, '.siesa-project')
+    if (fs.existsSync(candidate)) {
+      try {
+        const first = fs.readFileSync(candidate, 'utf8').split(/\r?\n/)[0].trim()
+        return { path: candidate, value: first }
+      } catch (_) {
+        return { path: candidate, value: null }
+      }
+    }
+    const parent = path.dirname(cur)
+    if (parent === cur) return null
+    cur = parent
+  }
+  return null
+}
+
+// Parse `<org>/<repo>` from a git remote URL. Returns { org, repo } or null.
+function parseRemote(url) {
+  if (!url) return null
+  const m = url.match(/[:/]([^/:]+)\/([^/:]+?)(?:\.git)?$/)
+  if (!m) return null
+  return { org: m[1], repo: m[2] }
+}
+
+// Apply the Siesa multi-repo naming convention to derive a logical slug.
+//
+//   business-pos-backend-pdv        → pos-pdv
+//   business-pos-docs-tomapedido    → pos-tomapedido
+//   foo-frontend-bar                → foo-bar
+//
+// Returns { matched: true, slug, module, role, rest } if the convention applies,
+// or { matched: false } if the repo name has no docs|backend|frontend segment.
+function deriveLogicalSlug(repoName) {
+  if (!repoName) return { matched: false }
+  const parts = repoName.split('-')
+  const roleIdx = parts.findIndex(p => p === 'docs' || p === 'backend' || p === 'frontend')
+  if (roleIdx === -1) return { matched: false }
+
+  // Drop a leading "business-" prefix if present — it is an organizational marker, not
+  // part of the logical project name.
+  const cleaned = parts[0] === 'business' ? parts.slice(1) : parts.slice()
+  const adjustedRoleIdx = parts[0] === 'business' ? roleIdx - 1 : roleIdx
+  if (adjustedRoleIdx < 0) return { matched: false }
+
+  const role = cleaned[adjustedRoleIdx]
+  const before = cleaned.slice(0, adjustedRoleIdx)
+  const after = cleaned.slice(adjustedRoleIdx + 1)
+  if (before.length === 0 || after.length === 0) return { matched: false }
+
+  const slug = before.concat(after).join('-')
+  return {
+    matched: true,
+    slug,
+    module: before.join('-'),
+    role,
+    rest: after.join('-'),
+  }
+}
+
+function listParentCandidates(gitRoot) {
+  const candidates = []
+  let cur = path.resolve(gitRoot)
+  const labels = [
+    'git root',
+    '1 level up',
+    '2 levels up (typical parent of docs/apps/)',
+    '3 levels up',
+    '4 levels up',
+  ]
+  for (let i = 0; i < labels.length; i++) {
+    candidates.push({ path: cur, label: labels[i], levelsUp: i })
+    const parent = path.dirname(cur)
+    if (parent === cur) break
+    cur = parent
+  }
+  return candidates
+}
+
+function runDetect() {
+  const cwd = process.cwd()
+  const gitRoot = tryExec('git rev-parse --show-toplevel')
+  if (!gitRoot) {
+    emit({
+      status: 'no-git-repo',
+      message: 'The current directory is not inside a git repository. .siesa-project resolution relies on walking up from a git-tracked sub-repo, so initializing here is unlikely to help.',
+      cwd,
+    })
+    process.exit(2)
+  }
+
+  const remoteUrl = tryExec('git remote get-url origin')
+  const remoteParsed = parseRemote(remoteUrl)
+  const repoName = remoteParsed ? remoteParsed.repo : null
+
+  const existing = findExistingSiesaProject(gitRoot)
+  if (existing) {
+    emit({
+      status: 'already-configured',
+      message: 'A .siesa-project file already exists above this repo. sa-emit.js will use it as-is.',
+      git_root: gitRoot,
+      remote_url: remoteUrl,
+      existing_siesa_project: existing,
+    })
+    process.exit(2)
+  }
+
+  if (!remoteUrl) {
+    emit({
+      status: 'no-remote',
+      message: 'This repo has no `origin` remote. Without it sa-emit.js falls back to "unknown" — set up a remote or pass --slug to write a .siesa-project manually.',
+      git_root: gitRoot,
+    })
+    process.exit(2)
+  }
+
+  const derived = deriveLogicalSlug(repoName)
+
+  if (!derived.matched) {
+    emit({
+      status: 'single-repo',
+      message: 'This repo name does not match the multi-repo convention (no docs|backend|frontend segment). sa-emit.js will report project_id based on the git remote, which is already unambiguous for single-repo projects. No .siesa-project is required.',
+      git_root: gitRoot,
+      remote_url: remoteUrl,
+      remote_repo: repoName,
+      fallback_project_id: remoteParsed ? `${remoteParsed.org}/${remoteParsed.repo}` : null,
+    })
+    process.exit(2)
+  }
+
+  const candidates = listParentCandidates(gitRoot)
+  // For the multi-repo convention the typical layout is:
+  //   <parent>/docs/         (git remote: business-pos-docs-pdv)
+  //   <parent>/apps/backend/ (git remote: business-pos-backend-pdv)
+  //   <parent>/apps/frontend/(git remote: business-pos-frontend-pdv)
+  // The git root for backend/frontend sits 2 levels under <parent>; for docs it sits 1 level
+  // under. We surface both as the recommended choice and let the user pick.
+  const recommendedLevels = derived.role === 'docs' ? 1 : 2
+  const recommended = candidates.find(c => c.levelsUp === recommendedLevels) || candidates[candidates.length - 1]
+
+  emit({
+    status: 'ready',
+    message: 'Multi-repo convention detected. Pick the parent directory that contains every sub-repo of this logical project, then re-run with --write.',
+    git_root: gitRoot,
+    remote_url: remoteUrl,
+    remote_repo: repoName,
+    convention_match: true,
+    proposed_slug: derived.slug,
+    convention_breakdown: {
+      module: derived.module,
+      role: derived.role,
+      rest: derived.rest,
+    },
+    parent_candidates: candidates,
+    recommended_dir: recommended.path,
+    next_step_example: `node sa-init-project.js --write --slug "${derived.slug}" --dir "${recommended.path}"`,
+  })
+  process.exit(0)
+}
+
+function runWrite(args) {
+  const slug = args['slug']
+  const dir = args['dir']
+  const force = Boolean(args['force'])
+
+  if (!slug || typeof slug !== 'string') {
+    console.error('Error: --slug "<value>" is required for --write')
+    process.exit(1)
+  }
+  if (!dir || typeof dir !== 'string') {
+    console.error('Error: --dir "<path>" is required for --write')
+    process.exit(1)
+  }
+
+  const normalizedSlug = slug.trim()
+  if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(normalizedSlug)) {
+    console.error(`Error: slug "${normalizedSlug}" must be lowercase letters, digits and dashes (e.g. "pos-pdv"). No spaces, no uppercase, no leading/trailing dash.`)
+    process.exit(1)
+  }
+
+  const resolvedDir = path.resolve(dir)
+  if (!fs.existsSync(resolvedDir) || !fs.statSync(resolvedDir).isDirectory()) {
+    console.error(`Error: directory does not exist: ${resolvedDir}`)
+    process.exit(3)
+  }
+
+  const target = path.join(resolvedDir, '.siesa-project')
+  if (fs.existsSync(target) && !force) {
+    let current = null
+    try { current = fs.readFileSync(target, 'utf8').split(/\r?\n/)[0].trim() } catch (_) {}
+    emit({
+      status: 'exists',
+      message: '.siesa-project already exists at this location. Pass --force to overwrite.',
+      path: target,
+      current_value: current,
+      requested_slug: normalizedSlug,
+    })
+    process.exit(3)
+  }
+
+  try {
+    fs.writeFileSync(target, normalizedSlug + '\n', { encoding: 'utf8' })
+  } catch (err) {
+    emit({ status: 'error', message: `Failed to write ${target}: ${err.message}` })
+    process.exit(3)
+  }
+
+  emit({
+    status: 'written',
+    message: `Wrote ${target}. sa-emit.js will now report project_id="${normalizedSlug}" from anywhere inside ${resolvedDir}.`,
+    path: target,
+    slug: normalizedSlug,
+    parent_dir: resolvedDir,
+  })
+  process.exit(0)
+}
+
+const args = parseArgs(process.argv.slice(2))
+
+if (args['write']) {
+  runWrite(args)
+} else {
+  // --detect is the default mode. Treat any other invocation as a detection request.
+  runDetect()
+}

package/siesa-agents/resources/architecture/architecture-both.md

@@ -1,6 +1,8 @@
 ---
 type: base-architecture
 status: base
+stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]
+lastStep: 8
 note: >
   This document was automatically generated during siesa-agents installation.
   It represents the Siesa corporate base architecture applicable to all microservices.
@@ -151,33 +153,35 @@ builder.Services.AddHealthChecks();                    // 9. Health Checks
 ## 3. Solution Structure (Backend)
 
 ```
-src/
-├── {Service}.API/              # Presentation Layer — Minimal API Endpoints
-│   ├── Endpoints/
-│   │   └── {Feature}/         # Endpoint classes per feature
-│   ├── Middleware/
-│   └── Program.cs
-├── {Service}.Application/      # Application Layer — CQRS, DTOs, Validators
-│   └── {Feature}/
-│       ├── Commands/
-│       ├── Queries/
-│       ├── DTOs/
-│       ├── Validators/
-│       └── Interfaces/
-├── {Service}.Domain/           # Domain Layer — Entities, Value Objects, Events
-│   └── {Feature}/
-│       ├── Entities/
-│       ├── ValueObjects/
-│       └── Events/
-└── {Service}.Infrastructure/   # Infrastructure Layer — EF Core, Repositories
-    ├── Data/
-    │   ├── Configurations/
-    │   ├── Migrations/
-    │   └── {Service}DbContext.cs
-    └── Repositories/
-tests/
-├── {Service}.UnitTests/        # xUnit + EF Core InMemory
-└── {Service}.IntegrationTests/ # xUnit + Testcontainers.PostgreSql
+apps/
+└── backend/
+    ├── src/
+    │   ├── {Service}.API/              # Presentation Layer — Minimal API Endpoints
+    │   │   ├── Endpoints/
+    │   │   │   └── {Feature}/         # Endpoint classes per feature
+    │   │   ├── Middleware/
+    │   │   └── Program.cs
+    │   ├── {Service}.Application/      # Application Layer — CQRS, DTOs, Validators
+    │   │   └── {Feature}/
+    │   │       ├── Commands/
+    │   │       ├── Queries/
+    │   │       ├── DTOs/
+    │   │       ├── Validators/
+    │   │       └── Interfaces/
+    │   ├── {Service}.Domain/           # Domain Layer — Entities, Value Objects, Events
+    │   │   └── {Feature}/
+    │   │       ├── Entities/
+    │   │       ├── ValueObjects/
+    │   │       └── Events/
+    │   └── {Service}.Infrastructure/   # Infrastructure Layer — EF Core, Repositories
+    │       ├── Data/
+    │       │   ├── Configurations/
+    │       │   ├── Migrations/
+    │       │   └── {Service}DbContext.cs
+    │       └── Repositories/
+    └── tests/
+        ├── {Service}.UnitTests/        # xUnit + EF Core InMemory
+        └── {Service}.IntegrationTests/ # xUnit + Testcontainers.PostgreSql
 ```
 
 ---
@@ -187,37 +191,39 @@ tests/
 ### 4.1 Folder Structure
 
 ```
-src/
-├── main.tsx
-├── router.tsx
-├── routeTree.gen.ts            # Auto-generated by TanStack Router
-├── globals.css
-├── routes/                     # TanStack Router — file-based routing
-│   ├── __root.tsx              # Root layout
-│   ├── index.tsx
-│   ├── _auth.tsx               # Pathless layout
-│   ├── _auth/login.tsx
-│   ├── _app.tsx                # Protected layout
-│   └── _app/{module}/*
-├── modules/                    # DDD business modules
-│   └── {module}/
-│       ├── domain/             # Entities, repository interfaces, types
-│       ├── application/        # Use-cases, hooks, store
-│       ├── infrastructure/     # Repository impl, api, adapters
-│       └── presentation/       # Components
-├── shared/                     # Reusable code
-│   ├── components/             # UI components, shadcn/ui
-│   ├── hooks/
-│   ├── lib/                    # Utilities, api-client
-│   ├── types/
-│   └── constants/
-├── app/                        # Global configuration
-│   ├── providers/
-│   └── store/
-└── infrastructure/             # Global external services
-    ├── api/
-    ├── storage/
-    └── pwa/
+apps/
+└── frontend/
+    └── src/
+        ├── main.tsx
+        ├── router.tsx
+        ├── routeTree.gen.ts            # Auto-generated by TanStack Router
+        ├── globals.css
+        ├── routes/                     # TanStack Router — file-based routing
+        │   ├── __root.tsx              # Root layout
+        │   ├── index.tsx
+        │   ├── _auth.tsx               # Pathless layout
+        │   ├── _auth/login.tsx
+        │   ├── _app.tsx                # Protected layout
+        │   └── _app/{module}/*
+        ├── modules/                    # DDD business modules
+        │   └── {module}/
+        │       ├── domain/             # Entities, repository interfaces, types
+        │       ├── application/        # Use-cases, hooks, store
+        │       ├── infrastructure/     # Repository impl, api, adapters
+        │       └── presentation/       # Components
+        ├── shared/                     # Reusable code
+        │   ├── components/             # UI components, shadcn/ui
+        │   ├── hooks/
+        │   ├── lib/                    # Utilities, api-client
+        │   ├── types/
+        │   └── constants/
+        ├── app/                        # Global configuration
+        │   ├── providers/
+        │   └── store/
+        └── infrastructure/             # Global external services
+            ├── api/
+            ├── storage/
+            └── pwa/
 ```
 
 ### 4.2 TanStack Router — File Conventions