enlace 0.0.2__tar.gz

enlace-0.0.2/.claude/CLAUDE.md

@@ -0,0 +1,113 @@
+# enlace — Agent Instructions
+
+## Core Principles
+
+These two principles govern ALL changes to enlace. Every PR, feature, and
+suggestion must respect both. They are in tension — the design challenge is
+balancing them.
+
+### 1. Apps should not need to change
+
+enlace wraps apps from the outside. Apps don't import enlace, don't depend
+on it, and don't know it exists. All aggregation logic (discovery, routing,
+CORS, static serving) lives in enlace, not in the app.
+
+When enlace encounters an app that's hard to mount:
+- **First**: solve it on the enlace side (app.toml config, env vars, middleware)
+- **Second**: suggest a minimal app change that preserves standalone operation
+- **Last resort**: suggest an app change that breaks standalone — but flag it explicitly
+
+### 2. Enlaced apps must still work alone
+
+An app that works standalone today must still work standalone after being
+enlaced. When we suggest changes to an app, those changes MUST preserve
+the app's ability to run independently.
+
+The pattern: **env-var with current value as default**.
+
+```python
+# GOOD: works standalone AND under enlace
+import os
+if not os.environ.get('ENLACE_MANAGED'):
+    app.add_middleware(CORSMiddleware, ...)
+
+# BAD: breaks standalone
+# (CORSMiddleware deleted entirely)
+```
+
+```typescript
+// GOOD: standalone uses localhost, enlace overrides at build time
+const API_BASE = process.env.NEXT_PUBLIC_API_BASE || "http://localhost:8000/api";
+
+// BAD: breaks standalone
+const API_BASE = "/api/s_conditions";
+```
+
+### Zero coupling
+
+Apps do not import enlace. The dependency graph:
+- enlace depends on FastAPI, Uvicorn, Pydantic, argh
+- Apps depend on their own domain libs (FastAPI, numpy, etc.)
+- There is NO dependency from apps to enlace
+
+enlace provides services to apps via:
+- ASGI scope injection (auth, store) — apps read `request.state.store`, not `import enlace.stores`
+- Environment variables (`ENLACE_MANAGED`) — apps can condition on this but don't have to
+- Convention (filesystem layout, app.toml) — external to app code
+
+## Architecture
+
+Read `misc/docs/enlace_spec.md` for the full architecture and design rationale.
+
+```
+enlace/
+├── base.py        # Pydantic models: AppConfig, PlatformConfig, ConventionsConfig
+├── util.py        # Pure helpers: derive_display_name, derive_route_prefix, is_skippable
+├── discover.py    # ConventionDiscoverer: walks apps/, detects types, loads TOML
+├── compose.py     # build_backend(): mounts sub-apps, cascade_lifespan, sets ENLACE_MANAGED
+├── diagnose.py    # diagnose_app(): scan an app dir for enlace compatibility issues
+├── serve.py       # Uvicorn subprocess orchestration, signal forwarding
+├── __main__.py    # CLI via argh.dispatch_commands
+├── __init__.py    # Public API facade
+└── tests/         # Unit tests (test_discover.py, test_compose.py)
+```
+
+**Data flow:** `PlatformConfig.from_toml()` → `ConventionDiscoverer.discover()` →
+`config.check_conflicts()` → `build_backend(config)` → `uvicorn --factory`
+
+## Before Making Changes
+
+- Run `enlace show-config` to understand current state
+- Run `enlace check` to validate config before and after changes
+
+## Critical Rules
+
+- **NEVER use `BaseHTTPMiddleware`** — it has terminal bugs (exception swallowing, ContextVar corruption). Use pure ASGI middleware (three-callable pattern) only.
+- **Mount on `FastAPI()` directly**, never on `APIRouter` — known framework bug.
+- **Discovery must never silently swallow ImportErrors** — distinguish "module doesn't exist" from "module has broken import".
+- **All middleware must be pure ASGI** (scope, receive, send pattern).
+- **Conflict detection is fail-fast** — report ALL conflicts, don't stop at first.
+- **CORS on parent only** — sub-apps must not add their own CORSMiddleware. If they do, enlace still works (MEDIUM issue, not a blocker), but the diagnostic flags it.
+- **`ENLACE_MANAGED=1`** — set by `build_backend()` so sub-apps can condition on it.
+- **Suggestions to app developers must preserve standalone operation** — use the env-var-with-default pattern, never suggest changes that break the app's ability to run alone.
+
+## Research Docs
+
+Consult these before modifying subsystems:
+
+| Subsystem | Document |
+|-----------|----------|
+| App mounting, middleware | `misc/docs/asgi_composition__*.md` |
+| Auth middleware | `misc/docs/auth_cross_cutting__*.md` |
+| Discovery, config | `misc/docs/convention_over_configuration__*.md` |
+| Deployment, logging | `misc/docs/deployment_observability__*.md` |
+| Frontend serving | `misc/docs/frontend_serving__*.md` |
+| Data persistence | `misc/docs/user_data_persistence__*.md` |
+| Design principles | `misc/docs/design_principles__*.md` |
+
+## Testing
+
+```bash
+pytest enlace/tests/     # Unit tests
+pytest tests/            # Integration tests
+```

