partweave 0.1.1

package/modules/auth/web/src/auth/auth-context.tsx

@@ -0,0 +1,63 @@
+"use client";
+
+import { createContext, useContext, useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import type { AuthUser, Credentials } from "@app/shared";
+import * as auth from "@/auth/client";
+
+interface AuthState {
+  user: AuthUser | null;
+  loading: boolean;
+  login: (creds: Credentials) => Promise<void>;
+  register: (creds: Credentials) => Promise<void>;
+  logout: () => Promise<void>;
+}
+
+const AuthCtx = createContext<AuthState | null>(null);
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+  const [user, setUser] = useState<AuthUser | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  async function load() {
+    try {
+      setUser(await auth.fetchMe());
+    } catch (err) {
+      // A 401 means the stored token is stale/expired — clear it so it isn't
+      // re-sent on later requests. Other errors (e.g. server down) keep it.
+      if (err instanceof auth.ApiError && err.status === 401) await auth.logout();
+      setUser(null);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  useEffect(() => {
+    void load();
+  }, []);
+
+  const value: AuthState = {
+    user,
+    loading,
+    login: async (creds) => {
+      await auth.login(creds);
+      await load();
+    },
+    register: async (creds) => {
+      await auth.register(creds);
+      await load();
+    },
+    logout: async () => {
+      await auth.logout();
+      setUser(null);
+    },
+  };
+
+  return <AuthCtx.Provider value={value}>{children}</AuthCtx.Provider>;
+}
+
+export function useAuth(): AuthState {
+  const ctx = useContext(AuthCtx);
+  if (!ctx) throw new Error("useAuth must be used within <AuthProvider>");
+  return ctx;
+}

package/modules/auth/web/src/auth/client.test.ts

@@ -0,0 +1,73 @@
+// @vitest-environment node
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// A leftover token is present in storage for every test — the exact condition
+// that produced the register-401 bug.
+let storedToken: string | null = null;
+
+vi.mock("@/lib/config", () => ({ API_URL: "http://api.test" }));
+vi.mock("@/lib/token-store", () => ({
+  tokenStore: {
+    get: vi.fn(async () => storedToken),
+    set: vi.fn(async () => {}),
+    clear: vi.fn(async () => {}),
+  },
+}));
+
+import { register, login, fetchMe, logout, ApiError } from "./client";
+import { tokenStore } from "@/lib/token-store";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function callTo(fetchMock: ReturnType<typeof vi.fn>, path: string) {
+  return fetchMock.mock.calls.find((c) => String(c[0]).endsWith(path));
+}
+function authHeaderOf(call: unknown[] | undefined): unknown {
+  const init = call?.[1] as { headers?: Record<string, unknown> } | undefined;
+  return init?.headers?.Authorization;
+}
+
+describe("web auth client", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    storedToken = "STALE.TOKEN";
+    fetchMock = vi.fn(async () => jsonResponse({ access: "a", refresh: "r" }));
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  it("register sends NO Authorization even with a stored token (regression: 401 on register)", async () => {
+    await register({ email: "a@b.com", password: "supersecret" });
+    const call = callTo(fetchMock, "/api/auth/register");
+    expect(call, "register endpoint was called").toBeTruthy();
+    expect(authHeaderOf(call)).toBeUndefined();
+  });
+
+  it("login sends NO Authorization", async () => {
+    await login({ email: "a@b.com", password: "supersecret" });
+    expect(authHeaderOf(callTo(fetchMock, "/api/auth/token"))).toBeUndefined();
+  });
+
+  it("fetchMe DOES send the stored token", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 1, email: "a@b.com" }));
+    await fetchMe();
+    expect(authHeaderOf(callTo(fetchMock, "/api/auth/me"))).toBe("Bearer STALE.TOKEN");
+  });
+
+  it("throws ApiError carrying the HTTP status on failure", async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ detail: "no" }, 401));
+    await expect(fetchMe()).rejects.toBeInstanceOf(ApiError);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ detail: "no" }, 401));
+    await expect(fetchMe()).rejects.toMatchObject({ status: 401 });
+  });
+
+  it("logout clears the token store", async () => {
+    await logout();
+    expect(tokenStore.clear).toHaveBeenCalled();
+  });
+});

package/modules/auth/web/src/auth/client.ts

