create-junando-app 0.7.3

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,23 @@
+# create-junando-app
+
+Scaffold a new [Junando](https://github.com/GerMoren/junando) alerting app in seconds. This package copies the `express-end-to-end` template into a new directory and wires up your project name — no configuration files to touch, no boilerplate to delete.
+
+## Usage
+
+```bash
+pnpm create junando-app my-app
+# or
+npx create-junando-app my-app
+```
+
+After scaffolding:
+
+```bash
+cd my-app/app
+cp .env.example .env  # edit with your LLM/Slack keys
+pnpm dev
+```
+
+## What's next
+
+See `my-app/app/README.md` (or the [example README](../../examples/express-end-to-end/README.md)) for a full walkthrough of what gets scaffolded, environment variables, and how to connect your LLM and Slack integrations.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { existsSync, readFileSync } from "fs";
+import { basename } from "path";
+import { fileURLToPath } from "url";
+
+// src/helpers/parse-args.ts
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let projectName2;
+  let help = false;
+  let version = false;
+  let unknownFlag;
+  for (const arg of args) {
+    if (arg === "--help" || arg === "-h") {
+      help = true;
+    } else if (arg === "--version" || arg === "-v") {
+      version = true;
+    } else if (arg.startsWith("-")) {
+      unknownFlag = arg;
+    } else if (projectName2 === void 0) {
+      projectName2 = arg;
+    }
+  }
+  return { projectName: projectName2, help, version, unknownFlag };
+}
+
+// src/helpers/validate-name.ts
+function isValidProjectName(name) {
+  return /^[a-z0-9][a-z0-9._-]*$/i.test(name);
+}
+
+// src/scaffold.ts
+import { cp, readdir, rename, access, copyFile } from "fs/promises";
+import { join } from "path";
+import { spawn } from "child_process";
+
+// src/helpers/rewrite-package-json.ts
+import { readFile, writeFile } from "fs/promises";
+async function rewritePackageJson(path, mutate) {
+  const raw = await readFile(path, "utf-8");
+  const pkg2 = JSON.parse(raw);
+  const updated = mutate(pkg2);
+  await writeFile(path, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+}
+
+// src/scaffold.ts
+async function scaffold({
+  targetDir: targetDir2,
+  projectName: projectName2,
+  templateDir: templateDir2,
+  skipInstall = false
+}) {
+  let entries = [];
+  try {
+    entries = await readdir(targetDir2);
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") {
+      throw err;
+    }
+  }
+  if (entries.length > 0) {
+    throw new Error(
+      `Target directory "${targetDir2}" already exists and is non-empty. Remove it first or choose a different name.`
+    );
+  }
+  await cp(templateDir2, targetDir2, { recursive: true });
+  const renamedGitignore = join(targetDir2, "app", "_gitignore");
+  try {
+    await access(renamedGitignore);
+    await rename(renamedGitignore, join(targetDir2, "app", ".gitignore"));
+  } catch {
+  }
+  const envExample = join(targetDir2, "app", ".env.example");
+  const envFile = join(targetDir2, "app", ".env");
+  try {
+    await access(envExample);
+    let envExists = false;
+    try {
+      await access(envFile);
+      envExists = true;
+    } catch {
+    }
+    if (!envExists) {
+      await copyFile(envExample, envFile);
+    }
+  } catch {
+  }
+  const pkgPath = join(targetDir2, "app", "package.json");
+  await rewritePackageJson(pkgPath, (pkg2) => ({ ...pkg2, name: projectName2 }));
+  if (!skipInstall) {
+    await runPnpmInstall(join(targetDir2, "app"));
+  }
+}
+function runPnpmInstall(cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("pnpm", ["install"], { cwd, stdio: "inherit", shell: false });
+    child.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        reject(new Error("pnpm not found on PATH. Install pnpm (https://pnpm.io/installation) and try again."));
+      } else {
+        reject(err);
+      }
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`pnpm install exited with code ${String(code)}`));
+      }
+    });
+  });
+}
+
+// src/helpers/next-steps.ts
+var RESET = "\x1B[0m";
+var BOLD = "\x1B[1m";
+var GREEN = "\x1B[32m";
+var CYAN = "\x1B[36m";
+function buildNextStepsMessage(targetDir2) {
+  return [
+    "",
+    `${GREEN}${BOLD}\u2714 Scaffolded ${targetDir2} successfully!${RESET}`,
+    "",
+    `${BOLD}Next steps:${RESET}`,
+    `  ${CYAN}cd ${targetDir2}/app${RESET}`,
+    `  ${CYAN}pnpm dev${RESET}`,
+    "",
+    `Your ${CYAN}.env${RESET} was created from ${CYAN}.env.example${RESET} with placeholder values.`,
+    `Edit it with your real LLM/Slack keys when you wire the full pipeline.`,
+    "",
+    `See ${targetDir2}/app/README.md for more details.`,
+    ""
+  ].join("\n");
+}
+
+// src/cli.ts
+var pkgUrl = new URL("../package.json", import.meta.url);
+var pkg = JSON.parse(readFileSync(fileURLToPath(pkgUrl), "utf8"));
+var VERSION = pkg.version;
+var USAGE = `
+Usage:
+  pnpm create junando-app <project-name>
+  npx create-junando-app <project-name>
+
+Arguments:
+  project-name    Name of the new project directory
+
+Options:
+  --help, -h      Show this help message
+  --version, -v   Show version number
+`.trim();
+var RED = "\x1B[31m";
+var RESET2 = "\x1B[0m";
+function die(msg) {
+  process.stderr.write(`${RED}Error: ${msg}${RESET2}
+`);
+  process.exit(1);
+}
+var parsed = parseArgs(process.argv);
+if (parsed.help) {
+  console.log(USAGE);
+  process.exit(0);
+}
+if (parsed.version) {
+  console.log(VERSION);
+  process.exit(0);
+}
+if (parsed.unknownFlag !== void 0) {
+  die(`Unknown flag: ${parsed.unknownFlag}
+
+${USAGE}`);
+}
+if (parsed.projectName === void 0) {
+  process.stderr.write(USAGE + "\n");
+  process.exit(1);
+}
+var targetDir = parsed.projectName;
+var projectName = basename(targetDir);
+if (targetDir.split(/[\\/]/).includes("..")) {
+  die(`Target path "${targetDir}" must not contain ".." segments.`);
+}
+if (!isValidProjectName(projectName)) {
+  die(
+    `Invalid project name "${projectName}". Use letters, digits, dots, hyphens, or underscores; must start with a letter or digit.`
+  );
+}
+var templateDirUrl = new URL("../template/", import.meta.url);
+var templateDir = fileURLToPath(templateDirUrl);
+if (!existsSync(templateDir)) {
+  die(
+    `Template directory not found at ${templateDir}. This is likely a broken install \u2014 try reinstalling create-junando-app.`
+  );
+}
+(async () => {
+  try {
+    await scaffold({ targetDir, projectName, templateDir });
+    process.stdout.write(buildNextStepsMessage(targetDir));
+  } catch (err) {
+    die(err instanceof Error ? err.message : String(err));
+  }
+})();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "create-junando-app",
+  "version": "0.7.3",
+  "description": "Scaffold a new Junando alerting app from the express-end-to-end template",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "create-junando-app": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "types": "./dist/cli.d.ts",
+  "files": [
+    "dist",
+    "template",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GerMoren/junando.git",
+    "directory": "packages/create-junando-app"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "prebuild": "node scripts/sync-template.js",
+    "build": "tsup src/cli.ts --format esm --dts --tsconfig tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist template"
+  }
+}

