siesa-agents 2.1.79 → 2.1.80

package/claude/skills/sa-init-observability/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: sa-init-observability
+description: 'Initialize a `.siesa-project` file that consolidates observability metrics across multi-repo logical projects (docs/backend/frontend sub-repos cloned side by side). Use whenever the user wants to set up observability for a new project, mentions `.siesa-project`, asks how to consolidate fragmented `project_id` values in GCP, sees metrics split across `business-*-docs-*`/`business-*-backend-*`/`business-*-frontend-*` repos, or starts working in a project that follows the multi-repo convention. Run this once per logical project, before workflows emit telemetry, so `sa-emit.js` reports a unified `project_id` instead of one per sub-repo.'
+---
+
+# Init Observability — `.siesa-project` Setup
+
+**Goal:** Create a `.siesa-project` file in the correct parent directory so `sa-emit.js` reports a single, stable `project_id` for every workflow that runs inside any sub-repo of the same logical project.
+
+**When this matters:** Projects following the Siesa multi-repo convention split docs, backend and frontend into separate GitHub repos (`business-pos-docs-pdv`, `business-pos-backend-pdv`, `business-pos-frontend-pdv`). Without `.siesa-project`, `sa-emit.js` falls back to `git remote get-url origin` and emits three different `project_id` values for what is conceptually one project. That fragments dashboards in GCP and inflates per-engineer epic counts because the same epic gets counted once per sub-repo it touches.
+
+## When to use this skill
+
+Trigger immediately when the user:
+
+- Says "initialize observability", "set up observability", "init `.siesa-project`", or "configure metrics" for a project
+- Mentions that GCP shows the same engineer/epic across multiple `business-*-docs-*` / `business-*-backend-*` / `business-*-frontend-*` rows
+- Asks how to make several sub-repos report under one logical project name
+- Has just cloned a multi-repo project (e.g. `docs/` + `apps/backend/` + `apps/frontend/`) and is about to run BMAD workflows that emit telemetry
+- References the `.siesa-project` file by name
+
+Do **not** trigger for: editing existing skills, changing OTLP endpoints, debugging a specific event payload (that is `sa-emit.js` territory), or anything unrelated to the `.siesa-project` mechanism.
+
+## Prerequisites
+
+- The user is sitting inside a git repository that belongs to a logical Siesa project (typically a clone of `business-*-{docs|backend|frontend}-*`).
+- Node.js is on the PATH (the scripts are invoked via `node`).
+- Two helper scripts live in the observability scripts dir and are mirrored to the npm copy:
+  - `sa-init-env.js` — ensures `~/.claude/observability/.env` has the OTLP variables sa-emit needs.
+  - `sa-init-project.js` — detects the multi-repo convention and writes `.siesa-project`.
+- Source-of-truth path is `_siesa-agents/observability/scripts/`; the npm mirror is `siesa-agents/observability/scripts/`. Prefer the source-of-truth path when both exist.
+
+If a script is missing, stop and tell the user — do not improvise the logic inline. The scripts are the authoritative source for slug derivation and env scaffolding.
+
+## Workflow
+
+The skill is a three-step orchestration: **ensure global env → detect → write**. Step 0 is idempotent and almost always silent. Steps 1 and 2 do the real work for the `.siesa-project` file.
+
+### Step 0 — Ensure global env
+
+Run `sa-init-env.js` first, every time the skill is invoked:
+
+```bash
+node <observability-scripts>/sa-init-env.js
+```
+
+The script verifies that `~/.claude/observability/.env` exists and declares both `SA_OTLP_ENDPOINT` and `SA_OTLP_HEADERS`. It does **not** modify `sa-emit.js` and does **not** copy values from any project `.env` — it only seeds clearly-fake placeholders that the user must replace before workflows emit real telemetry.
+
+Parse the JSON `status` field:
+
+- **`status: "already-configured"`** — Both variables are already present. Do not mention this to the user unless they explicitly asked about env setup; it is the silent happy path. Continue to Step 1.
+- **`status: "created"`** — The file did not exist; the script wrote a fresh template at `env_path`. Tell the user once: "Created `~/.claude/observability/.env` with placeholder values. Edit it with your real OTLP endpoint and headers before running workflows that emit telemetry." Then continue to Step 1.
+- **`status: "updated"`** — The file existed but was missing one of the two variables; placeholders were appended for `appended_vars`. Tell the user which vars were added and remind them to replace the placeholders. Continue to Step 1.
+- **`status: "error"`** — Surface the error verbatim and stop. Do not proceed to Step 1 — if the env scaffolding is broken, the project-level setup is the wrong place to spend the user's attention.
+
+The placeholders the script writes are intentionally bogus (`https://your-otel-collector.example.com`, `Authorization=Bearer YOUR_TOKEN_HERE`). They will not connect to anything. The user is expected to receive real values from the observability team and paste them in.
+
+### Step 1 — Detect
+
+Run `sa-init-project.js` from the user's current directory (or from any directory inside the target sub-repo if the user told you where they want to initialize):
+
+```bash
+node <observability-scripts>/sa-init-project.js --detect
+```
+
+Parse the JSON object printed to stdout. The `status` field selects the next branch.
+
+**`status: "ready"`** — Multi-repo convention detected. The JSON contains everything needed to act:
+
+- `proposed_slug` — the logical project name to write (e.g. `pos-pdv`)
+- `recommended_dir` — the parent directory chosen by the script (1 level up for `docs` clones, 2 levels up for `backend`/`frontend` clones)
+- `convention_breakdown` — how the slug was derived (`module`, `role`, `rest`)
+
+Proceed straight to Step 2 with `proposed_slug` and `recommended_dir`. Do **not** ask the user to confirm — the user has already accepted the auto-detection policy by invoking this skill.
+
+**`status: "single-repo"`** — The repo name has no `docs`/`backend`/`frontend` segment, so the git remote already produces an unambiguous `project_id`. Stop and tell the user no `.siesa-project` is needed (mention the `fallback_project_id` value so they know what GCP will see). Do not write anything. If they later say "no, write one anyway with slug X", run Step 2 with that explicit slug and the directory they specify.
+
+**`status: "already-configured"`** — A `.siesa-project` exists above the current git root. Stop and report `existing_siesa_project.path` and `existing_siesa_project.value` to the user. Do not overwrite implicitly. If the user replies that they want it changed, run `--write` with `--force`, the new slug, and the same directory.
+
+**`status: "no-git-repo"`** — The cwd is not inside a git repo. Tell the user to `cd` into the clone they want to initialize and re-run. Do not invent a directory.
+
+**`status: "no-remote"`** — Git repo without an `origin` remote. Stop and ask the user for a slug + directory before proceeding, since the script has no signal to auto-derive a name.
+
+### Step 2 — Write
+
+When `status == "ready"`, run write immediately with the values from the detect output — no user prompt in between:
+
+```bash
+node <observability-scripts>/sa-init-project.js --write --slug "<proposed_slug>" --dir "<recommended_dir>"
+```
+
+Parse the JSON response:
+
+- **`status: "written"`** — Success. Report a single concise line to the user: the absolute `path` and the slug that was written. Optionally suggest the verification command from Step 3.
+- **`status: "exists"`** — A file is already there with a different value (the detect step missed it because the user pointed at a non-default dir, or a race). Show `current_value` vs `requested_slug` and ask the user whether to overwrite. If yes, re-run with `--force`.
+- **`status: "error"`** — Surface the error message verbatim and stop.
+
+For the `single-repo`, `already-configured` and `no-remote` branches where the user explicitly opts into writing, gather slug + directory inline and run the same `--write` command.
+
+### Step 3 — Verify (optional)
+
+Suggest the user run a quick sanity check from any sub-repo of the project:
+
+```bash
+node <observability-scripts>/sa-emit.js --event workflow.started --story "0-verify" --phase create-story 2>&1 | grep project_id
+```
+
+If the buffered event shows `project_id=<confirmed-slug>`, the consolidation works. If it still shows the git-remote-derived value, the user is running from a directory that is **not** a descendant of the chosen parent — point them at the right cwd.
+
+## Edge cases
+
+- **Nested logical projects.** If the user runs the skill inside a directory that is already under an existing `.siesa-project`, the script reports `already-configured`. Do not stack `.siesa-project` files — the lowest one wins during walk-up, which can silently mask the consolidation.
+- **Slugs with dots, underscores or uppercase.** The script rejects them. Stick to lowercase + dashes (`pos-pdv`, `finance-billing`). If the user pushes back, explain that GCP labels work best with kebab-case and that other Siesa scripts assume this shape.
+- **Convention without `business-` prefix.** The parser handles both `business-pos-backend-pdv` and a hypothetical `pos-backend-pdv` — both produce `pos-pdv`. Future modules (`finance-*`, `hcm-*`) work without any code change.
+- **Parent dir that is itself a git repo.** Sometimes the docs repo *is* the logical parent (e.g. `comercial/` is a git repo and `comercial/apps/{backend,frontend}/` are clones inside it). That is fine — writing `.siesa-project` in `comercial/` will (a) commit-able in the docs repo, and (b) walked up correctly by `sa-emit.js` from `comercial/apps/backend/`. Mention this to the user so they can decide whether to commit the file (recommended, since it documents the convention for teammates).
+- **Windows path separators.** The script uses `path.join`, so output paths may contain backslashes. Treat them as opaque and pass them back to `--write --dir` verbatim.
+
+## Convention reference
+
+The Siesa multi-repo naming convention is:
+
+```
+business-<module>-<role>-<rest>
+        └ org prefix
+              └ logical module (pos, finance, hcm, …)
+                    └ role: docs | backend | frontend
+                          └ project-specific suffix (pdv, tomapedido, billing, …)
+```
+
+The logical slug collapses `<role>` away: `business-pos-backend-pdv` → `pos-pdv`.
+
+For repo names that do not contain `docs`/`backend`/`frontend`, the script returns `single-repo` and no `.siesa-project` is needed.
+
+## Examples
+
+**Example 1 — Happy path on a `pos-pdv` clone (env already configured)**
+
+```
+User: I just cloned business-pos-backend-pdv into comercial/apps/backend. Set up observability.
+Model: <runs sa-init-env.js — status "already-configured", silent>
+       <runs sa-init-project.js --detect from comercial/apps/backend/>
+       <reads proposed_slug="pos-pdv", recommended_dir=C:\…\comercial>
+       <runs --write --slug pos-pdv --dir C:\…\comercial without asking>
+       Wrote C:\…\comercial\.siesa-project. sa-emit.js will now report project_id="pos-pdv".
+```
+
+**Example 1b — Same flow on a fresh machine (env missing)**
+
+```
+User: Set up observability for this clone.
+Model: <runs sa-init-env.js — status "created">
+       Created ~/.claude/observability/.env with placeholder values. Edit it with your real OTLP endpoint and headers before running workflows that emit telemetry.
+       <continues with detect + write as in Example 1>
+```
+
+**Example 2 — Single-repo project**
+
+```
+User: Set up .siesa-project for Siesa-Agents.
+Model: <runs --detect from Siesa-Agents/>
+       Repo name "Siesa-Agents" has no docs/backend/frontend segment, so the git remote already produces an unambiguous project_id ("SiesaTeams/Siesa-Agents"). No .siesa-project is needed.
+       Want to set a custom slug anyway?
+User: no, thanks
+Model: Nothing written. Existing fallback (SiesaTeams/Siesa-Agents) will continue to be reported.
+```
+
+**Example 3 — Already configured**
+
+```
+User: Init observability here.
+Model: <runs --detect>
+       A .siesa-project already exists at C:\…\comercial\.siesa-project with value "pos-pdv". sa-emit.js is already consolidating under that slug. No action needed unless you want to change the value.
+```
+
+## Reminders
+
+- Step 0 (`sa-init-env.js`) always runs first and is idempotent. Skip the user-facing message when its status is `already-configured`; surface it only on `created` / `updated` / `error`.
+- On `status: "ready"` from `sa-init-project.js --detect`, write immediately using `proposed_slug` and `recommended_dir` — no confirmation prompt. The user invoked this skill knowing it auto-creates the file.
+- Never invent a slug. If the detect step returns `single-repo`, `no-remote`, or any branch other than `ready`, stop and let the user drive the next decision.
+- Never call `--write --force` automatically. Overwriting an existing `.siesa-project` always requires an explicit user request.
+- Do not modify `sa-emit.js` or other observability scripts from this skill — its only side effects are (a) creating `~/.claude/observability/.env` with placeholders if absent and (b) creating or overwriting (with consent) a single `.siesa-project` file.
+- The scripts' JSON output is the contract. If a future field appears (e.g. an extra status), surface it to the user rather than guessing what it means.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.79",
+  "version": "2.1.80",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {

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()
+}