@monster-orange/den 0.0.0 → 0.1.0

package/make/den.mk

@@ -0,0 +1,80 @@
+# make/den.mk — Den's make targets, for any distribution.
+#
+# A distribution's Makefile includes it from the installed package:
+#
+#   include node_modules/@monster-orange/den/make/den.mk
+#
+# Den's own Makefile includes it too (include make/den.mk). Recipes run from
+# the distribution root (the directory make runs in: config/, manifests/,
+# reports/ and results/ live there) and reach Den's own files through
+# $(DEN_ENGINE). In Den's checkout the two are the same directory.
+
+# Prefix of the service and setup targets (`make <prefix>-up`, -status, …):
+# the distribution's own name. Set it before the include; Den's own is "den".
+DEN_TARGET_PREFIX ?= den
+
+# Den's package root: the directory above this file.
+DEN_ENGINE ?= $(patsubst %/,%,$(abspath $(dir $(lastword $(MAKEFILE_LIST)))/..))
+
+# The distribution root, and the engine, for every Den process a recipe runs.
+DEN_ROOT ?= $(CURDIR)
+export DEN_ROOT
+DEN_ENGINE_ROOT := $(DEN_ENGINE)
+export DEN_ENGINE_ROOT
+
+# Binaries from Den's dependencies: Den's own node_modules (a checkout) or
+# the distribution's, where npm hoists them.
+den_bin = $(firstword $(wildcard $(DEN_ENGINE)/node_modules/.bin/$(1) $(CURDIR)/node_modules/.bin/$(1)) $(1))
+DEN_TSX        ?= $(call den_bin,tsx)
+DEN_PLAYWRIGHT ?= $(call den_bin,playwright)
+# The CLI (as `den`, or the distribution's own name via its den.yml).
+DEN_BIN        ?= $(DEN_ENGINE)/bin/den
+DEN_CLI_TS     ?= $(DEN_TSX) $(DEN_ENGINE)/src/ui/cli/index.ts
+
+# ── Globals ───────────────────────────────────────────────────────────────────
+
+# Environment selection — defaults to local.
+# Usage: make test-syn-all env=staging
+env ?= local
+export E2E_ENVIRONMENT=$(env)
+OPEN_REPORT ?= 0
+
+# Secrets backend is a strategy chosen in the org config (secrets.provider:
+# doppler | 1password | env). Override per shell:
+#   DEN_SECRETS_PROVIDER=env make up
+# OP_ACCOUNT is only consulted when the 1password strategy is selected.
+OP_ACCOUNT ?= example.1password.com
+export OP_ACCOUNT
+
+# Repo for the smoke and browser pillars — no default: make test-smk-all repo=<repo>
+repo ?=
+
+# ── Fragments ─────────────────────────────────────────────────────────────────
+include $(DEN_ENGINE)/make/test.mk
+include $(DEN_ENGINE)/make/local_dev.mk
+include $(DEN_ENGINE)/make/journeys.mk
+include $(DEN_ENGINE)/make/security.mk
+include $(DEN_ENGINE)/make/demo.mk
+
+# ── Help ──────────────────────────────────────────────────────────────────────
+# A distribution gets `make help` from here; Den's own Makefile has a longer
+# one and sets DEN_OWN_HELP before including this file.
+.PHONY: $(DEN_TARGET_PREFIX)-help
+$(DEN_TARGET_PREFIX)-help:
+	@printf '\nDen targets (run from this directory)\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n'
+	@printf '  make test                  interactive test runner\n'
+	@printf '  make web                   the web UI\n'
+	@printf '  make $(DEN_TARGET_PREFIX)-up / down         start / stop services\n'
+	@printf '  make $(DEN_TARGET_PREFIX)-status            service status\n'
+	@printf '  make test-syn-all repo=R   browser tests\n'
+	@printf '  make test-int-all          API tests\n'
+	@printf '  make test-smk-all repo=R   smoke tests\n'
+	@printf '  make test-perf module=M    performance tests\n'
+	@printf '  make test-jrn-all          journeys\n'
+	@printf '  make test-sec-all          security scans\n\n'
+
+ifndef DEN_OWN_HELP
+.PHONY: help
+help: $(DEN_TARGET_PREFIX)-help
+.DEFAULT_GOAL := help
+endif