@@ -0,0 +1,59 @@
+import type { AuthTokens, AuthUser, Credentials } from "@app/shared";
+import { API_URL } from "@/lib/config";
+import { tokenStore } from "@/lib/token-store";
+
+/** Error carrying the HTTP status, so callers can react to e.g. a 401. */
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    body: string,
+  ) {
+    super(`${status} ${body}`);
+    this.name = "ApiError";
+  }
+}
+
+// `auth` defaults to true — the stored token is attached. Public endpoints
+// (register/login/refresh) MUST pass `auth: false`: sending a stale/expired
+// token to them makes the server's JWTAuthentication reject the request with a
+// 401 before it ever reaches the AllowAny permission.
+async function req<T>(path: string, init: RequestInit & { auth?: boolean } = {}): Promise<T> {
+  const { auth = true, headers, ...rest } = init;
+  const token = auth ? await tokenStore.get() : null;
+  const res = await fetch(`${API_URL}${path}`, {
+    ...rest,
+    headers: {
+      "Content-Type": "application/json",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      ...(headers ?? {}),
+    },
+  });
+  if (!res.ok) throw new ApiError(res.status, await res.text());
+  return (res.status === 204 ? null : await res.json()) as T;
+}
+
+export async function login(creds: Credentials): Promise<void> {
+  const tokens = await req<AuthTokens>("/api/auth/token", {
+    method: "POST",
+    body: JSON.stringify(creds),
+    auth: false,
+  });
+  await tokenStore.set(tokens);
+}
+
+export async function register(creds: Credentials): Promise<void> {
+  await req("/api/auth/register", {
+    method: "POST",
+    body: JSON.stringify(creds),
+    auth: false,
+  });
+  await login(creds);
+}
+
+export async function fetchMe(): Promise<AuthUser> {
+  return req<AuthUser>("/api/auth/me");
+}
+
+export async function logout(): Promise<void> {
+  await tokenStore.clear();
+}

package/modules/auth/web/src/lib/config.ts

@@ -0,0 +1,2 @@
+export const API_URL =
+  process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:8000";

package/modules/auth/web/src/lib/token-store.ts

@@ -0,0 +1,23 @@
+import type { AuthTokens, TokenStore } from "@app/shared";
+
+const ACCESS = "access_token";
+const REFRESH = "refresh_token";
+
+/**
+ * Web TokenStore over localStorage. For production, prefer httpOnly cookies set
+ * by a Next.js route handler — swap this impl without touching callers.
+ */
+export const tokenStore: TokenStore = {
+  async get() {
+    if (typeof window === "undefined") return null;
+    return window.localStorage.getItem(ACCESS);
+  },
+  async set(tokens: AuthTokens) {
+    window.localStorage.setItem(ACCESS, tokens.access);
+    window.localStorage.setItem(REFRESH, tokens.refresh);
+  },
+  async clear() {
+    window.localStorage.removeItem(ACCESS);
+    window.localStorage.removeItem(REFRESH);
+  },
+};

package/modules/ci/module.json

@@ -0,0 +1,11 @@
+{
+  "id": "ci",
+  "title": "CI workflows",
+  "description": "Per-app GitHub Actions with path filters, so each part builds independently.",
+  "kind": "feature",
+  "targets": ["root"],
+  "default": true,
+  "notes": [
+    "CI: see .github/workflows/*.yml — each app's pipeline runs only when its files change."
+  ]
+}

package/modules/db-postgres/module.json

@@ -0,0 +1,22 @@
+{
+  "id": "db-postgres",
+  "title": "PostgreSQL",
+  "description": "Use PostgreSQL instead of the default SQLite.",
+  "kind": "feature",
+  "targets": ["server"],
+  "requiresApps": ["server"],
+  "provides": "database",
+  "default": true,
+  "env": {
+    "DATABASE_URL": "postgres://app:app@localhost:5432/app"
+  },
+  "wiring": {
+    "server": {
+      "deps": ["psycopg[binary]>=3.2"]
+    }
+  },
+  "notes": [
+    "PostgreSQL: set DATABASE_URL in .env (already added to .env.example).",
+    "Need a local database? Include the 'docker' component and run `make db-up`."
+  ]
+}

package/modules/docker/module.json

@@ -0,0 +1,19 @@
+{
+  "id": "docker",
+  "title": "Docker & Compose",
+  "description": "A Postgres compose file for local dev and a production Dockerfile for the server.",
+  "kind": "feature",
+  "targets": ["server", "root"],
+  "requiresApps": ["server"],
+  "default": true,
+  "env": {
+    "POSTGRES_USER": "app",
+    "POSTGRES_PASSWORD": "app",
+    "POSTGRES_DB": "app",
+    "POSTGRES_PORT": "5432"
+  },
+  "notes": [
+    "Local DB: `make db-up` (docker compose). Server image: `docker build apps/server`.",
+    "Postgres creds/port come from .env (POSTGRES_USER/PASSWORD/DB/PORT); keep them in sync with DATABASE_URL."
+  ]
+}