package/template/README.md

@@ -0,0 +1,139 @@
+# Express end-to-end example
+
+> **This example is the template used by `create-junando-app`. Changes here ship to new users on next release.**
+
+The canonical Junando demo. A broken Express endpoint triggers a Prometheus alert, Alertmanager forwards it to Junando, Junando asks an LLM for a structured diagnosis, and the result lands in Slack with the original `correlationId` intact.
+
+```
+demo-app (Express)
+  └─ /api/checkout always returns 500 + logs an error with correlationId
+       └─ Prometheus scrapes http_errors_total
+            └─ Alert rule CheckoutEndpointFailing fires
+                 └─ Alertmanager posts to junando-webhook
+                      └─ Junando builds a cluster, asks the LLM, and notifies Slack
+```
+
+Total time to first Slack message: about 5 minutes including filling in credentials.
+
+---
+
+## Prerequisites
+
+- Docker + Docker Compose
+- A Slack bot token (or a Microsoft Teams Power Automate webhook — see `.env.example`)
+- An LLM API key (Qwen, Claude, Gemini, or OpenRouter)
+
+That is it. You do not need to clone the Junando monorepo or build any package — the example uses the published `ghcr.io/germoren/junando-webhook:latest` image by default.
+
+---
+
+## Run it
+
+```bash
+cd examples/express-end-to-end
+
+cp .env.example .env
+# edit .env and fill in LLM_API_KEY, SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET, SLACK_CHANNEL
+
+docker compose up -d
+./scripts/simulate.sh
+```
+
+Within ~30 seconds you should see a Slack message in the channel you configured. It will contain:
+
+- The probable cause as inferred by the LLM
+- Recommended next steps
+- A link to the runbook declared in `prometheus/rules.yml`
+- The `correlationId` from the first failing request, so you can pivot to logs
+
+Tear down:
+
+```bash
+docker compose down -v
+```
+
+---
+
+## What is happening behind the scenes
+
+### `demo-app`
+
+A 60-line Express app at `app/src/server.js`. The only thing worth pointing out is the **correlationId middleware**: every request gets a UUID (or reuses an incoming `x-correlation-id` header). That id is attached to every pino log line and surfaces in the 500 response body. Real apps should do the same so a single incident is greppable across logs, metrics, and incident summaries.
+
+### Prometheus
+
+Scrapes `demo-app:3001/metrics` every 5 seconds. The rule in `docker/prometheus/rules.yml` watches `http_errors_total{route="/api/checkout"}` and fires `CheckoutEndpointFailing` when the rate exceeds zero for 15 seconds.
+
+### Alertmanager
+
+Single route, single receiver: it forwards every alert to `http://junando-webhook:4000/webhook/alert`. The `send_resolved: true` flag means Junando also receives the resolution event when the alert clears.
+
+### Junando webhook
+
+The published `ghcr.io/germoren/junando-webhook` image. It deduplicates against Redis (TTL 5 min by default), clusters related alerts (120 s window), pulls representative log context from Loki when available, and sends the cluster to your configured LLM. The LLM response is mapped to a Slack Block Kit message and posted to `SLACK_CHANNEL`.
+
+---
+
+## Inspect each step
+
+| URL                              | What to look at                                       |
+|----------------------------------|-------------------------------------------------------|
+| http://localhost:3001/health     | Demo app health                                       |
+| http://localhost:3001/metrics    | Raw Prometheus metrics including `http_errors_total`  |
+| http://localhost:9090/alerts     | Prometheus alert state (PENDING → FIRING)             |
+| http://localhost:9093/#/alerts   | Alertmanager queue and grouping                       |
+| http://localhost:4000/health     | Junando webhook health                                |
+
+Logs:
+
+```bash
+docker compose logs -f demo-app          # see the failing requests + correlationIds
+docker compose logs -f junando-webhook   # see the cluster build, LLM call, Slack post
+```
+
+---
+
+## Swap notifier to Microsoft Teams
+
+In `.env`:
+
+```bash
+NOTIFIER_TYPE=teams
+TEAMS_WEBHOOK_URL=https://prod-XX.westus.logic.azure.com/workflows/.../invoke?api-version=2024-10-01&sp=...
+```
+
+Comment out the three `SLACK_*` variables. Restart:
+
+```bash
+docker compose up -d junando-webhook
+```
+
+Junando posts an Adaptive Card to your Power Automate workflow. The rest of the pipeline is identical.
+
+---
+
+## Contributor mode (build webhook from source)
+
+If you are working on `@junando/core` or `@junando/webhook` and want this example to reflect your local changes:
+
+```bash
+docker compose --profile dev up -d --build
+```
+
+This builds the webhook from `docker/Dockerfile.webhook` at the repo root instead of pulling the published image. Everything else is unchanged.
+
+---
+
+## Troubleshooting
+
+**No Slack message after 1 minute.**
+Check the Junando logs (`docker compose logs junando-webhook`). The most common causes are an invalid `SLACK_BOT_TOKEN`, a channel the bot is not invited to, or the LLM provider returning an error (the log line will say so).
+
+**Alertmanager says `dial tcp: lookup junando-webhook: no such host`.**
+This means alertmanager and junando-webhook are not in the same Compose network. Make sure you ran `docker compose up` from this directory, not from the repo root.
+
+**Prometheus alert never fires.**
+Hit `/api/checkout` manually a few times (`curl http://localhost:3001/api/checkout`) and watch http://localhost:9090/alerts. If `http_errors_total` is incrementing but the alert stays GREEN, the scrape may not have caught up yet — wait 15 more seconds.
+
+**The LLM call times out.**
+Some free-tier providers throttle aggressively. Switch `LLM_PROVIDER` to `openrouter` and use a paid model, or set `LLM_FALLBACK_MODELS` to a comma-separated list of free models.

