agent-scaffold-cli 0.1.1__py3-none-any.whl

agent_scaffold/__init__.py

@@ -0,0 +1,8 @@
+"""agent-scaffold: generate runnable AI agent projects from markdown specs."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("agent-scaffold-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

agent_scaffold/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m agent_scaffold`."""
+
+from agent_scaffold.cli import app
+
+if __name__ == "__main__":
+    app()

agent_scaffold/_bundled_deployments/__init__.py

@@ -0,0 +1,15 @@
+"""Bundled agent-deployments docs for zero-config usage.
+
+The docs/ directory is populated at build time by scripts/sync_deployments.sh.
+When installed via PyPI/Homebrew, the bundled docs allow agent-scaffold to work
+without requiring a separate agent-deployments clone.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def bundled_docs_path() -> Path:
+    """Return the path to the bundled deployments root (contains docs/)."""
+    return Path(__file__).parent

agent_scaffold/_bundled_deployments/docs/cross-cutting/README.md

@@ -0,0 +1,15 @@
+# Cross-cutting Concerns
+
+Shared production plumbing used by all agents. Each file answers: **"What production scaffolding do I need?"**
+
+| Concern | Library (Py / TS) | Reference |
+|---------|-------------------|-----------|
+| [Auth](auth-jwt.md) | python-jose / hono-jwt | Inline implementation below |
+| [Logging](logging-structured.md) | structlog / pino | Inline implementation below |
+| [Observability](observability.md) | Langfuse SDK | Inline implementation below |
+| [Rate Limiting](rate-limiting.md) | slowapi / hono-rate-limiter | Inline implementation below |
+| [Testing](testing-strategy.md) | pytest + DeepEval / vitest + Promptfoo | Inline implementation below |
+
+## The 11-point production checklist
+
+Every blueprint specifies these concerns. See [playbook/production-checklist.md](../playbook/production-checklist.md) for the full checklist.

agent_scaffold/_bundled_deployments/docs/cross-cutting/auth-jwt.md

@@ -0,0 +1,235 @@
+# Cross-cutting: JWT Authentication
+
+**Concern:** Protect all agent endpoints with bearer-token authentication.
+**Library:** `python-jose` (Py) / `jose` (TS)
+**Lives in:** Inline below (formerly `common/python/agent_common/auth/` and `common/typescript/src/auth/`)
+
+## What it provides
+
+- **Token creation** -- `create_token()` / `createToken()` signs a JWT with a user ID, expiry, and optional extra claims.
+- **Token verification** -- `verify_token()` / `verifyToken()` decodes and validates a JWT, returning a typed payload.
+- **FastAPI dependency** -- `get_current_user(secret)` returns a FastAPI `Depends()` that extracts the bearer token from the `Authorization` header, verifies it, and returns a `TokenPayload`. Returns 401 on failure.
+- **Typed payload** -- `TokenPayload` model (Pydantic / TS interface) with `sub`, `exp`, and extra claims.
+
+## How to use
+
+### Python (FastAPI)
+
+```python
+from agent_common.auth import create_token, get_current_user, TokenPayload
+
+# Create a token (for testing or a /login endpoint)
+token = create_token("user-123", secret="my-secret", expires_hours=24)
+
+# Protect an endpoint
+@app.post("/query")
+async def query(
+    request: QueryRequest,
+    user: TokenPayload = Depends(get_current_user("my-secret")),
+):
+    # user.sub is the authenticated user ID
+    return await handle_query(request, user_id=user.sub)
+```
+
+### TypeScript (Hono)
+
+```typescript
+import { createToken, verifyToken } from "@agent-deployments/common";
+
+// Create a token
+const token = await createToken("user-123", "my-secret");
+
+// Verify in middleware
+app.use("/query/*", async (c, next) => {
+  const auth = c.req.header("Authorization");
+  const token = auth?.replace("Bearer ", "");
+  if (!token) return c.json({ error: "Unauthorized" }, 401);
+
+  try {
+    const payload = await verifyToken(token, "my-secret");
+    c.set("userId", payload.sub);
+    await next();
+  } catch {
+    return c.json({ error: "Invalid token" }, 401);
+  }
+});
+```
+
+## Configuration via env
+
+| Var | Default | Effect |
+|-----|---------|--------|
+| `JWT_SECRET` | `change-me-in-production` | Signing secret (HS256) |
+| Algorithm | `HS256` | Symmetric signing for local dev. Switch to RS256 with a key pair for production |
+| Expiry | 24 hours | Token lifetime |
+
+## Tests
+
+Test token creation, verification, expiry, invalid tokens, and the FastAPI dependency (Py) / token round-trip and invalid signature (TS).
+
+## Production considerations
+
+- **HS256 is fine for local dev** where the secret is in `.env`. For production, switch to **RS256** with asymmetric keys so the API only needs the public key.
+- **Token rotation:** The current implementation has no refresh token flow. For production, add a `/refresh` endpoint or use short-lived tokens with an external auth provider.
+- **Extra claims:** Pass `extra={"role": "admin"}` to embed authorization data in the token. The payload is available in the endpoint handler.
+
+## Swapping to an external auth provider
+
+To use Auth0, Clerk, or Supabase Auth instead of self-managed JWT:
+
+1. Replace `create_token()` with the provider's token issuance (usually handled by their SDK).
+2. Replace `verify_token()` with JWKS-based verification against the provider's public keys.
+3. Keep the `get_current_user` dependency shape -- just change the verification logic inside.
+
+This is a **single-file swap** (only the auth module changes).
+
+## Reference Implementation
+
+<details>
+<summary>Python — <code>jwt.py</code></summary>
+
+```python
+"""JWT utilities for FastAPI-based agent prototypes."""
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from jose import JWTError, jwt
+from pydantic import BaseModel
+
+_security = HTTPBearer()
+
+_DEFAULT_ALGORITHM = "HS256"
+_DEFAULT_EXPIRY_HOURS = 24
+
+
+class TokenPayload(BaseModel):
+    sub: str
+    exp: datetime
+    extra: dict[str, Any] = {}
+
+
+def create_token(
+    user_id: str,
+    secret: str,
+    *,
+    algorithm: str = _DEFAULT_ALGORITHM,
+    expires_hours: int = _DEFAULT_EXPIRY_HOURS,
+    extra: dict[str, Any] | None = None,
+) -> str:
+    """Create a signed JWT."""
+    now = datetime.now(UTC)
+    payload = {
+        "sub": user_id,
+        "iat": now,
+        "exp": now + timedelta(hours=expires_hours),
+        **(extra or {}),
+    }
+    return jwt.encode(payload, secret, algorithm=algorithm)
+
+
+def verify_token(
+    token: str,
+    secret: str,
+    *,
+    algorithm: str = _DEFAULT_ALGORITHM,
+) -> TokenPayload:
+    """Verify and decode a JWT. Raises ValueError on failure."""
+    try:
+        payload = jwt.decode(token, secret, algorithms=[algorithm])
+        return TokenPayload(
+            sub=payload["sub"],
+            exp=datetime.fromtimestamp(payload["exp"], tz=UTC),
+            extra={k: v for k, v in payload.items() if k not in ("sub", "exp", "iat")},
+        )
+    except JWTError as exc:
+        raise ValueError(f"Invalid token: {exc}") from exc
+
+
+def get_current_user(
+    secret: str,
+    algorithm: str = _DEFAULT_ALGORITHM,
+):
+    """Return a FastAPI dependency that extracts and verifies the JWT bearer token."""
+
+    async def _dependency(
+        credentials: HTTPAuthorizationCredentials = Depends(_security),
+    ) -> TokenPayload:
+        try:
+            return verify_token(credentials.credentials, secret, algorithm=algorithm)
+        except ValueError:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid or expired token",
+            )
+
+    return _dependency
+```
+
+</details>
+
+<details>
+<summary>TypeScript — <code>jwt.ts</code></summary>
+
+```typescript
+/**
+ * JWT utilities for Hono-based agent prototypes.
+ */
+
+import * as jose from "jose";
+
+export interface TokenPayload {
+  sub: string;
+  exp: number;
+  iat: number;
+  [key: string]: unknown;
+}
+
+const DEFAULT_ALGORITHM = "HS256";
+const DEFAULT_EXPIRY_HOURS = 24;
+
+/**
+ * Create a signed JWT.
+ */
+export async function createToken(
+  userId: string,
+  secret: string,
+  options: {
+    algorithm?: string;
+    expiresHours?: number;
+    extra?: Record<string, unknown>;
+  } = {},
+): Promise<string> {
+  const { expiresHours = DEFAULT_EXPIRY_HOURS, extra = {} } = options;
+
+  const secretKey = new TextEncoder().encode(secret);
+  const now = Math.floor(Date.now() / 1000);
+
+  return new jose.SignJWT({ sub: userId, ...extra })
+    .setProtectedHeader({ alg: DEFAULT_ALGORITHM })
+    .setIssuedAt(now)
+    .setExpirationTime(now + expiresHours * 3600)
+    .sign(secretKey);
+}
+
+/**
+ * Verify and decode a JWT. Throws on failure.
+ */
+export async function verifyToken(
+  token: string,
+  secret: string,
+  options: { algorithm?: string } = {},
+): Promise<TokenPayload> {
+  const secretKey = new TextEncoder().encode(secret);
+
+  const { payload } = await jose.jwtVerify(token, secretKey, {
+    algorithms: [DEFAULT_ALGORITHM],
+  });
+
+  return payload as TokenPayload;
+}
+```
+
+</details>

agent_scaffold/_bundled_deployments/docs/cross-cutting/logging-structured.md

@@ -0,0 +1,196 @@
+# Cross-cutting: Structured Logging
+
+**Concern:** JSON-structured logs with request/session/user context on every line.
+**Library:** `structlog` (Py) / `pino` (TS)
+**Lives in:** Inline below (formerly `common/python/agent_common/logs/` and `common/typescript/src/logging/`)
+
+## What it provides
+
+- **One-call setup** -- `configure(service_name, env, log_level)` (Py) / `createLogger(config)` (TS) configures the logger for the entire app.
+- **Environment-aware output** -- Development mode renders human-readable colored output. Production mode renders JSON for log aggregators.
+- **Contextual binding** -- `structlog.contextvars` (Py) / `pino.child()` (TS) lets you attach request-scoped context (trace ID, user ID, session ID) that appears on every subsequent log line.
+- **Standard fields** -- Every log line includes: `service`, `env`, `level`, `timestamp` (ISO 8601), `msg`.
+
+## How to use
+
+### Python
+
+```python
+from agent_common.logs import configure
+import structlog
+
+# At app startup (typically in lifespan)
+configure("docs-rag-qa", env="production", log_level="INFO")
+
+# Get a logger anywhere
+logger = structlog.get_logger()
+
+# Basic logging
+logger.info("query_received", question="What is MCP?")
+
+# Bind context for a request scope
+log = logger.bind(trace_id="abc-123", user_id="user-1")
+log.info("processing_query")
+log.info("query_answered", citation_count=3)
+# Both lines include trace_id and user_id
+```
+
+Output (production):
+
+```json
+{"service":"docs-rag-qa","env":"production","level":"info","timestamp":"2026-04-27T10:00:00Z","msg":"query_received","question":"What is MCP?"}
+```
+
+### TypeScript
+
+```typescript
+import { createLogger } from "@agent-deployments/common";
+
+const logger = createLogger({
+  serviceName: "docs-rag-qa",
+  env: "production",
+  level: "info",
+});
+
+// Basic logging
+logger.info({ question: "What is MCP?" }, "query_received");
+
+// Child logger with request context
+const reqLog = logger.child({ traceId: "abc-123", userId: "user-1" });
+reqLog.info("processing_query");
+reqLog.info({ citationCount: 3 }, "query_answered");
+```
+
+## Configuration via env
+
+| Var | Default | Effect |
+|-----|---------|--------|
+| `LOG_LEVEL` | `INFO` | Minimum level to emit (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
+| `APP_ENV` | `development` | Controls output format: `development` = colored console, anything else = JSON |
+
+## Tests
+
+Test configure in both modes and verify output format (Py). Test logger creation, child loggers, and level filtering (TS).
+
+## Logging conventions
+
+Use these patterns consistently across prototypes:
+
+| Event | Key | Example |
+|-------|-----|---------|
+| Request received | `{endpoint}_received` | `logger.info("query_received", ...)` |
+| Processing step | `{step}_completed` | `logger.info("retrieval_completed", chunk_count=5)` |
+| Error | `{operation}_failed` | `logger.error("query_failed", error=str(exc))` |
+| External call | `{service}_called` | `logger.info("llm_called", model="claude-sonnet-4-6", tokens=150)` |
+
+Always use **snake_case** event names. Always include the **trace_id** and **user_id** via context binding, not per-call arguments.
+
+## Swapping to OpenTelemetry-native logging
+
+If your deployment already uses an OTel collector:
+
+1. Replace structlog/pino with `opentelemetry-sdk` (Py) / `@opentelemetry/sdk-logs` (TS).
+2. Remove the `configure()` / `createLogger()` call.
+3. Set `OTEL_EXPORTER_OTLP_ENDPOINT` in env.
+
+This is a **multi-file swap** (common module + app startup + docker-compose for the OTel collector).
+
+## Reference Implementation
+
+<details>
+<summary>Python — <code>structlog_config.py</code></summary>
+
+```python
+"""Structured logging configuration using structlog."""
+
+import logging
+import sys
+
+import structlog
+
+
+def configure(
+    service_name: str,
+    *,
+    env: str = "development",
+    log_level: str = "INFO",
+) -> None:
+    """Configure structlog for the application.
+
+    In production, outputs JSON. In development, outputs colored human-readable logs.
+    """
+    shared_processors: list[structlog.types.Processor] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+    ]
+
+    if env == "development":
+        renderer: structlog.types.Processor = structlog.dev.ConsoleRenderer()
+    else:
+        renderer = structlog.processors.JSONRenderer()
+
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            structlog.processors.EventRenamer("msg"),
+            renderer,
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(logging.getLevelNamesMapping()[log_level.upper()]),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
+        cache_logger_on_first_use=True,
+    )
+
+    structlog.contextvars.clear_contextvars()
+    structlog.contextvars.bind_contextvars(service=service_name, env=env)
+```
+
+</details>
+
+<details>
+<summary>TypeScript — <code>logger.ts</code></summary>
+
+```typescript
+/**
+ * Structured logging using pino.
+ */
+
+import pino from "pino";
+
+export interface LoggerConfig {
+  serviceName: string;
+  env?: string;
+  level?: string;
+}
+
+/**
+ * Create a configured pino logger instance.
+ */
+export function createLogger(config: LoggerConfig): pino.Logger {
+  const { serviceName, env = "development", level = "info" } = config;
+
+  const transport =
+    env === "development"
+      ? {
+          target: "pino/file",
+          options: { destination: 1 }, // stdout
+        }
+      : undefined;
+
+  return pino({
+    name: serviceName,
+    level,
+    transport,
+    base: {
+      service: serviceName,
+      env,
+    },
+    timestamp: pino.stdTimeFunctions.isoTime,
+  });
+}
+```
+
+</details>