package/make/journeys.mk

@@ -0,0 +1,57 @@
+# make/journeys.mk — Agent-driven E2E journeys (journeys pillar)
+#
+# Journey specs live in registered service repos (e.g. shop-web) and are
+# discovered through their .den.yml `journeys:` block; the runner drives
+# a sandboxed @cursor/sdk agent per journey. See src/pillars/journeys/.
+#
+# Usage:
+#   make test-jrn-all env=<env>                 All journeys allowing <env>
+#   make test-jrn-<name> env=<env>              Single journey by spec name
+#   make test-jrn-<name> env=<env> repo=<repo>  Disambiguate a spec name
+#                                               duplicated across repos
+#                                               (passes --journey=<repo>/<name>)
+#
+# The root Makefile declares a global `repo` for the smoke pillar.
+# Journeys deliberately ignore that inherited default — only a `repo=` stated
+# on the command line ($(origin repo) == "command line") qualifies the spec
+# name; otherwise the bare name is resolved across all registered repos.
+#
+# EXPLICIT-ENV GUARD: the root Makefile sets `env ?= local`, which would
+# silently point journeys at local. Journeys are agent-driven runs with
+# real side effects, so the env MUST be stated on the command line —
+# $(origin env) is "command line" only then; "file" (the ?= default) and
+# "environment" (an inherited shell var) are both rejected.
+#
+# MODEL: each journey spec may declare its own default (`model:` field);
+# the JOURNEYS_MODEL env var, when set, overrides every spec (operator
+# control, e.g. CI cost pinning). A journey with neither is refused by the
+# runner — no default model is ever invented. CURSOR_API_KEY needs no
+# export — the runner falls back to a 1Password `op read` when unset.
+
+.PHONY: test-jrn-all .journeys-check-env
+
+.journeys-check-env:
+ifeq ($(origin env),command line)
+	@true
+else
+	@echo "❌ Journeys require an explicit env=<name> on the command line."
+	@echo "   The Makefile default (env ?= local) is deliberately rejected for"
+	@echo "   agent-driven runs. Usage: make test-jrn-all env=local"
+	@exit 1
+endif
+
+# All journeys whose environments allowlist includes $(env)
+test-jrn-all: .journeys-check-env .check-auth
+	@echo "🧭 Running ALL journeys..."
+	@echo "🌍 Environment: $(env)"
+	@echo ""
+	@$(DEN_TSX) $(DEN_ENGINE)/src/pillars/journeys/run.ts --env=$(env)
+
+# make test-jrn-<journey-name> env=<env>
+test-jrn-%: .journeys-check-env .check-auth
+	@JOURNEY_NAME=$(subst test-jrn-,,$@); \
+	$(if $(filter command line,$(origin repo)),JOURNEY_NAME="$(repo)/$$JOURNEY_NAME";) \
+	echo "🧭 Running journey $$JOURNEY_NAME..."; \
+	echo "🌍 Environment: $(env)"; \
+	echo ""; \
+	$(DEN_TSX) $(DEN_ENGINE)/src/pillars/journeys/run.ts --env=$(env) --journey=$$JOURNEY_NAME

package/make/local_dev.mk