package/template/app/.env.example

@@ -0,0 +1,29 @@
+# --- LLM (required) ---
+# Pick one provider and set the matching API key.
+LLM_PROVIDER=qwen
+LLM_API_KEY=replace-me
+LLM_MODEL=
+
+# --- Notifier (Slack) ---
+NOTIFIER_TYPE=slack
+SLACK_BOT_TOKEN=xoxb-replace-me
+SLACK_SIGNING_SECRET=replace-me
+SLACK_CHANNEL=#alerts
+
+# To swap to Microsoft Teams, comment the three SLACK_* lines above and set:
+#   NOTIFIER_TYPE=teams
+#   TEAMS_WEBHOOK_URL=https://prod-XX.westus.logic.azure.com/workflows/.../invoke?api-version=2024-10-01&sp=...
+
+# --- Infra (do not change for the example) ---
+REDIS_URL=redis://redis:6379
+LOKI_URL=http://loki:3100
+SQS_QUEUE_URL=
+APP_URL=http://localhost:4000
+
+# --- Tunables ---
+DEDUP_TTL_SECONDS=300
+CLUSTER_WINDOW_MS=120000
+
+# --- General ---
+NODE_ENV=development
+LOG_LEVEL=info

package/template/app/.nvmrc

@@ -0,0 +1 @@
+24