package/modules/docker/root/infra/docker-compose.yml

@@ -0,0 +1,20 @@
+services:
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-app}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-app}
+      POSTGRES_DB: ${POSTGRES_DB:-app}
+    ports:
+      # Bound to localhost so the dev database isn't exposed on the network.
+      - "127.0.0.1:${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-app}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  pgdata:

package/modules/docker/server/.dockerignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+db.sqlite3
+.env
+.pytest_cache/
+.ruff_cache/

package/modules/example/mobile/app/profile.test.tsx

@@ -0,0 +1,44 @@
+import type { ReactNode } from "react";
+import { render, screen } from "@testing-library/react-native";
+import { useAuth } from "@/auth/auth-context";
+
+// Create the mock inside the factory (no out-of-scope refs), then import it back
+// — jest hoists jest.mock above the imports, so `useAuth` is the mocked fn here.
+jest.mock("@/auth/auth-context", () => ({ useAuth: jest.fn() }));
+jest.mock("expo-router", () => {
+  const { Text } = require("react-native");
+  return { Link: ({ children }: { children: ReactNode }) => <Text>{children}</Text> };
+});
+
+import Profile from "./profile";
+
+const mockUseAuth = useAuth as jest.Mock;
+
+describe("example Profile screen", () => {
+  beforeEach(() => mockUseAuth.mockReset());
+
+  it("shows a loading state", () => {
+    mockUseAuth.mockReturnValue({ user: null, loading: true, logout: jest.fn() });
+    render(<Profile />);
+    expect(screen.getByText("Loading…")).toBeTruthy();
+  });
+
+  it("prompts to log in when there is no user", () => {
+    mockUseAuth.mockReturnValue({ user: null, loading: false, logout: jest.fn() });
+    render(<Profile />);
+    expect(screen.getByText("Not logged in.")).toBeTruthy();
+    expect(screen.getByText("Log in")).toBeTruthy();
+  });
+
+  it("shows the signed-in user's details", () => {
+    mockUseAuth.mockReturnValue({
+      user: { id: 7, email: "me@x.com" },
+      loading: false,
+      logout: jest.fn(),
+    });
+    render(<Profile />);
+    expect(screen.getByText("Signed in ✓")).toBeTruthy();
+    expect(screen.getByText("Email: me@x.com")).toBeTruthy();
+    expect(screen.getByText("ID: 7")).toBeTruthy();
+  });
+});

package/modules/example/mobile/app/profile.tsx

@@ -0,0 +1,39 @@
+import { Link } from "expo-router";
+import { Button, StyleSheet, Text, View } from "react-native";
+import { useAuth } from "@/auth/auth-context";
+
+export default function Profile() {
+  const { user, loading, logout } = useAuth();
+
+  if (loading)
+    return (
+      <View style={styles.container}>
+        <Text>Loading…</Text>
+      </View>
+    );
+
+  if (!user)
+    return (
+      <View style={styles.container}>
+        <Text>Not logged in.</Text>
+        <Link href="/login" style={styles.link}>
+          Log in
+        </Link>
+      </View>
+    );
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Signed in ✓</Text>
+      <Text>ID: {user.id}</Text>
+      <Text>Email: {user.email}</Text>
+      <Button title="Log out" onPress={() => logout()} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, justifyContent: "center", padding: 24, gap: 8 },
+  title: { fontSize: 24, fontWeight: "bold" },
+  link: { color: "#2563eb" },
+});

package/modules/example/module.json

@@ -0,0 +1,21 @@
+{
+  "id": "example",
+  "title": "Example screens",
+  "description": "A demo profile screen that reads the logged-in user from /api/auth/me.",
+  "kind": "feature",
+  "targets": ["web", "mobile"],
+  "requiresApps": ["server"],
+  "requires": ["auth"],
+  "default": true,
+  "wiring": {
+    "web": {
+      "routes": ["{ href: \"/profile\", label: \"My profile\" },"]
+    },
+    "mobile": {
+      "routes": ["{ href: \"/profile\", label: \"My profile\" },"]
+    }
+  },
+  "notes": [
+    "Visit /profile (web) or the Profile screen (mobile) after logging in to see the wiring end-to-end."
+  ]
+}