enlace-0.0.2/.claude/skills/enlace/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: enlace
+description: >
+  Use when working with the enlace multi-app platform — creating apps, configuring
+  platform.toml or app.toml, diagnosing discovery issues, understanding conventions,
+  or serving/deploying apps. Triggers on: enlace CLI commands, apps/ directory
+  structures, platform.toml/app.toml files, multi-app ASGI composition, or when the
+  user mentions enlace, app discovery, app mounting, or personal app platform.
+---
+
+# enlace — Multi-App Platform
+
+enlace discovers Python modules and React apps in a directory, mounts them as
+sub-applications under a single ASGI server, and serves them.
+
+**enlace is not a framework.** Apps don't import it, don't depend on it, and
+don't know it exists. You write a standard FastAPI app (or plain Python
+functions with type hints). enlace discovers it from the outside, mounts it
+alongside other apps, and serves them all — without touching your code.
+
+**Two principles:**
+1. **Apps should not need to change** — all aggregation logic lives in enlace.
+   When an app is hard to mount, prefer enlace-side config (app.toml, env vars)
+   over app code changes.
+2. **Enlaced apps must still work alone** — if we do suggest changes, they must
+   preserve standalone operation. Pattern: env-var with current value as default.
+
+## Core Concept
+
+Drop files in `apps/`, enlace finds and serves them:
+
+```
+apps/
+├── my_tool/
+│   └── server.py          # has `app = FastAPI()` → served at /api/my_tool
+├── dashboard/
+│   ├── server.py           # backend
+│   └── frontend/
+│       └── index.html      # SPA assets
+├── calculator/
+│   └── server.py           # has typed functions, no `app` → auto-wrapped
+└── blog/
+    └── frontend/
+        └── index.html      # frontend-only, no backend
+```
+
+Everything enlace infers is inspectable (`enlace show-config`) and overridable
+(via TOML or CLI flags).
+
+## CLI Commands
+
+```bash
+enlace serve                          # Start backend (dev mode, hot reload)
+enlace serve --mode prod              # Production mode (2 workers)
+enlace serve --port 9000              # Custom port
+enlace serve --app-dirs "/a,/b"       # Serve apps from specific directories
+enlace show-config                    # Resolved config with provenance
+enlace show-config --json             # Machine-readable
+enlace show-config --verbose          # Show where each value came from
+enlace check                          # Validate config, check route conflicts
+enlace list-apps                      # Table: name, route, type, access
+```
+
+## Creating an App
+
+### Standalone ASGI App (most common)
+
+Create `apps/{name}/server.py` with an `app` attribute:
+
+```python
+# apps/my_tool/server.py
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get("/hello")
+def hello():
+    return {"message": "Hello from my_tool"}
+```
+
+This gets mounted at `/api/my_tool/`. The `app` attribute name is configurable.
+
+### Function Collection (no FastAPI needed)
+
+If the entry module has typed public functions but no `app` attribute, enlace
+auto-wraps them as endpoints:
+
+```python
+# apps/calculator/server.py
+def add(a: int, b: int) -> dict:
+    return {"result": a + b}
+
+def multiply(a: float, b: float) -> dict:
+    return {"result": a * b}
+```
+
+Functions become POST endpoints: `/api/calculator/add`, `/api/calculator/multiply`.
+Simple-type parameters are query params.
+
+### Frontend-Only App
+
+Just a `frontend/` directory with `index.html`:
+
+```
+apps/blog/
+└── frontend/
+    └── index.html
+```
+
+No backend mounted. Assets served at `/apps/blog/` (in production via Caddy).
+
+## Discovery Conventions
+
+| What | Convention | Override key in `app.toml` |
+|------|-----------|---------------------------|
+| Route prefix | `/api/{directory_name}` | `route` |
+| Backend entry | First of `server.py`, `app.py`, `main.py` | `entry_point` |
+| ASGI app object | Attribute named `app` | `app_attr` |
+| Frontend assets | `frontend/` with `index.html` | `frontend_dir` |
+| Display name | Dir name, `_` → space, title-cased | `display_name` |
+| Access level | `local` (default) | `access` |
+| Skip directory | Starts with `_` or `.` | — |
+
+## Multi-Source App Discovery
+
+enlace can discover apps from multiple locations — you don't need to move
+existing projects into a single `apps/` folder.
+
+Two source types:
+- **`apps_dirs`**: directories that CONTAIN app subdirectories (walk children)
+- **`app_dirs`**: individual directories that ARE apps (discover directly)
+
+### Enlacing existing projects
+
+```toml
+# platform.toml
+[platform]
+apps_dirs = ["apps"]
+app_dirs = [
+    "/Users/thor/projects/chord_analyzer",
+    "/Users/thor/projects/todo_app",
+]
+```
+
+Or via CLI:
+```bash
+enlace serve --app-dirs "/path/to/chord_analyzer,/path/to/todo_app"
+enlace serve --apps-dirs "apps,/path/to/more_apps"
+```
+
+Symlinks also work: `ln -s /path/to/my_app apps/my_app` and enlace discovers
+it transparently.
+
+App names must be globally unique across all sources. Duplicates are caught
+by `enlace check`.
+
+## Configuration
+
+### `platform.toml` (global, in project root)
+
+```toml
+[platform]
+apps_dirs = ["apps"]                   # container directories (walk children)
+app_dirs = []                          # individual app directories
+domain = "localhost"
+backend_port = 8000
+
+[conventions]
+entry_points = ["server.py", "app.py", "main.py"]
+app_attr = "app"
+frontend_dir = "frontend"
+```
+
+The legacy `apps_dir = "apps"` (scalar) is still supported for backward compat.
+
+### `app.toml` (per-app, in app directory)
+
+```toml
+route = "/api/custom-route"
+access = "public"
+display_name = "My Custom App"
+entry_point = "application.py"
+app_attr = "my_app"
+```
+
+### Override Precedence (lowest → highest)
+
+```
+hardcoded defaults → filesystem conventions → app.toml → platform.toml → env vars → CLI flags
+```
+
+Environment variables: `ENLACE_APPS_DIRS`, `ENLACE_APP_DIRS` (pathsep-delimited).
+
+## App Types
+
+| Type | Detection | Mounting |
+|------|-----------|---------|
+| `asgi_app` | Module has `app` attribute (callable) | `parent.mount(prefix, sub_app)` |
+| `functions` | No `app` attr, has typed public functions | Auto-wrapped as APIRouter |
+| `frontend_only` | No backend entry, has `frontend/index.html` | Static file serving only |
+
+## Diagnosing Issues
+
+**App not discovered?**
+1. Run `enlace show-config --verbose` — is the app listed?
+2. Check directory isn't prefixed with `_` or `.`
+3. Check entry point file exists (`server.py`, `app.py`, or `main.py`)
+4. Check for import errors — enlace intentionally surfaces them (won't silently skip)
+
+**Route conflict?**
+- `enlace check` reports ALL conflicts at once with both app names
+- Fix by changing `route` in one app's `app.toml`
+
+**Wrong app type detected?**
+- Run `enlace show-config --verbose` to see detection reason
+- Ensure your `app = FastAPI()` is at module level (not inside a function)
+- For function collections, ensure functions have type annotations
+
+## Access Levels
+
+| Level | Description |
+|-------|-------------|
+| `local` | Development only (default) |
+| `public` | Open to everyone |
+| `protected:shared` | Single shared password gate |
+| `protected:user` | Per-user accounts |
+
+Set in `app.toml` with `access = "protected:shared"` etc.
+
+## Workflow
+
+```bash
+# 1. Initialize (creates platform.toml + apps/)
+enlace init
+
+# 2. Create an app
+mkdir -p apps/my_app
+# Write apps/my_app/server.py
+
+# 3. Verify discovery
+enlace show-config
+enlace check
+
+# 4. Serve
+enlace serve
+# → http://localhost:8000/api/my_app/
+```
+
+Always run `enlace check` after making changes to catch conflicts early.

enlace-0.0.2/.claude/skills/enlace/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "enlace",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to add a new app to my enlace platform that exposes a couple of Python functions as API endpoints -- one that takes a text string and returns the word count, and another that reverses the string. I don't want to deal with FastAPI boilerplate, just the functions. Set it up for me in apps/text_utils/",
+      "expected_output": "Creates apps/text_utils/server.py with two typed functions (word_count and reverse_text), no FastAPI app object. The agent understands this will be auto-detected as a 'functions' type app and served at /api/text_utils/.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I'm getting an error when I run enlace serve -- it says route conflict. I have three apps in my apps directory: todo, notes, and dashboard. The dashboard app has an app.toml that sets route = '/api/notes'. Can you help me figure out what's going on and fix it?",
+      "expected_output": "The agent identifies the conflict between the 'notes' app (convention route /api/notes) and 'dashboard' app (overridden to /api/notes via app.toml). Suggests running enlace check, then fixes dashboard's app.toml to use a different route like /api/dashboard or /api/dash.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I need to set up a new enlace project from scratch. I want two apps: a chord_analyzer with a FastAPI backend and a React frontend, and a simple notes app that's backend-only. The chord_analyzer should be public access and the notes app should be protected with a shared password. Walk me through the whole setup.",
+      "expected_output": "The agent creates the full directory structure: platform.toml with conventions, apps/chord_analyzer/server.py with FastAPI app, apps/chord_analyzer/frontend/ placeholder, apps/chord_analyzer/app.toml with access=public, apps/notes/server.py with FastAPI app, apps/notes/app.toml with access=protected:shared. Mentions running enlace show-config to verify.",
+      "files": []
+    }
+  ]
+}