package/template/app/Dockerfile

@@ -0,0 +1,7 @@
+FROM node:24-alpine
+WORKDIR /app
+COPY package.json ./
+RUN npm install --omit=dev
+COPY src ./src
+EXPOSE 3001
+CMD ["node", "src/server.js"]

package/template/app/_gitignore

@@ -0,0 +1,2 @@
+.env
+node_modules/

package/template/app/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "express-end-to-end-example",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Canonical end-to-end Junando example: Express app -> Prometheus -> Alertmanager -> Junando -> Slack",
+  "scripts": {
+    "start": "node --env-file=.env src/server.js",
+    "dev": "node --env-file=.env --watch src/server.js"
+  },
+  "dependencies": {
+    "express": "^4.21.0",
+    "pino": "^9.5.0",
+    "pino-http": "^10.3.0",
+    "prom-client": "^15.1.3"
+  }
+}

package/template/app/src/server.js

@@ -0,0 +1,80 @@
+import express from "express";
+import client from "prom-client";
+import pinoHttp from "pino-http";
+import { randomUUID } from "node:crypto";
+import pino from "pino";
+
+const log = pino({ level: process.env.LOG_LEVEL ?? "info" });
+const app = express();
+
+// --- correlationId middleware ----------------------------------------------
+// Propagates an incoming x-correlation-id header or generates one. Every log
+// line, every metric label, and every error response carries this id so that
+// a single incident is traceable end-to-end from app -> Prom -> Junando -> Slack.
+app.use((req, res, next) => {
+  const id = req.header("x-correlation-id") ?? randomUUID();
+  req.correlationId = id;
+  res.setHeader("x-correlation-id", id);
+  next();
+});
+
+app.use(
+  pinoHttp({
+    logger: log,
+    customProps: (req) => ({ correlationId: req.correlationId }),
+  }),
+);
+
+// --- Prometheus metrics ----------------------------------------------------
+const register = new client.Registry();
+client.collectDefaultMetrics({ register });
+
+const httpRequests = new client.Counter({
+  name: "http_requests_total",
+  help: "Total HTTP requests handled by the demo app",
+  labelNames: ["method", "route", "status"],
+  registers: [register],
+});
+
+const httpErrors = new client.Counter({
+  name: "http_errors_total",
+  help: "Total HTTP 5xx responses from the demo app",
+  labelNames: ["route"],
+  registers: [register],
+});
+
+// --- Routes ----------------------------------------------------------------
+app.get("/health", (_req, res) => {
+  res.json({ status: "ok" });
+});
+
+app.get("/api/orders/:id", (req, res) => {
+  httpRequests.inc({ method: "GET", route: "/api/orders/:id", status: 200 });
+  res.json({ id: req.params.id, status: "shipped" });
+});
+
+// Intentionally broken endpoint. Every call returns 500 and increments
+// http_errors_total. Prometheus alert rule (see prometheus/rules.yml) fires
+// when the rate exceeds the threshold.
+app.get("/api/checkout", (req, res) => {
+  req.log.error(
+    { correlationId: req.correlationId, route: "/api/checkout" },
+    "checkout failed: payment provider unreachable",
+  );
+  httpRequests.inc({ method: "GET", route: "/api/checkout", status: 500 });
+  httpErrors.inc({ route: "/api/checkout" });
+  res.status(500).json({
+    error: "payment_provider_unreachable",
+    correlationId: req.correlationId,
+  });
+});
+
+app.get("/metrics", async (_req, res) => {
+  res.set("Content-Type", register.contentType);
+  res.end(await register.metrics());
+});
+
+const port = Number(process.env.PORT ?? 3001);
+app.listen(port, "0.0.0.0", () => {
+  log.info({ port }, "demo-app listening");
+});