package/modules/example/web/app/profile/page.test.tsx

@@ -0,0 +1,41 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { ReactNode } from "react";
+import { render, screen } from "@testing-library/react";
+
+const { useAuth } = vi.hoisted(() => ({ useAuth: vi.fn() }));
+vi.mock("@/auth/auth-context", () => ({ useAuth }));
+vi.mock("next/link", () => ({
+  default: ({ children, href }: { children: ReactNode; href: string }) => <a href={href}>{children}</a>,
+}));
+
+import ProfilePage from "./page";
+
+describe("example ProfilePage", () => {
+  beforeEach(() => useAuth.mockReset());
+
+  it("shows a loading state", () => {
+    useAuth.mockReturnValue({ user: null, loading: true, logout: vi.fn() });
+    render(<ProfilePage />);
+    expect(screen.getByText(/Loading/)).toBeTruthy();
+  });
+
+  it("prompts to log in when there is no user", () => {
+    useAuth.mockReturnValue({ user: null, loading: false, logout: vi.fn() });
+    render(<ProfilePage />);
+    // the "Log in" link is a leaf element with the login href
+    expect(screen.getByText("Log in").getAttribute("href")).toBe("/login");
+  });
+
+  it("shows the signed-in user's details", () => {
+    useAuth.mockReturnValue({
+      user: { id: 7, email: "me@x.com" },
+      loading: false,
+      logout: vi.fn(),
+    });
+    render(<ProfilePage />);
+    expect(screen.getByText("Signed in ✓")).toBeTruthy();
+    expect(screen.getByText(/me@x\.com/)).toBeTruthy();
+    expect(screen.getByText(/ID: 7/)).toBeTruthy();
+  });
+});

package/modules/example/web/app/profile/page.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import Link from "next/link";
+import { useAuth } from "@/auth/auth-context";
+
+export default function ProfilePage() {
+  const { user, loading, logout } = useAuth();
+
+  if (loading) return <main className="p-8">Loading…</main>;
+
+  if (!user)
+    return (
+      <main className="p-8">
+        Not logged in.{" "}
+        <Link href="/login" className="text-blue-600 underline">
+          Log in
+        </Link>
+      </main>
+    );
+
+  return (
+    <main className="mx-auto max-w-xl p-8">
+      <h1 className="text-2xl font-bold">Signed in ✓</h1>
+      <p className="mt-2">ID: {user.id}</p>
+      <p>Email: {user.email}</p>
+      <button
+        className="mt-4 rounded bg-gray-800 px-3 py-1 text-white"
+        onClick={() => logout()}
+      >
+        Log out
+      </button>
+    </main>
+  );
+}

package/modules/storage/module.json

@@ -0,0 +1,34 @@
+{
+  "id": "storage",
+  "title": "File storage (swappable)",
+  "description": "Abstract StorageProvider with Local and S3 backends; switch via STORAGE_BACKEND.",
+  "kind": "feature",
+  "targets": ["server"],
+  "requiresApps": ["server"],
+  "provides": "storage",
+  "default": false,
+  "env": {
+    "STORAGE_BACKEND": "local",
+    "AWS_STORAGE_BUCKET_NAME": "",
+    "AWS_REGION": "us-east-1",
+    "AWS_ACCESS_KEY_ID": "",
+    "AWS_SECRET_ACCESS_KEY": ""
+  },
+  "wiring": {
+    "server": {
+      "deps": ["boto3>=1.35"],
+      "settings": [
+        "STORAGE_BACKEND = env(\"STORAGE_BACKEND\", default=\"local\")",
+        "MEDIA_ROOT = BASE_DIR / \"media\"",
+        "MEDIA_URL = \"/media/\"",
+        "AWS_STORAGE_BUCKET_NAME = env(\"AWS_STORAGE_BUCKET_NAME\", default=\"\")",
+        "AWS_REGION = env(\"AWS_REGION\", default=\"us-east-1\")",
+        "AWS_ACCESS_KEY_ID = env(\"AWS_ACCESS_KEY_ID\", default=\"\")",
+        "AWS_SECRET_ACCESS_KEY = env(\"AWS_SECRET_ACCESS_KEY\", default=\"\")"
+      ]
+    }
+  },
+  "notes": [
+    "Storage: switch backends with STORAGE_BACKEND=local|s3. Call get_storage() from storage.factory."
+  ]
+}

package/modules/storage/server/storage/base.py