@@ -0,0 +1,154 @@
+# make/local_dev.mk — Local Dev environment manager
+#
+# Manages the Local Dev experience: service clones, workspaces, web UI,
+# secrets setup, repo registration, auth configuration, and AWS profiles.
+
+.PHONY: down $(DEN_TARGET_PREFIX)-up $(DEN_TARGET_PREFIX)-down $(DEN_TARGET_PREFIX)-restart $(DEN_TARGET_PREFIX)-status $(DEN_TARGET_PREFIX)-services \
+        $(DEN_TARGET_PREFIX)-graph $(DEN_TARGET_PREFIX)-logs \
+        $(DEN_TARGET_PREFIX)-register $(DEN_TARGET_PREFIX)-setup $(DEN_TARGET_PREFIX)-sync $(DEN_TARGET_PREFIX)-workspace \
+        $(DEN_TARGET_PREFIX)-init $(DEN_TARGET_PREFIX)-validate $(DEN_TARGET_PREFIX)-local-dev $(DEN_TARGET_PREFIX)-setup-secrets $(DEN_TARGET_PREFIX)-setup-1password \
+        register-repos aws-configure auth-configure \
+        web dev-dns
+
+# ── Service management ────────────────────────────────────────────────────────
+
+# Start always_on services in the active workspace.
+# Usage: make $(DEN_TARGET_PREFIX)-up  OR  make $(DEN_TARGET_PREFIX)-up args="shop/api tasks-runner"
+$(DEN_TARGET_PREFIX)-up:
+	@if ! $(DEN_TSX) $(DEN_ENGINE)/scripts/setup-secrets.ts --gate; then \
+		echo ""; \
+		echo "🔑  secrets.required is set and the secrets backend is not ready."; \
+		echo ""; \
+		$(MAKE) $(DEN_TARGET_PREFIX)-setup-secrets || exit 1; \
+	fi
+	@$(DEN_BIN) up $(args)
+
+# Stop services in the active workspace. `make down` is the short form most
+# people reach for, so it stops SERVICES; use `make test-down` for Playwright/k6.
+# Usage: make down  OR  make down args="files-api -w files-api"
+down $(DEN_TARGET_PREFIX)-down:
+	@$(DEN_BIN) down $(args)
+
+$(DEN_TARGET_PREFIX)-restart:
+	@$(DEN_BIN) restart $(args)
+
+$(DEN_TARGET_PREFIX)-status:
+	@$(DEN_BIN) status
+
+# Tail live local logs for a repo's service (offers to start it when down).
+# Usage: make $(DEN_TARGET_PREFIX)-logs  OR  make $(DEN_TARGET_PREFIX)-logs args="shop"
+$(DEN_TARGET_PREFIX)-logs:
+	@$(DEN_BIN) logs $(args)
+
+$(DEN_TARGET_PREFIX)-services:
+	@$(DEN_BIN) services
+
+# Derive and show the system dependency graph.
+# Usage: make $(DEN_TARGET_PREFIX)-graph  OR  make $(DEN_TARGET_PREFIX)-graph args="--all --diff"
+$(DEN_TARGET_PREFIX)-graph:
+	@$(DEN_BIN) graph $(args)
+
+# Check for updates and pull managed repos.
+$(DEN_TARGET_PREFIX)-sync:
+	@$(DEN_BIN) sync $(args)
+
+# ── Workspaces ────────────────────────────────────────────────────────────────
+
+# Usage: make $(DEN_TARGET_PREFIX)-workspace args="list"
+#        make $(DEN_TARGET_PREFIX)-workspace args="use feat-streaming"
+#        make $(DEN_TARGET_PREFIX)-workspace args="create feat-streaming"
+$(DEN_TARGET_PREFIX)-workspace:
+	@$(DEN_BIN) workspace $(args)
+
+# ── Catalog & repo setup ──────────────────────────────────────────────────────
+
+# Register a repo in the service catalog (interactive).
+# Usage: make $(DEN_TARGET_PREFIX)-register  OR  make $(DEN_TARGET_PREFIX)-register args=/path/to/repo
+$(DEN_TARGET_PREFIX)-register:
+	@$(DEN_BIN) register $(args)
+
+# Run setup for registered services.
+# Usage: make $(DEN_TARGET_PREFIX)-setup  OR  make $(DEN_TARGET_PREFIX)-setup args="shop tasks-runner"
+$(DEN_TARGET_PREFIX)-setup:
+	@$(DEN_BIN) setup $(args)
+
+# Scaffold a new .den.yml in a target directory (interactive).
+# Usage: make $(DEN_TARGET_PREFIX)-init  OR  make $(DEN_TARGET_PREFIX)-init args=/path/to/repo
+$(DEN_TARGET_PREFIX)-init:
+	@$(DEN_BIN) init $(args)
+
+# Heal config/den.yml — fills missing required keys (currently github_org).
+# Idempotent. Safe for existing users whose den.yml pre-dates github_org.
+$(DEN_TARGET_PREFIX)-heal-config:
+	@$(DEN_TSX) $(DEN_ENGINE)/scripts/heal-config.ts
+
+# Validate a .den.yml file or URL.
+# Usage: make $(DEN_TARGET_PREFIX)-validate args=/path/to/repo
+#        make $(DEN_TARGET_PREFIX)-validate args=/path/to/repo/.den.yml
+$(DEN_TARGET_PREFIX)-validate:
+	@$(DEN_BIN) validate $(args)
+
+# Toggle the local dev experience on or off (per-engineer, gitignored).
+# Usage: make $(DEN_TARGET_PREFIX)-local-dev args=on|off
+$(DEN_TARGET_PREFIX)-local-dev:
+	@$(DEN_BIN) local-dev $(args)
+
+# Set up developer secrets with the configured backend (secrets.provider).
+$(DEN_TARGET_PREFIX)-setup-secrets:
+	@$(DEN_TSX) $(DEN_ENGINE)/scripts/setup-secrets.ts
+
+# 1Password strategy only: populate the "Developer API Keys" item.
+$(DEN_TARGET_PREFIX)-setup-1password:
+	@$(DEN_TSX) $(DEN_ENGINE)/scripts/setup-1password.ts
+
+# Show where test discovery gets its repos. With Local Dev enabled (default)
+# it follows the workspace — nothing to register. Hosted / no-local setups get
+# the legacy sibling scan (also forceable with args=--legacy), which writes
+# config/local/registered-repos.json (gitignored).
+register-repos:
+	@$(DEN_TSX) $(DEN_ENGINE)/src/scripts/register-repos.ts $(args)
+
+# Map den environments → AWS CLI profiles for CloudWatch logs and re-auth.
+# Writes to config/local/aws-profiles.json (gitignored).
+aws-configure:
+	@$(DEN_TSX) $(DEN_ENGINE)/src/scripts/configure-aws-profiles.ts
+
+# Per-engineer admin 1Password setup — staging/production only.
+# Saves config/local/admin-auth-{env}.json (gitignored, no password stored).
+auth-configure:
+	@E2E_ENVIRONMENT=$(env) $(DEN_TSX) $(DEN_ENGINE)/scripts/auth-configure.ts
+	@$(MAKE) int-jwt-clear env=$(env)
+
+# ── Web UI ────────────────────────────────────────────────────────────────────
+
+# Browser-based runner + Local Dev dashboard at http://localhost:<web.port> (default 7777),
+# and https://<brand>.<edge.domain> once `edge up` has run. Never opens a browser:
+# it prints the address instead.
+# PORT=8080 make web          — run on a different port.
+# make web silent=true        — suppress request logs (banner still shown).
+web:
+	@if ! $(DEN_TSX) $(DEN_ENGINE)/scripts/setup-secrets.ts --gate; then \
+		echo ""; \
+		echo "🔑  secrets.required is set and the secrets backend is not ready."; \
+		echo ""; \
+		$(MAKE) $(DEN_TARGET_PREFIX)-setup-secrets || exit 1; \
+	fi
+	@echo "🌐 Starting the web UI..."
+	@_PORT=$${PORT:-$$($(DEN_TSX) -e 'import("$(DEN_ENGINE)/src/shared/edge/config.ts").then(m=>console.log(m.readWebPort()))' 2>/dev/null || echo 7777)}; \
+	_HOST=$$(grep -q "127.0.0.1 den" /etc/hosts 2>/dev/null && echo "den" || echo "localhost"); \
+	_SILENT_FLAG=$$([ "$(silent)" = "true" ] && echo "--silent" || echo ""); \
+	echo "   http://$$_HOST:$$_PORT"; \
+	$(DEN_TSX) $(DEN_ENGINE)/src/ui/server/index.ts $$_SILENT_FLAG
+
+# OPTIONAL, legacy: add a bare 'den' alias to /etc/hosts (needs sudo) so
+# http://den:7777 resolves. Not needed — http://den.localhost:7777
+# already resolves in Chromium/Firefox, and http://localhost:7777 everywhere.
+# Requires sudo.
+dev-dns:
+	@if grep -q "127.0.0.1 den" /etc/hosts 2>/dev/null; then \
+		echo "✅ /etc/hosts already has '127.0.0.1 den'"; \
+	else \
+		echo "Adding '127.0.0.1 den' to /etc/hosts (requires sudo)..."; \
+		echo '127.0.0.1 den' | sudo tee -a /etc/hosts > /dev/null; \
+		echo "✅ Done. You can now use http://den:7777"; \
+	fi