package/template/docker/alertmanager/alertmanager.yml

@@ -0,0 +1,11 @@
+route:
+  receiver: junando
+  group_wait: 5s
+  group_interval: 10s
+  repeat_interval: 1h
+
+receivers:
+  - name: junando
+    webhook_configs:
+      - url: 'http://junando-webhook:4000/webhook/alert'
+        send_resolved: true

package/template/docker/loki/loki-config.yml

@@ -0,0 +1,25 @@
+auth_enabled: false
+
+server:
+  http_listen_port: 3100
+
+common:
+  path_prefix: /loki
+  storage:
+    filesystem:
+      chunks_directory: /loki/chunks
+      rules_directory: /loki/rules
+  replication_factor: 1
+  ring:
+    kvstore:
+      store: inmemory
+
+schema_config:
+  configs:
+    - from: 2024-01-01
+      store: tsdb
+      object_store: filesystem
+      schema: v13
+      index:
+        prefix: index_
+        period: 24h

package/template/docker/prometheus/prometheus.yml

@@ -0,0 +1,16 @@
+global:
+  scrape_interval: 5s
+  evaluation_interval: 5s
+
+rule_files:
+  - /etc/prometheus/rules.yml
+
+alerting:
+  alertmanagers:
+    - static_configs:
+        - targets: ['alertmanager:9093']
+
+scrape_configs:
+  - job_name: 'demo-app'
+    static_configs:
+      - targets: ['demo-app:3001']

package/template/docker/prometheus/rules.yml