@@ -0,0 +1,24 @@
+from abc import ABC, abstractmethod
+from typing import BinaryIO
+
+
+class StorageProvider(ABC):
+    """
+    Swappable file-storage backend. Concrete implementations (LocalStorage,
+    S3Storage, ...) are selected at runtime via settings.STORAGE_BACKEND.
+
+    This is the reference pattern for adding a new capability to the platform:
+    define an ABC here, ship one or more implementations, and select via config.
+    """
+
+    @abstractmethod
+    def save(self, key: str, content: BinaryIO) -> str:
+        """Persist `content` under `key`; return a retrievable URL."""
+
+    @abstractmethod
+    def url(self, key: str) -> str:
+        """Return a URL for an already-stored object."""
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Remove the object at `key` (no error if absent)."""

package/modules/storage/server/storage/factory.py

@@ -0,0 +1,20 @@
+from functools import lru_cache
+
+from django.conf import settings
+from django.utils.module_loading import import_string
+
+from .base import StorageProvider
+
+# Short aliases; a fully-qualified dotted path is also accepted.
+_BACKENDS = {
+    "local": "storage.local.LocalStorage",
+    "s3": "storage.s3.S3Storage",
+}
+
+
+@lru_cache
+def get_storage() -> StorageProvider:
+    """Return the configured StorageProvider (see settings.STORAGE_BACKEND)."""
+    backend = getattr(settings, "STORAGE_BACKEND", "local")
+    dotted = _BACKENDS.get(backend, backend)
+    return import_string(dotted)()

package/modules/storage/server/storage/local.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+from typing import BinaryIO
+
+from django.conf import settings
+
+from .base import StorageProvider
+
+
+class LocalStorage(StorageProvider):
+    """Stores files on the local filesystem under MEDIA_ROOT."""
+
+    def __init__(self) -> None:
+        self.root = Path(getattr(settings, "MEDIA_ROOT", settings.BASE_DIR / "media"))
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.base_url = getattr(settings, "MEDIA_URL", "/media/")
+
+    def save(self, key: str, content: BinaryIO) -> str:
+        dest = self.root / key
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        with open(dest, "wb") as fh:
+            fh.write(content.read())
+        return self.url(key)
+
+    def url(self, key: str) -> str:
+        return f"{self.base_url.rstrip('/')}/{key}"
+
+    def delete(self, key: str) -> None:
+        (self.root / key).unlink(missing_ok=True)

package/modules/storage/server/storage/s3.py

@@ -0,0 +1,30 @@
+from typing import BinaryIO
+
+from django.conf import settings
+
+from .base import StorageProvider
+
+
+class S3Storage(StorageProvider):
+    """Stores files in an S3 bucket. Requires boto3 and AWS credentials."""
+
+    def __init__(self) -> None:
+        import boto3  # imported lazily so boto3 is only needed for the S3 backend
+
+        self.bucket = settings.AWS_STORAGE_BUCKET_NAME
+        self.client = boto3.client(
+            "s3",
+            region_name=getattr(settings, "AWS_REGION", None),
+            aws_access_key_id=getattr(settings, "AWS_ACCESS_KEY_ID", None) or None,
+            aws_secret_access_key=getattr(settings, "AWS_SECRET_ACCESS_KEY", None) or None,
+        )
+
+    def save(self, key: str, content: BinaryIO) -> str:
+        self.client.upload_fileobj(content, self.bucket, key)
+        return self.url(key)
+
+    def url(self, key: str) -> str:
+        return f"https://{self.bucket}.s3.amazonaws.com/{key}"
+
+    def delete(self, key: str) -> None:
+        self.client.delete_object(Bucket=self.bucket, Key=key)

package/modules/storage/server/tests/test_storage.py

@@ -0,0 +1,20 @@
+import io
+
+
+def test_local_storage_roundtrip(tmp_path, settings):
+    settings.MEDIA_ROOT = tmp_path
+    settings.MEDIA_URL = "/media/"
+    settings.STORAGE_BACKEND = "local"
+
+    from storage.factory import get_storage
+
+    get_storage.cache_clear()
+    store = get_storage()
+
+    url = store.save("greeting.txt", io.BytesIO(b"hi"))
+    assert url.endswith("/greeting.txt")
+    assert (tmp_path / "greeting.txt").read_bytes() == b"hi"
+
+    store.delete("greeting.txt")
+    assert not (tmp_path / "greeting.txt").exists()
+    get_storage.cache_clear()