package/make/security.mk

@@ -0,0 +1,59 @@
+# make/security.mk — OWASP ZAP scanning of our own services (security pillar)
+#
+# Scan targets are declared in each workspace repo's .den.yml (or the
+# den-held manifests/<repo>.den.yml) under `security:`; the runner
+# drives ZAP in docker. Every target host must be on the owned-host allowlist
+# (config/den.yml `security.owned_hosts`). See src/pillars/security/.
+#
+# Usage:
+#   make test-sec-all env=<env>                      Every target, baseline mode
+#   make test-sec-<service> env=<env>                One service (bare name)
+#   make test-sec-<service> env=<env> repo=<repo>    Repo-qualified (--service=<repo>/<service>)
+#   make test-sec-all env=<env> mode=<m>             m = baseline | api | full | all
+#   make test-sec-all env=<env> dry_run=1            Print the docker commands only
+#
+# Production is passive-only (baseline) and additionally needs
+# DEN_ALLOW_PROD=1; the runner enforces both — this file only guards env.
+#
+# The root Makefile sets a global `repo ?= shop` default for the smoke
+# pillar. Security deliberately ignores that inherited default — only a
+# `repo=` stated on the command line ($(origin repo) == "command line")
+# qualifies the service name.
+#
+# EXPLICIT-ENV GUARD: the root Makefile sets `env ?= local`, which would
+# silently point scans at local. Scans send attack traffic, so the env MUST
+# be stated on the command line — $(origin env) is "command line" only then;
+# "file" (the ?= default) and "environment" (an inherited shell var) are
+# both rejected.
+
+.PHONY: test-sec-all .security-check-env
+
+# Optional pass-through flags (only when stated on the command line)
+SEC_FLAGS := $(if $(filter command line,$(origin mode)),--mode=$(mode)) \
+             $(if $(filter command line,$(origin dry_run)),--dry-run)
+
+.security-check-env:
+ifeq ($(origin env),command line)
+	@true
+else
+	@echo "❌ Security scans require an explicit env=<name> on the command line."
+	@echo "   The Makefile default (env ?= local) is deliberately rejected for"
+	@echo "   scans that send attack traffic. Usage: make test-sec-all env=local"
+	@exit 1
+endif
+
+# Every discovered target allowed in $(env)
+test-sec-all: .security-check-env
+	@echo "🛡️  Running ALL security scans..."
+	@echo "🌍 Environment: $(env)"
+	@echo ""
+	@$(DEN_TSX) $(DEN_ENGINE)/src/pillars/security/run.ts --env=$(env) $(SEC_FLAGS)
+
+# make test-sec-<service> env=<env> [repo=<repo>]
+test-sec-%: .security-check-env
+	@SERVICE_NAME=$(subst test-sec-,,$@); \
+	$(if $(filter command line,$(origin repo)),SERVICE_NAME="$(repo)/$$SERVICE_NAME";) \
+	echo "🛡️  Running security scan for $$SERVICE_NAME..."; \
+	echo "🌍 Environment: $(env)"; \
+	echo ""; \
+	$(DEN_TSX) $(DEN_ENGINE)/src/pillars/security/run.ts --env=$(env) --service=$$SERVICE_NAME $(SEC_FLAGS)