enlace-0.0.2/.claude/skills/enlace-dev/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: enlace-dev
+description: >
+  Use when developing or modifying the enlace package itself — adding features,
+  fixing bugs, extending the ASGI composition, adding middleware, or working on
+  any module in the enlace/ source directory. Triggers on: editing enlace source
+  files (base.py, discover.py, compose.py, serve.py, auth.py, stores.py),
+  implementing spec phases 2-4, or when the user says "add X to enlace" or
+  "implement Y in enlace".
+---
+
+# Developing enlace
+
+enlace is a multi-app ASGI platform. This skill covers the critical rules,
+architecture, and patterns needed to modify the enlace codebase safely.
+
+## Design Principles
+
+These two principles govern ALL changes. Every feature, fix, and diagnostic
+suggestion must respect both:
+
+### 1. Zero coupling — apps don't import enlace
+
+enlace wraps apps from the outside. Apps depend on their own domain libs
+(FastAPI, numpy, etc.), never on enlace. enlace provides services via:
+- ASGI scope injection (auth, store) — not imports
+- Environment variables (`ENLACE_MANAGED`) — optional, apps can ignore it
+- Convention (filesystem layout, app.toml) — external to app code
+
+When adding features, NEVER create patterns that require apps to
+`import enlace` or depend on enlace-specific APIs.
+
+### 2. Preserve standalone operation
+
+When enlace (or its diagnostic tool) suggests changes to an app, those
+changes MUST preserve the app's ability to run independently. The pattern:
+**env-var with current value as default**.
+
+```python
+# GOOD: works standalone AND under enlace
+if not os.environ.get('ENLACE_MANAGED'):
+    app.add_middleware(CORSMiddleware, ...)
+
+# BAD: breaks standalone
+# (CORSMiddleware deleted entirely)
+```
+
+When writing diagnostic messages, fix suggestions, or documentation:
+- Prefer enlace-side solutions (app.toml, build-time env vars) over app changes
+- When app changes are needed, always use the env-var-with-default pattern
+- Flag any suggestion that would break standalone with `breaks_standalone=True`
+
+See `misc/docs/design_principles__*.md` for the full rationale.
+
+## Architecture
+
+```
+enlace/
+├── base.py        # Pydantic models: AppConfig, PlatformConfig, ConventionsConfig
+├── util.py        # Pure helpers: derive_display_name, derive_route_prefix, is_skippable
+├── discover.py    # ConventionDiscoverer: walks apps/, detects types, loads TOML
+├── compose.py     # build_backend(): mounts sub-apps, cascade_lifespan
+├── diagnose.py    # diagnose_app(): scan an app dir for enlace compatibility issues
+├── serve.py       # Uvicorn subprocess orchestration, signal forwarding
+├── __main__.py    # CLI via argh.dispatch_commands
+├── __init__.py    # Public API facade
+└── tests/         # Unit tests (test_discover.py, test_compose.py)
+```
+
+**Data flow:** `PlatformConfig.from_toml()` → `ConventionDiscoverer.discover()` →
+`config.check_conflicts()` → `build_backend(config)` → `uvicorn --factory`
+
+## Critical Rules
+
+### Never use BaseHTTPMiddleware
+
+It has terminal, unfixable bugs: exception swallowing across mounted sub-apps,
+ContextVar propagation corruption, synchronous execution of background tasks.
+The Starlette maintainer has called it unfixable. Always use pure ASGI middleware:
+
+```python
+# YES: Pure ASGI middleware
+class MyMiddleware:
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http":
+            # your logic here
+            pass
+        await self.app(scope, receive, send)
+
+# NO: BaseHTTPMiddleware — NEVER use this
+```
+
+### Mount on FastAPI directly, not APIRouter
+
+`app.mount()` only works on the top-level FastAPI instance. Mounting on an
+APIRouter silently fails (FastAPI issues #4194, #10180).
+
+### Never silently swallow ImportErrors during discovery
+
+If a module file exists but fails to import (syntax error, missing dep), that is
+a real error. Propagate it. Only skip directories that have no entry point file.
+This prevents the Celery autodiscover anti-pattern.
+
+### Conflict detection: fail-fast, report ALL
+
+`check_conflicts()` collects every duplicate route, not just the first. Users
+need to see all conflicts at once to fix them in one pass.
+
+### Starlette does NOT cascade lifespan events
+
+Mounted sub-apps never receive startup/shutdown. The `cascade_lifespan` context
+manager in compose.py works around this by iterating Mount routes and entering
+their lifespan contexts. Any new mounting logic must preserve this.
+
+### CORS on parent only
+
+If a sub-app also adds CORS middleware, responses get duplicate headers. All
+cross-cutting middleware (auth, CORS, logging, store injection) goes on the
+parent FastAPI app exclusively.
+
+## Research Documents
+
+Detailed rationale, code patterns, and pitfalls live in `misc/docs/`:
+
+| Module area | Consult |
+|-------------|---------|
+| compose.py, mounting, middleware | `asgi_composition__*.md` |
+| auth.py, sessions, cookies | `auth_cross_cutting__*.md` |
+| discover.py, config, show-config | `convention_over_configuration__*.md` |
+| serve.py, deployment, logging | `deployment_observability__*.md` |
+| frontend.py, SPA serving | `frontend_serving__*.md` |
+| stores.py, PrefixedStore, Mall | `user_data_persistence__*.md` |
+| Design philosophy, coupling, independence | `design_principles__*.md` |
+
+Read the relevant doc before modifying its subsystem.
+
+## Implementation Phases (from spec)
+
+**Phase 1 (done):** Core discovery, composition, CLI, serve
+**Phase 2:** frontend.py (SPAStaticFiles, launcher), auth.py (PlatformAuthMiddleware,
+  shared-password login, signed cookies), inject.py (HTML injection), hash-password
+  and create-session-secret CLI commands
+**Phase 3:** stores.py (PrefixedStore, Mall, filesystem/SQLite backends),
+  StoreInjectionMiddleware, per-user sessions, CSRF, WebSocket origin validation
+**Phase 4:** deploy.py (Caddyfile/systemd generation), structlog middleware,
+  analytics injection, `generate` CLI namespace
+
+## Testing Pattern
+
+```bash
+pytest enlace/tests/     # Unit tests
+pytest tests/            # Integration tests
+```
+
+Tests use `tmp_path` fixtures to create temporary app directories. Composition
+tests use `starlette.testclient.TestClient` against the built app. Always test
+both the happy path and error cases (import errors, conflicts, missing files).
+
+## Adding a New Module
+
+1. Create `enlace/{module}.py`
+2. Add exports to `enlace/__init__.py`
+3. Create `enlace/tests/test_{module}.py`
+4. If it adds CLI commands, register them in `enlace/__main__.py` via
+   `argh.dispatch_commands`
+5. Run `enlace check` before and after to verify nothing breaks

enlace-0.0.2/.claude/skills/enlace-dev/evals/evals.json

@@ -0,0 +1,17 @@
+{
+  "skill_name": "enlace-dev",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to add structured request logging to enlace as a middleware that logs every request with timestamp, method, path, status, duration, and the app name extracted from the route prefix. This is part of Phase 4 in the spec. Add it to compose.py's middleware stack.",
+      "expected_output": "The agent creates a pure ASGI middleware (NOT BaseHTTPMiddleware), extracts app_id from path prefix, uses time.perf_counter_ns for duration, wraps the send callable to capture status code. Adds it to the middleware stack in build_backend(). Reads the deployment_observability research doc for the structlog pattern.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "The show-config command currently works but it re-does the full discovery+import every time. I want to add a new enlace init command that creates a platform.toml and apps/ directory in the current directory. Keep it simple.",
+      "expected_output": "The agent adds an init() function, creates a default platform.toml and apps/ directory, registers the command in __main__.py's dispatch list, and exports from __init__.py. Follows the argh pattern used by existing commands.",
+      "files": []
+    }
+  ]
+}