@@ -0,0 +1,17 @@
+groups:
+  - name: demo-app
+    interval: 10s
+    rules:
+      - alert: CheckoutEndpointFailing
+        expr: rate(http_errors_total{route="/api/checkout"}[30s]) > 0
+        for: 15s
+        labels:
+          severity: critical
+          service: demo-app
+          team: payments
+        annotations:
+          summary: 'Checkout endpoint returning 5xx errors'
+          description: |
+            The /api/checkout endpoint on demo-app is returning errors at a rate of
+            {{ $value }} req/s. Likely cause: payment provider unreachable.
+          runbook_url: 'https://example.com/runbooks/checkout'

package/template/docker-compose.yml

@@ -0,0 +1,72 @@
+name: junando-example
+
+# Two modes:
+#   docker compose up                       -> use published junando-webhook image (default)
+#   docker compose --profile dev up         -> build junando-webhook from the monorepo source
+#
+# The published mode is intended for users evaluating Junando.
+# The dev mode is for contributors who change core/webhook code and want to see
+# the effect end-to-end without publishing.
+
+services:
+  demo-app:
+    build: ./app
+    ports: ['3001:3001']
+    environment:
+      - PORT=3001
+      - LOG_LEVEL=info
+    depends_on:
+      - prometheus
+
+  prometheus:
+    image: prom/prometheus:v2.53.0
+    ports: ['9090:9090']
+    volumes:
+      - ./docker/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - ./docker/prometheus/rules.yml:/etc/prometheus/rules.yml:ro
+
+  alertmanager:
+    image: prom/alertmanager:v0.27.0
+    ports: ['9093:9093']
+    volumes:
+      - ./docker/alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
+
+  loki:
+    image: grafana/loki:3.0.0
+    ports: ['3100:3100']
+    volumes:
+      - ./docker/loki/loki-config.yml:/etc/loki/local-config.yaml:ro
+    command: -config.file=/etc/loki/local-config.yaml
+
+  redis:
+    image: redis:7-alpine
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 5s
+      retries: 5
+
+  # Default: pull the published image. No build needed.
+  junando-webhook:
+    profiles: ['', 'default']
+    image: ghcr.io/germoren/junando-webhook:latest
+    ports: ['4000:4000']
+    env_file: .env
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+
+  # Dev profile: build from the monorepo Dockerfile. Same service name so
+  # alertmanager.yml does not need to change.
+  junando-webhook-dev:
+    profiles: ['dev']
+    build:
+      context: ../..
+      dockerfile: docker/Dockerfile.webhook
+    container_name: junando-webhook
+    ports: ['4000:4000']
+    env_file: .env
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped

package/template/scripts/simulate.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Triggers the broken /api/checkout endpoint enough times to fire the
+# Prometheus alert rule. Each request gets a unique correlationId so you can
+# follow it in pino logs, Prometheus metrics, and the Slack message.
+
+set -euo pipefail
+
+HOST="${HOST:-http://localhost:3001}"
+COUNT="${COUNT:-20}"
+DELAY="${DELAY:-0.2}"
+
+echo "Firing ${COUNT} failing checkout requests against ${HOST} ..."
+
+for i in $(seq 1 "${COUNT}"); do
+  CID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
+  STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+    -H "x-correlation-id: ${CID}" \
+    "${HOST}/api/checkout" || true)
+  printf "  [%2d/%s] correlationId=%s -> %s\n" "${i}" "${COUNT}" "${CID}" "${STATUS}"
+  sleep "${DELAY}"
+done
+
+cat <<EOF
+
+Done. What to watch next:
+  - Prometheus rules:   http://localhost:9090/alerts
+  - Alertmanager queue: http://localhost:9093/#/alerts
+  - Junando logs:       docker compose logs -f junando-webhook
+  - Slack channel:      the one you configured in .env (SLACK_CHANNEL)
+
+Expected timeline:
+  ~15s  alert CheckoutEndpointFailing transitions to FIRING in Prometheus
+  ~20s  Alertmanager posts to junando-webhook
+  ~30s  Junando publishes the LLM analysis to Slack
+EOF