Compare commits

...
2 Commits
Author SHA1 Message Date
Joren de Graaf 3a12d56f8b latest changes 2026-10-22 10:24:33 +02:00
Joren de Graaf 9a5210a48f link preview v1 2026-10-21 15:25:33 +02:00
62 changed files with 2352 additions and 100 deletions
+4
View File
@@ -60,3 +60,7 @@ Run checks and tests with:
```
For compiled frontend assets, run `npm run build`. Django uses Vite in development, the build manifest when present, and checked-in preview assets otherwise.
## Knowledge Library
`/knowledge/` is a separate personal link library with its own menu, data and capture API. It does not use Project Manager cards. See [Knowledge Library setup and limitations](docs/knowledge-library.md) and the [Pocket source review](docs/research/knowledge-library-pocket.md). The separate MCP `knowledge:read` scope grants contextual discovery; opt-in ntfy scheduling is available through a management command.
+240
View File
@@ -0,0 +1,240 @@
#!/usr/bin/env python3
"""Portable, dependency-free Codex usage display (Python 3.8+)."""
import argparse
import datetime as dt
import json
import math
import os
import tempfile
import hashlib
import shutil
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
def clean(value):
# Never allow API text to inject terminal control sequences.
return "".join(c for c in str(value) if c.isprintable())
def timestamp(value):
try:
if isinstance(value, str):
result = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
else:
result = dt.datetime.fromtimestamp(value, dt.timezone.utc)
return result.astimezone().strftime("%d %b %H:%M %Z")
except (ValueError, TypeError, OverflowError, OSError):
return "unknown"
def window_line(label, window, width):
if not isinstance(window, dict):
return [label + ": unavailable"]
used = window.get("usedPercent")
if isinstance(used, (int, float)) and not isinstance(used, bool) and math.isfinite(used):
used = max(0, min(100, used))
size = max(5, min(30, width - 40))
filled = round(size * used / 100)
bar = "#" * filled + "-" * (size - filled)
summary = "{} [{}] {:g}% used / {:g}% left".format(label, bar, used, 100 - used)
else:
summary = label + ": usage unknown"
reset = window.get("resetsAt")
countdown = ""
if isinstance(reset, (int, float)) and math.isfinite(reset):
seconds = max(0, int(reset - time.time()))
hours, minutes = divmod(seconds // 60, 60)
countdown = " (in {}h {:02d}m)".format(hours, minutes) if seconds else " (awaiting fresh poll)"
return [summary, " Reset: " + timestamp(reset) + countdown]
def render(data, failure, width):
lines = ["CODEX USAGE", ""]
if failure:
lines += ["OFFLINE - " + failure, "Showing last successful response" if data else "No usage data yet", ""]
if data:
stale = data.get("stale") or data.get("status") != "ok" or bool(failure)
raw = data.get("raw") or {}
if not isinstance(raw, dict):
raw = {}
allowed = raw.get("ordinaryUsageAllowed")
lines += ["State: {} | Allowed: {}".format("STALE" if stale else "OK", {True: "yes", False: "no"}.get(allowed, "unknown")),
"Last server poll: " + timestamp(data.get("last_checked")), ""]
buckets = raw.get("rateLimitsByLimitId")
if not isinstance(buckets, dict) or not buckets:
buckets = {"codex": raw.get("rateLimits")}
for name, bucket in list(buckets.items())[:20]:
if not isinstance(bucket, dict):
continue
lines.append("{} | Plan: {}".format(clean(name), clean(bucket.get("planType") or "unknown")))
for key in ("primary", "secondary"):
window = bucket.get(key)
duration = window.get("windowDurationMins") if isinstance(window, dict) else None
label = {300: "5-hour", 10080: "Weekly"}.get(duration, "{} min".format(duration) if duration else key.title())
lines.extend(window_line(label, window, width))
credits = bucket.get("credits")
if isinstance(credits, dict):
lines.append("Credits: " + ("unlimited" if credits.get("unlimited") else clean(credits.get("balance", "unknown"))))
lines.append("")
lines.append("Display: {} | Ctrl-C to quit".format(time.strftime("%H:%M:%S")))
return [clean(line)[:width] for line in lines]
def fetch(url, timeout=5):
request = urllib.request.Request(url, headers={"Accept": "application/json"})
try:
response = urllib.request.urlopen(request, timeout=timeout)
except urllib.error.HTTPError as exc:
if exc.code != 503:
raise
response = exc
with response:
body = response.read(1024 * 1024 + 1)
if len(body) > 1024 * 1024:
raise ValueError("response exceeds 1 MiB")
data = json.loads(body)
if not isinstance(data, dict) or data.get("service") != "codex":
raise ValueError("endpoint did not return Codex usage data")
return data
def cache_path(url):
digest = hashlib.sha256(url.encode("utf-8")).hexdigest()[:16]
return os.path.join(tempfile.gettempdir(), "codex-usage-{}-{}.json".format(os.getuid(), digest))
def cached_fetch(url, ttl, timeout):
path = cache_path(url)
cached = None
try:
info = os.lstat(path)
if info.st_uid == os.getuid() and info.st_mode & 0o077 == 0 and info.st_size <= 1024 * 1024:
with open(path, "r") as stream:
cached = json.load(stream)
if (not isinstance(cached, dict) or not isinstance(cached.get("data"), dict)
or not isinstance(cached.get("fetched_at"), (int, float))):
cached = None
except (OSError, ValueError, TypeError):
pass
if cached and 0 <= time.time() - cached["fetched_at"] < ttl:
return cached["data"], None
try:
data = fetch(url, timeout)
if data.get("status") == "unavailable":
return cached["data"] if cached else None, "offline"
fd, temporary = tempfile.mkstemp(prefix=".codex-usage-", dir=tempfile.gettempdir())
try:
with os.fdopen(fd, "w") as stream:
json.dump({"fetched_at": time.time(), "data": data}, stream)
os.replace(temporary, path)
finally:
if os.path.exists(temporary):
os.unlink(temporary)
return data, None
except (urllib.error.URLError, OSError, ValueError, TimeoutError):
return cached["data"] if cached else None, "offline"
def tmux_line(data, failure, compact=True, width=30):
if failure or not data:
return "C OFFLINE" if compact or width < 22 else "CODEX OFFLINE"
if data.get("stale") or data.get("status") != "ok":
return "C STALE" if compact or width < 22 else "CODEX STALE"
raw = data.get("raw")
if not isinstance(raw, dict):
return "C STALE" if compact or width < 22 else "CODEX STALE"
buckets = raw.get("rateLimitsByLimitId")
if not isinstance(buckets, dict) or not buckets:
buckets = {"codex": raw.get("rateLimits")}
values = {}
for bucket in list(buckets.values())[:20]:
if not isinstance(bucket, dict):
continue
for key in ("primary", "secondary"):
window = bucket.get(key)
if not isinstance(window, dict):
continue
duration = window.get("windowDurationMins")
used = window.get("usedPercent")
if isinstance(used, (int, float)) and not isinstance(used, bool) and math.isfinite(used):
if duration == 300:
values.setdefault("5h", round(max(0, min(100, 100 - used))))
elif duration == 10080:
values.setdefault("W", round(max(0, min(100, 100 - used))))
if not values:
return "C STALE" if compact or width < 22 else "CODEX STALE"
short = compact or width < 30
prefix = "C" if short else "CODEX"
parts = [prefix]
if "5h" in values:
parts.append(("" if short else "5h ") + "{}%".format(values["5h"]))
if "W" in values:
parts.append("W {}%".format(values["W"]))
return " ".join(parts)[:width]
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--url", default=os.environ.get("CODEX_USAGE_URL", "http://127.0.0.1:3100"), help="server base URL or full /api/usage URL (env: CODEX_USAGE_URL)")
parser.add_argument("--interval", type=float, default=10, help="display fetch interval in seconds (default: 10)")
parser.add_argument("--once", action="store_true", help="print once without terminal controls")
parser.add_argument("--tmux", action="store_true", help="print one compact status-bar line")
parser.add_argument("--compact", action="store_true", help="use short status labels")
parser.add_argument("--width", type=int, default=30, help="maximum tmux output width (default: 30)")
parser.add_argument("--cache-ttl", type=float, default=45, help="cache lifetime in seconds (default: 45)")
args = parser.parse_args()
if not math.isfinite(args.interval) or args.interval < 1:
parser.error("--interval must be at least 1 second")
if args.width < 8 or not math.isfinite(args.cache_ttl) or args.cache_ttl < 0:
parser.error("--width must be at least 8 and --cache-ttl must be nonnegative")
url = args.url.rstrip("/")
parsed = urllib.parse.urlsplit(url)
if parsed.scheme not in ("http", "https") or not parsed.hostname or parsed.query or parsed.fragment or parsed.username:
parser.error("--url must be an HTTP(S) URL without credentials, query or fragment")
if not parsed.path or parsed.path == "/":
url += "/api/usage"
if args.tmux:
data, failure = cached_fetch(url, args.cache_ttl, 2)
print(tmux_line(data, failure, True, args.width))
return 1 if failure else 0
interactive = sys.stdout.isatty() and os.environ.get("TERM") != "dumb" and not args.once
data, failure = None, None
if interactive:
sys.stdout.write("\033[?1049h\033[?25l")
try:
while True:
failure = None
try:
received, cache_failure = cached_fetch(url, 0, 5)
if cache_failure:
raise ValueError("usage API unavailable")
if received.get("status") == "unavailable":
failure = "server has no successful usage snapshot"
else:
data = received
except (urllib.error.URLError, OSError, ValueError, TimeoutError):
failure = "cannot fetch usage; check endpoint, network and service"
width, height = shutil.get_terminal_size((80, 24))
lines = render(data, failure, width)
if interactive:
sys.stdout.write("\033[H\033[2J")
lines = lines[:max(1, height - 1)]
print("\n".join(lines), flush=True)
if args.once:
return 1 if failure else 0
time.sleep(args.interval)
except KeyboardInterrupt:
return 0
finally:
if interactive:
sys.stdout.write("\033[?25h\033[?1049l")
sys.stdout.flush()
if __name__ == "__main__":
sys.exit(main())
+9 -1
View File
@@ -17,6 +17,7 @@ INSTALLED_APPS = [
"django.contrib.staticfiles",
"core",
"dashboard",
"knowledge",
'projects',
'oauth2_provider',
]
@@ -57,6 +58,13 @@ PROJECT_DOCS_MAX_FILES = int(os.environ.get('PROJECT_DOCS_MAX_FILES', '500'))
PROJECTS_ATTACHMENT_MAX_BYTES = int(os.environ.get('PROJECTS_ATTACHMENT_MAX_BYTES', 10 * 1024 * 1024))
PROJECTS_ATTACHMENT_MAX_FILES = int(os.environ.get('PROJECTS_ATTACHMENT_MAX_FILES', 50))
PROJECTS_ATTACHMENT_MAX_CARD_BYTES = int(os.environ.get('PROJECTS_ATTACHMENT_MAX_CARD_BYTES', 100 * 1024 * 1024))
KNOWLEDGE_NTFY_ENABLED = os.environ.get('KNOWLEDGE_NTFY_ENABLED', '0') == '1'
KNOWLEDGE_NTFY_URL = os.environ.get('KNOWLEDGE_NTFY_URL', '')
KNOWLEDGE_NTFY_USER_ID = os.environ.get('KNOWLEDGE_NTFY_USER_ID', '')
KNOWLEDGE_NTFY_MODE = os.environ.get('KNOWLEDGE_NTFY_MODE', 'forgotten')
KNOWLEDGE_NTFY_WEEKLY_LIMIT = int(os.environ.get('KNOWLEDGE_NTFY_WEEKLY_LIMIT', '2'))
KNOWLEDGE_NTFY_QUIET_START = int(os.environ.get('KNOWLEDGE_NTFY_QUIET_START', '22'))
KNOWLEDGE_NTFY_QUIET_END = int(os.environ.get('KNOWLEDGE_NTFY_QUIET_END', '8'))
DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
DATABASES = {'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': BASE_DIR / 'db.sqlite3'}}
CACHES = {
@@ -81,7 +89,7 @@ if not DEBUG and (not MCP_PUBLIC_URL.startswith('https://') or not OAUTH_ISSUER_
raise ImproperlyConfigured('MCP_PUBLIC_URL and OAUTH_ISSUER_URL must use HTTPS in production.')
OAUTH2_PROVIDER = {
'OIDC_ISS_ENDPOINT': f'{OAUTH_ISSUER_URL}/',
'SCOPES': {'projects:read': 'Read projects and cards', 'projects:write': 'Create and edit projects and cards'},
'SCOPES': {'projects:read': 'Read projects and cards', 'projects:write': 'Create and edit projects and cards', 'knowledge:read': 'Find saved knowledge links'},
'DEFAULT_SCOPES': ['projects:read'],
'ALLOWED_REDIRECT_URI_SCHEMES': ['http', 'https'] if DEBUG else ['https'],
'PKCE_REQUIRED': True,
+3
View File
@@ -5,6 +5,7 @@ from django.conf import settings
from oauth2_provider.urls import metadata_urlpatterns
from core import views
from projects import views as project_views
from knowledge import views as knowledge_views
urlpatterns = [
*metadata_urlpatterns,
@@ -14,6 +15,8 @@ urlpatterns = [
path('accounts/logout/', auth_views.LogoutView.as_view(), name='logout'),
path('accounts/password/change/', auth_views.PasswordChangeView.as_view(template_name='projects/form.html', success_url='/projects/profile/'), name='password_change'),
path('projects/', include('projects.urls')),
path('knowledge/', include('knowledge.urls')),
path('api/bookmarks/', knowledge_views.api_add, name='knowledge_api_add'),
path("", include('dashboard.urls')),
path("examples/today/", views.today, name="today"),
path("health/", views.health, name="health"),
+3 -2
View File
@@ -12,6 +12,7 @@
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.13.1/font/bootstrap-icons.min.css">
{% vite_assets %}
<link rel="stylesheet" href="{% static 'core/theme-bridge.css' %}">
{% block extra_head %}{% endblock %}
</head>
<body>
<a class="skip-link" href="#main">Skip to content</a>
@@ -21,7 +22,7 @@
<div class="nav-label">WORKSPACE</div>
<nav class="side-nav"><a href="{% url 'dashboard:index' %}" {% if section == 'dashboard' %}aria-current="page"{% endif %}><i class="bi bi-grid-1x2"></i><span>Dashboard</span></a></nav>
<details class="nav-submenu" {% if section == 'today' or section == 'health' or section == 'energy' or section == 'home' or section == 'showcase' %}open{% endif %}><summary><i class="bi bi-palette"></i> Design examples</summary><nav class="side-nav" aria-label="Design examples"><a href="{% url 'today' %}" {% if section == 'today' %}aria-current="page"{% endif %}>Today</a><a href="{% url 'health' %}" {% if section == 'health' %}aria-current="page"{% endif %}>Health</a><a href="{% url 'energy' %}" {% if section == 'energy' %}aria-current="page"{% endif %}>Energy</a><a href="{% url 'home' %}" {% if section == 'home' %}aria-current="page"{% endif %}>Home</a><a href="{% url 'showcase' %}" {% if section == 'showcase' %}aria-current="page"{% endif %}>Showcase</a></nav></details>
{% if user.is_authenticated %}<div class="nav-label">PROJECTS</div><nav class="side-nav"><a href="{% url 'projects:list' %}" {% if section == 'projects' %}aria-current="page"{% endif %}><i class="bi bi-kanban"></i><span>All Projects</span></a>{% for nav_project in nav_projects %}<a href="{% url 'projects:board' nav_project.id %}"><i class="bi bi-folder"></i><span>{{ nav_project.name }}</span></a>{% endfor %}</nav><div class="nav-label">ACCOUNT</div><nav class="side-nav"><a href="{% url 'projects:profile' %}" {% if section == 'profile' %}aria-current="page"{% endif %}><i class="bi bi-person-circle"></i><span>Profile</span></a></nav>{% endif %}
{% if user.is_authenticated %}<div class="nav-label">LIBRARY</div><nav class="side-nav"><a href="{% url 'knowledge:index' %}" {% if section == 'knowledge' %}aria-current="page"{% endif %}><i class="bi bi-bookmarks"></i><span>Knowledge Library</span></a></nav><div class="nav-label">PROJECTS</div><nav class="side-nav"><a href="{% url 'projects:list' %}" {% if section == 'projects' %}aria-current="page"{% endif %}><i class="bi bi-kanban"></i><span>All Projects</span></a>{% for nav_project in nav_projects %}<a href="{% url 'projects:board' nav_project.id %}"><i class="bi bi-folder"></i><span>{{ nav_project.name }}</span></a>{% endfor %}</nav><div class="nav-label">ACCOUNT</div><nav class="side-nav"><a href="{% url 'projects:profile' %}" {% if section == 'profile' %}aria-current="page"{% endif %}><i class="bi bi-person-circle"></i><span>Profile</span></a></nav>{% endif %}
<div class="nav-label secondary-label">EXPLORE</div>
<nav class="side-nav secondary-nav"><span class="nav-disabled"><i class="bi bi-stars"></i>Insights <small>SOON</small></span><span class="nav-disabled"><i class="bi bi-gear"></i>Settings <small>SOON</small></span></nav>
<div class="sidebar-bottom"><span class="demo-dot"></span><div><strong>{{ user.get_username }}</strong><small>Dashboard</small></div></div>
@@ -31,5 +32,5 @@
<main id="main" class="page-content">{% block content %}{% endblock %}</main>
</div>
</div>
<nav class="mobile-nav" aria-label="Mobile navigation"><a href="{% url 'dashboard:index' %}" {% if section == 'dashboard' %}aria-current="page"{% endif %}><i class="bi bi-layout-text-window-reverse"></i><span>Dashboard</span></a><a href="{% url 'projects:list' %}" {% if section == 'projects' %}aria-current="page"{% endif %}><i class="bi bi-kanban"></i><span>Projects</span></a><a href="{% url 'projects:profile' %}" {% if section == 'profile' %}aria-current="page"{% endif %}><i class="bi bi-person"></i><span>Profile</span></a><a href="{% url 'today' %}"><i class="bi bi-palette"></i><span>Examples</span></a></nav>
<nav class="mobile-nav" aria-label="Mobile navigation"><a href="{% url 'dashboard:index' %}" {% if section == 'dashboard' %}aria-current="page"{% endif %}><i class="bi bi-layout-text-window-reverse"></i><span>Dashboard</span></a><a href="{% url 'knowledge:index' %}" {% if section == 'knowledge' %}aria-current="page"{% endif %}><i class="bi bi-bookmarks"></i><span>Library</span></a><a href="{% url 'projects:list' %}" {% if section == 'projects' %}aria-current="page"{% endif %}><i class="bi bi-kanban"></i><span>Projects</span></a><a href="{% url 'projects:profile' %}" {% if section == 'profile' %}aria-current="page"{% endif %}><i class="bi bi-person"></i><span>Profile</span></a><a href="{% url 'today' %}"><i class="bi bi-palette"></i><span>Examples</span></a></nav>
</body></html>
+85
View File
@@ -0,0 +1,85 @@
"""Server-side adapter for the local Codex usage service."""
import json
import math
import os
import urllib.error
import urllib.request
from datetime import datetime, timezone
from django.core.cache import caches
URL = os.environ.get("DASHBOARD_CODEX_USAGE_URL", "http://192.168.1.122:3100/api/usage")
CACHE = caches["weather"]
FRESH_SECONDS = 45
STALE_SECONDS = 15 * 60
def _percentage(value):
if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
return None
return round(max(0, min(100, 100 - value)))
def _time(value):
if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
return None
try:
return datetime.fromtimestamp(value, timezone.utc)
except (ValueError, OverflowError, OSError):
return None
def _display(data):
if not isinstance(data, dict) or data.get("service") != "codex":
raise ValueError("Unexpected usage response")
raw = data.get("raw")
if not isinstance(raw, dict):
raise ValueError("Usage details unavailable")
buckets = raw.get("rateLimitsByLimitId")
if not isinstance(buckets, dict) or not buckets:
buckets = {"codex": raw.get("rateLimits")}
windows = []
for name, bucket in list(buckets.items())[:10]:
if not isinstance(bucket, dict):
continue
for key in ("primary", "secondary"):
window = bucket.get(key)
if not isinstance(window, dict):
continue
duration = window.get("windowDurationMins")
title = {300: "5 hours", 10080: "Weekly"}.get(duration, f"{duration} min" if type(duration) is int and 0 < duration < 100000 else key.title())
windows.append({
"title": title,
"remaining": _percentage(window.get("usedPercent")),
"reset": _time(window.get("resetsAt")),
"bucket": str(name)[:32],
})
checked = data.get("last_checked")
try:
checked = datetime.fromisoformat(checked.replace("Z", "+00:00")) if isinstance(checked, str) else None
except ValueError:
checked = None
return {"windows": windows, "checked": checked, "stale": bool(data.get("stale") or data.get("status") != "ok"), "allowed": raw.get("ordinaryUsageAllowed") is True}
def get_usage():
cached = CACHE.get("codex-usage:v1")
if cached and cached.get("fresh"):
return cached["display"]
try:
request = urllib.request.Request(URL, headers={"Accept": "application/json"})
with urllib.request.urlopen(request, timeout=5) as response:
body = response.read(1024 * 1024 + 1)
if len(body) > 1024 * 1024:
raise ValueError("Usage response too large")
display = _display(json.loads(body))
if display["stale"] and cached:
raise ValueError("Usage service returned stale data")
CACHE.set("codex-usage:v1", {"display": display, "fresh": True}, FRESH_SECONDS)
CACHE.set("codex-usage:last-good", display, STALE_SECONDS)
return display
except (urllib.error.URLError, OSError, ValueError, TypeError, json.JSONDecodeError):
previous = CACHE.get("codex-usage:last-good")
return {**previous, "stale": True} if previous else None
+1
View File
@@ -20,5 +20,6 @@ WIDGETS = {
WidgetType("shortcuts", "Shortcuts", "Links to useful pages", "bi-grid", "dashboard/widgets/shortcuts.html"),
WidgetType("open_meteo", "Weather forecast", "Current weather and hourly outlook from Open-Meteo", "bi-cloud-sun", "dashboard/widgets/open_meteo.html", 2),
WidgetType("buienradar", "Rain radar", "Netherlands radar and local rain forecast from Buienradar", "bi-cloud-rain", "dashboard/widgets/buienradar.html", 2),
WidgetType("codex_usage", "Codex usage", "Remaining five-hour and weekly capacity", "bi-speedometer2", "dashboard/widgets/codex_usage.html", 2),
)
}
+12 -8
View File
@@ -20,20 +20,24 @@
indicator.className = 'widget-drop-indicator';
indicator.setAttribute('aria-hidden', 'true');
grid.append(indicator);
const icons = { welcome: 'bi-sun', notes: 'bi-sticky', shortcuts: 'bi-grid', open_meteo: 'bi-cloud-sun', buienradar: 'bi-cloud-rain' };
const titles = { welcome: 'Welcome', notes: 'Quick notes', shortcuts: 'Shortcuts', open_meteo: 'Weather forecast', buienradar: 'Rain radar' };
const spans = { welcome: 2, notes: 1, shortcuts: 1, open_meteo: 2, buienradar: 2 };
const multiple = { welcome: false, notes: true, shortcuts: false, open_meteo: false, buienradar: false };
const icons = { welcome: 'bi-sun', notes: 'bi-sticky', shortcuts: 'bi-grid', open_meteo: 'bi-cloud-sun', buienradar: 'bi-cloud-rain', codex_usage: 'bi-speedometer2' };
const titles = { welcome: 'Welcome', notes: 'Quick notes', shortcuts: 'Shortcuts', open_meteo: 'Weather forecast', buienradar: 'Rain radar', codex_usage: 'Codex usage' };
const spans = { welcome: 2, notes: 1, shortcuts: 1, open_meteo: 2, buienradar: 2, codex_usage: 2 };
const multiple = { welcome: false, notes: true, shortcuts: false, open_meteo: false, buienradar: false, codex_usage: false };
function setStatus(message, error = false) {
status.textContent = message;
status.classList.toggle('error', error);
}
function widgetCards(root) {
if (!root || typeof root.querySelectorAll !== 'function') return [];
return root.matches?.('.widget-card') ? [root] : [...root.querySelectorAll('.widget-card')];
}
function cards() { return [...grid.querySelectorAll(':scope > .widget-card')]; }
function updateEmpty() { document.querySelector('#empty-layout').hidden = cards().length > 0; }
function markDirty() { dirty = true; setStatus('Unsaved layout changes'); updateEmpty(); }
function mount(root) {
const targets = root.matches?.('.widget-card') ? [root] : [...root.querySelectorAll('.widget-card')];
const targets = widgetCards(root);
targets.forEach(card => {
if (lifecycle.has(card)) return;
const controller = new AbortController();
@@ -43,13 +47,13 @@
markDirty();
}, { signal: controller.signal });
}
const widgetCleanup = card.dataset.widgetType === 'open_meteo' ? window.DashboardOpenMeteo?.mount(card) : card.dataset.widgetType === 'buienradar' ? window.DashboardBuienradar?.mount(card) : null;
const widgetCleanup = card.dataset.widgetType === 'open_meteo' ? window.DashboardOpenMeteo?.mount(card) : card.dataset.widgetType === 'buienradar' ? window.DashboardBuienradar?.mount(card) : card.dataset.widgetType === 'codex_usage' ? window.DashboardCodexUsage?.mount(card) : null;
lifecycle.set(card, () => { controller.abort(); widgetCleanup?.(); });
card.dispatchEvent(new CustomEvent('dashboard:widget-mounted', { bubbles: true }));
});
}
function unmount(root) {
const targets = root.matches?.('.widget-card') ? [root] : [...root.querySelectorAll('.widget-card')];
const targets = widgetCards(root);
targets.forEach(card => { lifecycle.get(card)?.(); lifecycle.delete(card); card.dispatchEvent(new CustomEvent('dashboard:widget-unmounted', { bubbles: true })); });
}
document.addEventListener('htmx:beforeCleanupElement', event => unmount(event.detail.elt));
@@ -103,7 +107,7 @@
}
function widgetMarkup(type) {
const icon = icons[type], title = titles[type];
const body = type === 'open_meteo' ? document.querySelector('#open-meteo-widget-template').innerHTML : type === 'buienradar' ? document.querySelector('#buienradar-widget-template').innerHTML : type === 'notes' ? '<p class="note-preview">Add a note in widget settings.</p>' : type === 'welcome' ? '<p>Welcome to your dashboard. Arrange the cards to fit your day.</p><p class="widget-muted">This is a placeholder widget. Live data widgets will be added separately.</p>' : '<nav class="widget-shortcuts" aria-label="Quick links"><a href="/projects/">Projects ↗</a><a href="/examples/today/">Design examples ↗</a></nav>';
const body = type === 'open_meteo' ? document.querySelector('#open-meteo-widget-template').innerHTML : type === 'buienradar' ? document.querySelector('#buienradar-widget-template').innerHTML : type === 'codex_usage' ? document.querySelector('#codex-usage-widget-template').innerHTML : type === 'notes' ? '<p class="note-preview">Add a note in widget settings.</p>' : type === 'welcome' ? '<p>Welcome to your dashboard. Arrange the cards to fit your day.</p><p class="widget-muted">This is a placeholder widget. Live data widgets will be added separately.</p>' : '<nav class="widget-shortcuts" aria-label="Quick links"><a href="/projects/">Projects ↗</a><a href="/examples/today/">Design examples ↗</a></nav>';
return `<header class="widget-card-head"><div><i class="bi ${icon}" aria-hidden="true"></i><h2>${title}</h2></div><div class="widget-controls"><button type="button" data-move="left" aria-label="Move ${title} earlier" title="Move earlier">←</button><button type="button" data-move="right" aria-label="Move ${title} later" title="Move later">→</button><button type="button" data-span-toggle aria-label="Resize ${title}" title="Resize">↔</button><button type="button" data-settings-toggle aria-label="Settings for ${title}" title="Settings"><i class="bi bi-sliders"></i></button><button type="button" data-remove aria-label="Remove ${title}" title="Remove"><i class="bi bi-x-lg"></i></button><span class="drag-handle" draggable="true" aria-hidden="true"><i class="bi bi-grip-vertical"></i></span></div></header><div class="widget-body">${body}</div><div class="widget-settings" hidden>${type === 'notes' ? '<label>Note text <textarea data-setting="text" maxlength="1000"></textarea></label>' : '<p>No settings for this widget.</p>'}</div>`;
}
function add(type, before = null) {
@@ -0,0 +1 @@
.codex-usage{min-width:0}.codex-usage-top,.codex-usage-footer{display:flex;justify-content:space-between;align-items:center;gap:12px}.codex-usage-top{margin-bottom:18px}.codex-usage-state{display:inline-flex;align-items:center;gap:7px;font-size:12px;font-weight:700;color:var(--accent)}.codex-usage-state:before{content:"";width:7px;height:7px;border-radius:50%;background:currentColor}.codex-usage-state.is-stale,.codex-usage-state.is-limited{color:var(--text-secondary)}.codex-usage-state.is-error{color:var(--negative)}.codex-usage-checked,.codex-usage-reset,.codex-usage-footer,.codex-usage-note{font-size:12px;color:var(--text-secondary)}.codex-usage-gauges{display:grid;grid-template-columns:repeat(auto-fit,minmax(145px,1fr));gap:20px}.codex-usage-window{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center;padding:12px;border-radius:var(--radius-md);background:var(--surface-secondary)}.codex-usage-ring{width:116px;aspect-ratio:1;border-radius:50%;display:grid;place-items:center;background:conic-gradient(var(--accent) var(--usage-progress,0%),var(--border) 0);margin-bottom:5px}.codex-usage-ring-inner{width:88px;aspect-ratio:1;border-radius:50%;display:flex;flex-direction:column;align-items:center;justify-content:center;background:var(--surface-secondary);color:var(--text)}.codex-usage-ring-inner strong{font-size:26px;line-height:1.1}.codex-usage-ring-inner small{font-size:11px;color:var(--text-secondary)}.codex-usage-label{font-size:13px;color:var(--text)}.codex-usage-reset{line-height:1.4}.codex-usage-note{margin:14px 0 0!important}.codex-usage-footer{border-top:1px solid var(--border);margin:16px 0 0!important;padding-top:10px}.codex-usage-panel[aria-busy="true"]{opacity:.75}@media(max-width:420px){.codex-usage-gauges{grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}.codex-usage-window{padding:10px 4px}.codex-usage-ring{width:96px}.codex-usage-ring-inner{width:73px}.codex-usage-ring-inner strong{font-size:22px}}
+26
View File
@@ -0,0 +1,26 @@
(() => {
window.DashboardCodexUsage = {
mount(card) {
const root = card.querySelector('[data-codex-usage]');
if (!root) return () => {};
const panel = root.querySelector('.codex-usage-panel');
const next = root.querySelector('[data-next-refresh]');
const controller = new AbortController();
let due = Date.now() + 60000;
function updateTimes() {
next.dateTime = new Date(due).toISOString();
next.textContent = new Date(due).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
panel.querySelectorAll('time[datetime]').forEach(time => {
const date = new Date(time.dateTime);
if (!Number.isNaN(date.getTime())) time.textContent = date.toLocaleString([], { day: 'numeric', month: 'short', hour: 'numeric', minute: '2-digit' });
});
}
panel.addEventListener('htmx:beforeRequest', () => { panel.setAttribute('aria-busy', 'true'); }, { signal: controller.signal });
panel.addEventListener('htmx:afterRequest', () => { panel.setAttribute('aria-busy', 'false'); }, { signal: controller.signal });
panel.addEventListener('htmx:afterSwap', () => { due = Date.now() + 60000; updateTimes(); }, { signal: controller.signal });
updateTimes();
window.htmx?.process(panel);
return () => { controller.abort(); };
},
};
})();
+3 -2
View File
@@ -1,4 +1,4 @@
{% extends 'core/base.html' %}{% load static %}{% block content %}<link rel="stylesheet" href="{% static 'dashboard/builder.css' %}"><link rel="stylesheet" href="{% static 'dashboard/open_meteo.css' %}"><link rel="stylesheet" href="{% static 'dashboard/buienradar.css' %}"><link rel="stylesheet" href="{% static 'dashboard/companion.css' %}">
{% extends 'core/base.html' %}{% load static %}{% block content %}<link rel="stylesheet" href="{% static 'dashboard/builder.css' %}"><link rel="stylesheet" href="{% static 'dashboard/open_meteo.css' %}"><link rel="stylesheet" href="{% static 'dashboard/buienradar.css' %}"><link rel="stylesheet" href="{% static 'dashboard/codex_usage.css' %}?v=20261022"><link rel="stylesheet" href="{% static 'dashboard/companion.css' %}">
<div class="page-heading dashboard-heading"><div><div class="eyebrow"><span class="eyebrow-line"></span> YOUR WORKSPACE</div><h1>{{ title }}<span class="heading-period">.</span></h1><p>Make this space your own with a few useful widgets.</p></div><div class="dashboard-actions"><button class="button secondary" id="catalogue-toggle" type="button" aria-controls="widget-catalogue" aria-expanded="false" aria-label="Open widget catalogue"><i class="bi bi-gear"></i> Widgets</button><button class="button secondary" id="reset-layout" type="button" hidden>Reset</button><button class="button primary" id="edit-layout" type="button">Edit layout</button></div></div>
<div id="layout-status" class="layout-status" role="status" aria-live="polite">Layout saved</div><button class="button secondary" id="companion-toggle" type="button" aria-pressed="false">Show companion</button>
<div class="dashboard-pages" aria-label="Dashboard pages"><a href="{% url 'dashboard:index' %}" {% if dashboard_page == 'overview' %}aria-current="page"{% endif %}>Overview</a><a href="{% url 'dashboard:page' 'personal' %}" {% if dashboard_page == 'personal' %}aria-current="page"{% endif %}>Personal</a></div>
@@ -8,7 +8,8 @@
<p id="empty-layout" class="empty-layout" {% if instances %}hidden{% endif %}>This page is empty. Choose <strong>Edit layout</strong>, then add a widget.</p>
<template id="open-meteo-widget-template">{% include 'dashboard/widgets/open_meteo.html' %}</template>
<template id="buienradar-widget-template">{% include 'dashboard/widgets/buienradar.html' %}</template>
<template id="codex-usage-widget-template">{% include 'dashboard/widgets/codex_usage.html' %}</template>
<aside id="widget-catalogue" class="widget-catalogue" aria-label="Widget catalogue" aria-hidden="true" inert><div class="catalogue-head"><div><span class="eyebrow">BUILD YOUR PAGE</span><h2>Widgets</h2></div><button type="button" id="catalogue-close" class="button ghost" aria-label="Close widget catalogue"><i class="bi bi-x-lg"></i></button></div><label for="widget-search">Search widgets</label><input id="widget-search" type="search" placeholder="Search by name or description"><div class="catalogue-list">{% for widget in catalogue %}<div class="catalogue-entry" draggable="true" data-widget-type="{{ widget.id }}" data-title="{{ widget.title|lower }}" data-description="{{ widget.description|lower }}"><i class="bi {{ widget.icon }}" aria-hidden="true"></i><div><strong>{{ widget.title }}</strong><small>{{ widget.description }}</small></div><button type="button" class="button secondary" data-add="{{ widget.id }}">Add</button></div>{% endfor %}</div><p class="catalogue-hint">Drag onto a dashed slot, or use Add and the Move controls. Changes save when you select Done.</p></aside><div id="catalogue-backdrop" class="catalogue-backdrop" hidden></div>
{{ catalogue|length|json_script:"widget-count" }}
<script src="{% static 'dashboard/location.js' %}" defer></script><script src="{% static 'dashboard/open_meteo.js' %}" defer></script><script src="{% static 'dashboard/buienradar.js' %}" defer></script><script src="{% static 'dashboard/builder.js' %}" defer></script><script src="{% static 'dashboard/companion.js' %}" defer></script><script src="{% static 'dashboard/companion-dashboard.js' %}" defer></script>
<script src="{% static 'dashboard/location.js' %}" defer></script><script src="{% static 'dashboard/open_meteo.js' %}" defer></script><script src="{% static 'dashboard/buienradar.js' %}" defer></script><script src="{% static 'dashboard/codex_usage.js' %}?v=20261022" defer></script><script src="{% static 'dashboard/builder.js' %}?v=20261022" defer></script><script src="{% static 'dashboard/companion.js' %}" defer></script><script src="{% static 'dashboard/companion-dashboard.js' %}" defer></script><script src="https://unpkg.com/htmx.org@2.0.4" defer></script>
{% endblock %}
@@ -0,0 +1,5 @@
{% if usage %}
<div class="codex-usage-top"><span class="codex-usage-state {% if usage.stale %}is-stale{% elif not usage.allowed %}is-limited{% endif %}">{% if usage.stale %}Stale data{% elif not usage.allowed %}Usage limited{% else %}Live usage{% endif %}</span>{% if usage.checked %}<span class="codex-usage-checked">Checked <time datetime="{{ usage.checked|date:'c' }}">{{ usage.checked|date:'j M H:i' }}</time></span>{% endif %}</div>
{% if usage.windows %}<div class="codex-usage-gauges">{% for window in usage.windows %}<div class="codex-usage-window"><div class="codex-usage-ring" {% if window.remaining is not None %}style="--usage-progress:{{ window.remaining }}%"{% endif %} role="img" aria-label="{{ window.bucket }} {{ window.title }}: {% if window.remaining is not None %}{{ window.remaining }} percent remaining{% else %}remaining usage unknown{% endif %}"><div class="codex-usage-ring-inner"><strong>{% if window.remaining is not None %}{{ window.remaining }}%{% else %}—{% endif %}</strong><small>left</small></div></div><strong class="codex-usage-label">{{ window.title }}</strong>{% if window.reset %}<span class="codex-usage-reset">Resets <time datetime="{{ window.reset|date:'c' }}">{{ window.reset|date:'j M H:i' }}</time></span>{% else %}<span class="codex-usage-reset">Reset time unavailable</span>{% endif %}</div>{% endfor %}</div>{% else %}<p class="codex-usage-state">No usage windows available.</p>{% endif %}
{% if usage.stale %}<p class="codex-usage-note">Showing the last available snapshot. The next refresh will retry.</p>{% endif %}
{% else %}<p class="codex-usage-state is-error" role="status">Usage is unavailable right now. The next refresh will retry.</p>{% endif %}
@@ -0,0 +1,6 @@
{% load static %}<div class="codex-usage" data-codex-usage>
<div class="codex-usage-panel" hx-get="{% url 'dashboard:codex_usage' %}" hx-trigger="load, every 60s" hx-swap="innerHTML" aria-busy="true">
<p class="codex-usage-state" role="status">Loading usage…</p>
</div>
<p class="codex-usage-footer">Next refresh <time data-next-refresh>soon</time></p>
</div>
+31
View File
@@ -14,6 +14,7 @@ from .models import DashboardLayout
from .views import validate_widgets
from .weather import ForecastUnavailable, coordinates, get_forecast
from .buienradar import RainUnavailable, get_rain, parse_forecast
from .codex_usage import _display, get_usage
class DashboardTests(TestCase):
@@ -130,6 +131,36 @@ class DashboardTests(TestCase):
def test_buienradar_stale_fallback(self):
cache = caches["weather"]
cache.clear()
def test_codex_usage_registry_and_private_panel(self):
from .registry import WIDGETS
self.assertIn("codex_usage", WIDGETS)
item = {"id": str(uuid.uuid4()), "type": "codex_usage", "span": 2, "settings": {}, "visible": True}
self.assertEqual(validate_widgets([item])[0]["type"], "codex_usage")
with self.assertRaises(ValueError):
validate_widgets([item, {**item, "id": str(uuid.uuid4())}])
url = reverse("dashboard:codex_usage")
self.assertEqual(self.client.get(url).status_code, 302)
self.client.force_login(self.one)
with patch("dashboard.views.get_usage", return_value={"windows": [{"title": "5 hours", "remaining": 17, "reset": None, "bucket": "codex"}], "checked": None, "stale": False, "allowed": True}):
response = self.client.get(url)
self.assertContains(response, "17%")
self.assertContains(response, "Reset time unavailable")
def test_codex_usage_normalizes_live_shape_and_stale_cache(self):
raw = {"service": "codex", "status": "ok", "last_checked": "2026-10-21T22:56:50.106Z", "raw": {"ordinaryUsageAllowed": True, "accountId": "private", "rateLimitsByLimitId": {"codex": {"primary": {"usedPercent": 83, "windowDurationMins": 300, "resetsAt": 1792625545}, "secondary": {"usedPercent": 60, "windowDurationMins": 10080, "resetsAt": 1793101162}}}}}
display = _display(raw)
self.assertEqual([window["remaining"] for window in display["windows"]], [17, 40])
self.assertNotIn("private", str(display))
cache = caches["weather"]
cache.delete("codex-usage:v1")
cache.delete("codex-usage:last-good")
cache.set("codex-usage:last-good", display, 60)
with patch("dashboard.codex_usage.urllib.request.urlopen", side_effect=OSError("offline")):
fallback = get_usage()
self.assertTrue(fallback["stale"])
self.assertEqual(fallback["windows"][0]["remaining"], 17)
cache.delete("codex-usage:last-good")
key = hashlib.sha256(b"buienradar:v1:52.96:5.92").hexdigest()
cache.set(f"stale:{key}", {"points": [{"time": "2026-10-14T23:55:00+02:00", "mm_per_hour": 0, "label": "None"}], "fetched_at": "2026-10-14T21:55:00+00:00"}, 60)
with patch("dashboard.buienradar.request_rain", side_effect=OSError("offline")):
+2 -1
View File
@@ -4,8 +4,9 @@ from . import views
app_name = "dashboard"
urlpatterns = [
path("", views.index, name="index"),
path("dashboard/<slug:page>/", views.page, name="page"),
path("dashboard/<slug:page>/layout/", views.layout_api, name="layout"),
path("dashboard/weather/open-meteo/", views.open_meteo_api, name="open_meteo"),
path("dashboard/weather/buienradar/", views.buienradar_api, name="buienradar"),
path("dashboard/codex-usage/", views.codex_usage_panel, name="codex_usage"),
path("dashboard/<slug:page>/", views.page, name="page"),
]
+7
View File
@@ -12,6 +12,7 @@ from .models import DashboardLayout
from .registry import WIDGETS
from .weather import ForecastUnavailable, get_forecast
from .buienradar import RainUnavailable, get_rain
from .codex_usage import get_usage
PAGES = {"overview": "Overview", "personal": "Personal"}
@@ -120,3 +121,9 @@ def buienradar_api(request):
except RainUnavailable as exc:
return JsonResponse({"error": str(exc)}, status=503)
return JsonResponse(rain)
@login_required
@require_http_methods(["GET"])
def codex_usage_panel(request):
return render(request, "dashboard/widgets/_codex_usage_panel.html", {"usage": get_usage()})
@@ -0,0 +1,11 @@
[Unit]
Description=Fetch bounded Knowledge Library preview metadata
After=network-online.target
[Service]
Type=oneshot
WorkingDirectory=/home/jorenmartijn/Desktop/django_dashboard
EnvironmentFile=-%h/.config/common-ground/env
ExecStart=/home/jorenmartijn/Desktop/django_dashboard/.venv-host/bin/python manage.py fetch_knowledge_metadata --limit 5
TimeoutStartSec=120
@@ -0,0 +1,11 @@
[Unit]
Description=Process Knowledge Library preview metadata each minute
[Timer]
OnBootSec=1min
OnUnitActiveSec=1min
AccuracySec=15s
Unit=common-ground-knowledge-metadata.service
[Install]
WantedBy=timers.target
+1 -1
View File
@@ -1,6 +1,6 @@
# Card and progress-note attachments
Attachments are stored as private files with metadata in `CardAttachment`. A file belongs to one card, and optionally one `CardComment` progress note on that card. Moving a card keeps its files. Deleting a note or card cascades to its attachment records and removes stored files. Explicit deletion also removes the bytes. Files are snapshots; `source_path` and `source_commit` record provenance but do not cause automatic refresh.
Attachments are stored as private files with metadata in `CardAttachment`. A file belongs to one card, and optionally one `CardComment` progress note on that card. Moving a card between project boards keeps the same card and comment records, so its files and progress-note files remain attached and accessible to destination project members. Deleting a note or card cascades to its attachment records and removes stored files. Explicit deletion also removes the bytes. Files are snapshots; `source_path` and `source_commit` record provenance but do not cause automatic refresh.
## Configuration
+9
View File
@@ -0,0 +1,9 @@
# Codex usage widget
Add **Codex usage** from the dashboard widget catalogue. The card shows remaining capacity in circular gauges for each usage window returned by the service, plus each window's reset time. Times are converted to the browser's local timezone. The footer shows the next scheduled refresh time.
The authenticated Django endpoint `dashboard/codex-usage/` requests `http://192.168.1.122:3100/api/usage` by default. Set `DASHBOARD_CODEX_USAGE_URL` on the Django server to override it. The browser receives only normalized display fields; the upstream account ID and full response stay server-side. The service response is cached for 45 seconds in the shared file cache. The browser polls the HTML partial with HTMX every 60 seconds while the widget is mounted.
If the service fails, the last successful display remains available for up to 15 minutes and is visibly marked stale. After that, the card shows an unavailable state. A response explicitly marked stale is also labeled. The widget never guesses missing percentages or reset times. Removing the card stops its HTMX polling with the DOM element; adding it again starts a new poll.
The dashboard template adds a version query to the widget stylesheet and scripts, including `builder.js`. This forces browsers with an older cached widget catalogue script to load the current type registry and Add handler after deployment.
+43
View File
@@ -0,0 +1,43 @@
# Knowledge Library
Knowledge Library is a separate Django app under `/knowledge/`, with its own models, routes and menu entry. It does not create or modify Project Manager cards. See [Pocket source review and schema rationale](research/knowledge-library-pocket.md).
## Capture
Run migrations, sign in, and open **Knowledge Library → Capture tokens**. The token is displayed only when created and can be revoked there. An Apple Shortcut can send a JSON POST to `/api/bookmarks/` with `Authorization: Bearer <token>` and `Content-Type: application/json`:
```json
{"url":"https://example.org/article","title":"Optional title","saved_reason":"Why this matters"}
```
The endpoint returns `201` for a new item or `200` with `duplicate: true` for an existing URL. URLs are normalized conservatively: scheme/host case and fragment are ignored, while path and query are preserved. Capture is owner-scoped and limited to 30 posts per token per minute. Token values are stored only as SHA-256 hashes. Browser forms use Django session authentication and CSRF; bearer tokens are accepted only at the capture endpoint. A saved link remains available when metadata has not been fetched.
New items show `pending` until `.venv/bin/python manage.py fetch_knowledge_metadata --limit 20` runs. A one-minute user-systemd timer is supplied in `deploy/systemd/common-ground-knowledge-metadata.{service,timer}`; link and enable it after the application and migration are deployed. The timer processes at most five links per run. The page polls pending cards for two minutes and replaces them when the worker completes. On this host, link both files from `deploy/systemd/` into `~/.config/systemd/user/`, run `systemctl --user daemon-reload`, then `systemctl --user enable --now common-ground-knowledge-metadata.timer` after migrations. Use `flatpak-spawn --host` before `systemctl` when running inside the Codex Flatpak shell. It checks every DNS answer and redirect target, pins the outbound connection to a validated public IP, restricts ports, limits redirects, total time and response bytes, and extracts Open Graph metadata first, then Twitter Card metadata, then HTML title/description and favicon. It stores no page HTML. YouTube URLs use the fixed YouTube oEmbed JSON endpoint; returned embed HTML is ignored. Failed fetches show `error` and use exponential retry, capped at five attempts. No arbitrary URL is fetched during the save request. Fetched HTML is never rendered or stored as article content.
## MCP discovery
Authorize the MCP client with `knowledge:read` to expose `find_relevant_saved_interests(context)`. It returns at most three links belonging to the OAuth user. The current matching is intentionally simple and deterministic; it searches saved titles, descriptions, reasons and tags, and can return no matches. It does not inspect conversations on its own. Clients must choose to call it, so automatic invocation cannot be guaranteed. Existing `projects:read` scope does not grant library access.
## ntfy prototype
TasksNest's `planner/services/notifications.py` at commit `743785c2e0e41514c8dd18c035b7ea21716d87de` uses a UTF-8 HTTP POST with a `Title` header; this app follows that transport convention. Configure the server environment, outside Git:
```sh
KNOWLEDGE_NTFY_ENABLED=1
KNOWLEDGE_NTFY_URL=https://your-ntfy-host/private-topic
KNOWLEDGE_NTFY_USER_ID=<owner database ID>
KNOWLEDGE_NTFY_MODE=forgotten
KNOWLEDGE_NTFY_WEEKLY_LIMIT=2
KNOWLEDGE_NTFY_QUIET_START=22
KNOWLEDGE_NTFY_QUIET_END=8
```
The feature is off by default. Run `.venv/bin/python manage.py rediscover_knowledge` from a scheduled service (for example, once daily); no timer is installed by the app. Modes are `forgotten`, `random`, and `timely` (recent saved item, not a claim that its price or availability changed). Items must be at least two days old, are cooled down for 14 days after delivery, and the weekly limit defaults to two. Quiet hours use Django's configured local timezone. The notification includes the original source URL and saved reason. Delivery events are recorded after success; failed sends do not consume a slot. Snooze and dismissal controls are future work.
## Current limits
This checkout uses SQLite. Search is scoped by owner but does not yet use PostgreSQL full-text search or semantic matching. The browser page supports save, search, edit of user title/description, preview/plain/embed modes, manual refresh and archive. Publisher metadata remains separate from user edits, so refresh preserves overrides. YouTube playback is opt-in and uses only a constructed `youtube-nocookie.com` URL after a click; no provider HTML or iframe loads automatically. Preview images load directly from their publisher with no referrer; broken images fall back to text. Editing tags, reasons, and snooze needs a later UI pass. No article body is stored. No project conversion happens automatically.
## Preview implementation choices
The current project uses SQLite, so preview metadata is cached on the owner-scoped `SavedItem` row rather than in PostgreSQL. A later PostgreSQL deployment can use the same migration fields and add a full-text index. `micawber` offers general oEmbed provider discovery, Beautiful Soup offers broader HTML parsing, and `httpx` offers a higher-level HTTP client. This feature needs only one allowlisted oEmbed provider and a narrow set of head tags. The standard-library parser and DNS-pinned connection avoid extra dependencies and make SSRF checks explicit. [Open Graph image alt and site name](https://ogp.me/) and the [YouTube oEmbed endpoint](https://oembed.org/providers/youtube) informed field mapping; [YouTube Help](https://support.google.com/youtube/answer/171780) documents the privacy-enhanced embed domain.
+19
View File
@@ -0,0 +1,19 @@
# Project board
The project board is a Django page backed by the existing project, card, and activity records. The responsive header shows repository metadata, completion progress, and permission-gated project actions. Completion uses active cards and safely reports zero percent when the project has no active cards.
Search and the filter sheet keep their state in GET parameters (`q`, `priority`, `card_type`, `column`, `assignee`, `tag`, and `archived`). Filter changes refresh the board through HTMX; a normal GET remains available. Archived cards are a separate toggle. Project access is resolved by `services.project_for`, while edit controls are shown only to the owner and project editors.
Columns scroll horizontally on narrow screens and snap into view. Cards retain SortableJS drag behavior for pointer and touch users, and keep column and ordering controls as keyboard alternatives. The project activity panel shows the latest three events in human-readable form and can expand to older events. The shared five-destination mobile navigation remains the source for mobile app navigation.
Styles live in `projects/static/projects/board_mobile.css` and use the shared theme variables. No database schema or new client dependency is required.
## Projects index
The authenticated Projects index lists only projects available to the current user. Active and archived views, search across project and card content, and pagination remain query-driven. Search responses can replace the project-card list through HTMX. Each project card shows total cards, active-card completion, repository access, and links to its board and documentation. Counts are calculated from existing project and card records; they do not require additional stored fields.
## Card detail
Selecting a card opens a responsive detail page with the Markdown description, raw Markdown disclosure, card properties, attachments, progress notes, and the full activity history. The page uses the same theme variables and mobile navigation. Edit, archive/restore, uploads, note creation, and cross-project moves are limited to project owners and editors; viewers can read the card and its history.
The card action menu can move a card to another active project the current editor may edit. Its accessible confirmation dialog selects an active destination column, defaulting to that project's default column. The move keeps the card UUID and URL, card timestamps, description, revisions, comments, attachments, and activity history. It maps tags to same-named destination tags and clears unmatched tags; an assignee without destination access is cleared. Both outcomes appear in the success message. The move is one transaction, checks the submitted card revision, adds a revision, records source and destination activity, and rejects archived projects, invalid columns, stale forms, and inaccessible destinations. The MCP `cards_move_project` tool calls the same service, requires a destination project UUID and expected revision, and supports an optional idempotency key. The existing `cards_move` tool continues to move a card within its current project.
+22
View File
@@ -0,0 +1,22 @@
# Knowledge library: Pocket source review and design
Reviewed 2026-10-20 before implementing the library data layer. Source inspected at [Pocket/pocket-monorepo](https://github.com/Pocket/pocket-monorepo/tree/5e5268fd92e997bb3350eaeafb54285238178a8e), commit `5e5268fd92e997bb3350eaeafb54285238178a8e`.
## Verified upstream patterns
- [`servers/list-api/schema.graphql`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/list-api/schema.graphql) defines `SavedItem` as a user's saved URL with title, tags, archive/favorite state, timestamps and a linked underlying item. That separation is useful: the saved reason and state belong to the user, while fetched page metadata is fallible.
- [`servers/list-api/src/dataService/savedItemsService.ts`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/list-api/src/dataService/savedItemsService.ts) scopes saved-item queries by `user_id` and looks up `given_url` separately from the resolved item. [`servers/list-api/src/models/SavedItem.ts`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/list-api/src/models/SavedItem.ts) handles archive, tags and soft deletion. The published monorepo does not provide a complete migration history for the legacy list database, so its exact indexes and constraints cannot be inferred from the API alone.
- [`servers/list-api/src/externalCaller/parserCaller.ts`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/list-api/src/externalCaller/parserCaller.ts) calls a separate parser. [`servers/parser-graphql-wrapper/src/databases/pocketMetadataStore.ts`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/parser-graphql-wrapper/src/databases/pocketMetadataStore.ts) illustrates metadata storage. The many service and cache layers are excessive for this personal Django app.
- [`lambdas/user-list-search-corpus-parser-hydration`](https://github.com/Pocket/pocket-monorepo/tree/5e5268fd92e997bb3350eaeafb54285238178a8e/lambdas/user-list-search-corpus-parser-hydration) shows separate search hydration. Local title, URL, description, notes and tag search should come first.
## License and reuse boundary
The monorepo root [`LICENSE`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/LICENSE) is Apache-2.0, but [`servers/client-api/LICENSE`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/client-api/LICENSE) is an MIT notice credited to Apollo Graph, Inc. Dependencies retain their own licenses. Apache-2.0 copying would require preserving license and applicable notices, marking changes, and observing its patent terms. Third-party article text and images are not granted by a source-code license. Pocket names and marks are not licensed as product branding. No upstream code or assets are copied here; the implementation uses independently written Django models and services based on general patterns. The [Pocket iOS repository](https://github.com/Pocket/pocket-ios) contains a Share extension, but that native code is unnecessary for an Apple Shortcut sending a POST.
## Proposed local schema and pipeline
Use a separate `knowledge` app. `SavedItem` has owner, original URL, conservative URL key, optional canonical URL, user title, extracted title/description/thumbnail, notes, tags, saved and deferral reasons, status, read date, metadata state, and exposure dates. Enforce `(owner, url_key)` uniqueness and index `(owner, status, created_at)` and `(owner, last_surfaced_at)`. `CaptureToken` stores only a hash, owner, scope, creation/revocation dates. `RediscoveryEvent` records attempted/delivered resurfacing and feedback. Do not model project cards as saved items. Optional project association can come later through an explicit link.
Save must commit without network access. A separate bounded worker may fetch metadata after validating each DNS resolution and redirect target against private, loopback, link-local and reserved addresses; cap redirects, time, response bytes and content type. Never render fetched HTML. Keep metadata pending until the separately invoked bounded worker runs. A failed fetch becomes an explicit error state. No arbitrary URL is fetched in the capture request. The current checkout uses SQLite, so local search uses indexed owner filtering plus simple text matching; PostgreSQL `SearchVector` and a GIN index are a deployment upgrade, not an assumed current capability. Do not add pgvector until relevance tests show a need.
MCP contextual retrieval uses only the authenticated owner's records, a relevance threshold, a maximum of three results, and a recent-exposure cooldown. A tool description can invite proactive calls, but the MCP server cannot compel ChatGPT to invoke it. ntfy scheduling must be opt-in with quiet hours, a low weekly budget, delivery history and duplicate suppression. The TasksNest ntfy implementation is outside this checkout and must be inspected before reusing its exact transport conventions.
View File
+6
View File
@@ -0,0 +1,6 @@
from django.apps import AppConfig
class KnowledgeConfig(AppConfig):
default_auto_field = 'django.db.models.BigAutoField'
name = 'knowledge'
View File
@@ -0,0 +1,40 @@
from django.core.management.base import BaseCommand
from django.db.models import Q
from django.utils import timezone
from datetime import timedelta
from knowledge.metadata import MetadataError, fetch_metadata
from knowledge.models import SavedItem
class Command(BaseCommand):
help = 'Fetch safe, bounded metadata for pending saved links.'
def add_arguments(self, parser):
parser.add_argument('--limit', type=int, default=20)
def handle(self, *args, **options):
total = 0
now = timezone.now()
candidates = SavedItem.objects.filter(metadata_attempts__lt=5).filter(
Q(metadata_status=SavedItem.MetadataStatus.PENDING) |
Q(metadata_status=SavedItem.MetadataStatus.ERROR, metadata_retry_at__lte=now)).order_by('created_at')
for item in candidates[:max(0, min(options['limit'], 100))]:
item.metadata_attempts += 1
try:
fields = fetch_metadata(item.original_url)
for name, value in fields.items():
setattr(item, name, value)
item.metadata_status = SavedItem.MetadataStatus.READY
item.metadata_error = ''
item.metadata_fetched_at = timezone.now()
item.metadata_retry_at = None
item.save(update_fields=[*fields, 'metadata_status', 'metadata_error', 'metadata_fetched_at',
'metadata_retry_at', 'metadata_attempts', 'updated_at'])
except MetadataError as exc:
item.metadata_status = SavedItem.MetadataStatus.ERROR
item.metadata_error = str(exc)[:200]
item.metadata_retry_at = timezone.now() + timedelta(minutes=min(5 * 2 ** (item.metadata_attempts - 1), 1440))
item.save(update_fields=['metadata_status', 'metadata_error', 'metadata_retry_at',
'metadata_attempts', 'updated_at'])
total += 1
self.stdout.write(f'Processed {total} link(s).')
@@ -0,0 +1,12 @@
from django.core.management.base import BaseCommand, CommandError
from knowledge.notifications import NotificationError, rediscover_once
class Command(BaseCommand):
help = 'Send at most one eligible Knowledge Library ntfy reminder, subject to opt-in, quiet hours and weekly limit.'
def handle(self, *args, **options):
try:
self.stdout.write(rediscover_once())
except NotificationError as exc:
raise CommandError(str(exc)) from exc
+212
View File
@@ -0,0 +1,212 @@
"""Bounded, DNS-pinned preview metadata for public web pages and YouTube."""
import http.client
import ipaddress
import json
import re
import socket
import ssl
import time
from html.parser import HTMLParser
from urllib.parse import parse_qs, urlencode, urljoin, urlsplit
from django.core.exceptions import ValidationError
from .services import clean_url
MAX_HTML_BYTES = 512 * 1024
MAX_JSON_BYTES = 16 * 1024
MAX_REDIRECTS = 3
VIDEO_ID = re.compile(r'^[A-Za-z0-9_-]{11}$')
class MetadataError(Exception):
pass
class MetadataParser(HTMLParser):
def __init__(self):
super().__init__(convert_charrefs=True)
self.title_parts = []
self.in_title = False
self.meta = {}
self.icons = []
self.canonical = ''
def handle_starttag(self, tag, attrs):
props = dict(attrs)
if tag == 'title':
self.in_title = True
elif tag == 'meta':
name = (props.get('property') or props.get('name') or '').lower().strip()
value = (props.get('content') or '').strip()
if name and value and name not in self.meta:
self.meta[name] = value
elif tag == 'link':
rel = (props.get('rel') or '').lower().split()
if 'canonical' in rel and not self.canonical:
self.canonical = props.get('href') or ''
if 'icon' in rel and props.get('href'):
self.icons.append(props['href'])
def handle_endtag(self, tag):
if tag == 'title':
self.in_title = False
def handle_data(self, data):
if self.in_title and sum(map(len, self.title_parts)) < 300:
self.title_parts.append(data)
class PinnedHTTPConnection(http.client.HTTPConnection):
def __init__(self, host, port, address, secure):
super().__init__(host, port, timeout=5)
self.address = address
self.secure = secure
def connect(self):
raw = socket.create_connection((self.address, self.port), timeout=self.timeout)
self.sock = ssl.create_default_context().wrap_socket(raw, server_hostname=self.host) if self.secure else raw
def public_address(host, port):
try:
answers = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
except OSError as exc:
raise MetadataError('DNS lookup failed.') from exc
if not answers:
raise MetadataError('No DNS address found.')
addresses = [answer[4][0] for answer in answers]
if any(not ipaddress.ip_address(address).is_global for address in addresses):
raise MetadataError('DNS resolved to a non-public address.')
return addresses[0]
def _public_url(value, base):
try:
candidate = clean_url(urljoin(base, value))
except (ValidationError, ValueError, TypeError):
return ''
return candidate if urlsplit(candidate).scheme == 'https' else ''
def _fetch_bytes(url, accepted_type, limit, max_redirects=MAX_REDIRECTS):
try:
current = clean_url(url)
except ValidationError as exc:
raise MetadataError('Invalid page URL.') from exc
deadline = time.monotonic() + 20
for _ in range(max_redirects + 1):
if time.monotonic() >= deadline:
raise MetadataError('Preview fetch timed out.')
parts = urlsplit(current)
port = parts.port or (443 if parts.scheme == 'https' else 80)
if port not in (80, 443):
raise MetadataError('Only standard web ports are fetched.')
address = public_address(parts.hostname, port)
connection = PinnedHTTPConnection(parts.hostname, port, address, parts.scheme == 'https')
try:
target = (parts.path or '/') + (f'?{parts.query}' if parts.query else '')
connection.request('GET', target, headers={'Host': parts.netloc, 'User-Agent': 'CommonGroundKnowledge/1.0',
'Accept': accepted_type, 'Accept-Encoding': 'identity', 'Connection': 'close'})
response = connection.getresponse()
if response.status in (301, 302, 303, 307, 308):
location = response.getheader('Location')
if not location:
raise MetadataError('Redirect has no location.')
try:
current = clean_url(urljoin(current, location))
except ValidationError as exc:
raise MetadataError('Redirect points to a disallowed URL.') from exc
continue
if response.status != 200:
raise MetadataError(f'HTTP {response.status}.')
content_type = (response.getheader('Content-Type') or '').lower().split(';', 1)[0].strip()
if content_type != accepted_type:
raise MetadataError('Unexpected content type.')
length = response.getheader('Content-Length')
if length and int(length) > limit:
raise MetadataError('Response is too large.')
chunks = []
size = 0
while True:
if time.monotonic() >= deadline:
raise MetadataError('Preview fetch timed out.')
chunk = response.read(min(8192, limit + 1 - size))
if not chunk:
return current, b''.join(chunks)
size += len(chunk)
if size > limit:
raise MetadataError('Response is too large.')
chunks.append(chunk)
except (OSError, ssl.SSLError, http.client.HTTPException, ValueError) as exc:
raise MetadataError('Could not fetch preview metadata.') from exc
finally:
connection.close()
raise MetadataError('Too many redirects.')
def youtube_video_id(url):
parts = urlsplit(url)
host = (parts.hostname or '').lower()
if host in ('youtube.com', 'www.youtube.com', 'm.youtube.com'):
if parts.path == '/watch':
value = parse_qs(parts.query).get('v', [''])[0]
elif parts.path.startswith(('/shorts/', '/live/', '/embed/')):
value = parts.path.split('/')[2]
else:
return ''
elif host == 'youtu.be':
value = parts.path.strip('/')
else:
return ''
return value if VIDEO_ID.fullmatch(value or '') else ''
def _youtube_metadata(url, video_id):
endpoint = 'https://www.youtube.com/oembed?' + urlencode({'url': url, 'format': 'json'})
_, body = _fetch_bytes(endpoint, 'application/json', MAX_JSON_BYTES, max_redirects=0)
try:
data = json.loads(body)
if not isinstance(data, dict):
raise ValueError()
except (ValueError, UnicodeError) as exc:
raise MetadataError('Invalid YouTube preview.') from exc
image = _public_url(data.get('thumbnail_url'), url) if isinstance(data.get('thumbnail_url'), str) else ''
return {'extracted_title': str(data.get('title') or '')[:300], 'description': '',
'thumbnail_url': image or f'https://i.ytimg.com/vi/{video_id}/hqdefault.jpg',
'image_alt': f'Thumbnail for {str(data.get("title") or "YouTube video")[:260]}',
'site_name': str(data.get('author_name') or 'YouTube')[:120], 'favicon_url': '',
'provider': 'youtube', 'embed_url': f'https://www.youtube-nocookie.com/embed/{video_id}',
'canonical_url': f'https://www.youtube.com/watch?v={video_id}'}
def fetch_metadata(url):
video_id = youtube_video_id(url)
if video_id:
try:
return _youtube_metadata(url, video_id)
except MetadataError:
# A known video still gets a useful card when oEmbed is unavailable.
return {'extracted_title': '', 'description': '',
'thumbnail_url': f'https://i.ytimg.com/vi/{video_id}/hqdefault.jpg',
'image_alt': 'YouTube video thumbnail', 'site_name': 'YouTube', 'favicon_url': '',
'provider': 'youtube', 'embed_url': f'https://www.youtube-nocookie.com/embed/{video_id}',
'canonical_url': f'https://www.youtube.com/watch?v={video_id}'}
final_url, body = _fetch_bytes(url, 'text/html', MAX_HTML_BYTES)
parser = MetadataParser()
parser.feed(body.decode('utf-8', errors='replace'))
meta = parser.meta
title = meta.get('og:title') or meta.get('twitter:title') or ''.join(parser.title_parts)
description = meta.get('og:description') or meta.get('twitter:description') or meta.get('description') or ''
image = meta.get('og:image') or meta.get('twitter:image') or ''
canonical = _public_url(parser.canonical, final_url) if parser.canonical else ''
if canonical and urlsplit(canonical).hostname != urlsplit(final_url).hostname:
canonical = ''
icon = _public_url(parser.icons[0], final_url) if parser.icons else ''
return {'extracted_title': ' '.join(title.split())[:300], 'description': description[:2000],
'thumbnail_url': _public_url(image, final_url) if image else '',
'image_alt': (meta.get('og:image:alt') or meta.get('twitter:image:alt') or '')[:300],
'site_name': (meta.get('og:site_name') or urlsplit(final_url).hostname or '')[:120],
'favicon_url': icon or _public_url('/favicon.ico', final_url),
'provider': 'web', 'embed_url': '', 'canonical_url': canonical}
+83
View File
@@ -0,0 +1,83 @@
# Generated by Django 6.1.2 on 2026-10-20 17:27
import django.db.models.deletion
import uuid
from django.conf import settings
from django.db import migrations, models
class Migration(migrations.Migration):
initial = True
dependencies = [
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
migrations.CreateModel(
name='CaptureToken',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('name', models.CharField(max_length=80)),
('token_hash', models.CharField(max_length=64, unique=True)),
('created_at', models.DateTimeField(auto_now_add=True)),
('revoked_at', models.DateTimeField(blank=True, null=True)),
('owner', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='knowledge_tokens', to=settings.AUTH_USER_MODEL)),
],
),
migrations.CreateModel(
name='SavedItem',
fields=[
('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
('original_url', models.URLField(max_length=2048)),
('url_key', models.CharField(max_length=2048)),
('canonical_url', models.URLField(blank=True, max_length=2048)),
('title', models.CharField(blank=True, max_length=300)),
('extracted_title', models.CharField(blank=True, max_length=300)),
('description', models.TextField(blank=True)),
('thumbnail_url', models.URLField(blank=True, max_length=2048)),
('notes', models.TextField(blank=True)),
('tags', models.JSONField(blank=True, default=list)),
('saved_reason', models.CharField(blank=True, max_length=300)),
('deferral_reason', models.CharField(blank=True, max_length=120)),
('status', models.CharField(choices=[('saved', 'Saved'), ('read', 'Read'), ('archived', 'Archived')], default='saved', max_length=12)),
('metadata_status', models.CharField(choices=[('pending', 'Pending'), ('ready', 'Ready'), ('error', 'Error')], default='pending', max_length=12)),
('created_at', models.DateTimeField(auto_now_add=True)),
('updated_at', models.DateTimeField(auto_now=True)),
('read_at', models.DateTimeField(blank=True, null=True)),
('last_surfaced_at', models.DateTimeField(blank=True, null=True)),
('snoozed_until', models.DateTimeField(blank=True, null=True)),
('owner', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='knowledge_items', to=settings.AUTH_USER_MODEL)),
],
options={
'ordering': ['-created_at'],
},
),
migrations.CreateModel(
name='RediscoveryEvent',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('channel', models.CharField(choices=[('mcp', 'MCP'), ('ntfy', 'ntfy')], max_length=12)),
('outcome', models.CharField(max_length=20)),
('created_at', models.DateTimeField(auto_now_add=True)),
('item', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='rediscovery_events', to='knowledge.saveditem')),
],
),
migrations.AddIndex(
model_name='saveditem',
index=models.Index(fields=['owner', 'status', '-created_at'], name='knowledge_s_owner_i_909a54_idx'),
),
migrations.AddIndex(
model_name='saveditem',
index=models.Index(fields=['owner', 'last_surfaced_at'], name='knowledge_s_owner_i_89f98e_idx'),
),
migrations.AddConstraint(
model_name='saveditem',
constraint=models.UniqueConstraint(fields=('owner', 'url_key'), name='knowledge_owner_url_unique'),
),
migrations.AddIndex(
model_name='rediscoveryevent',
index=models.Index(fields=['item', '-created_at'], name='knowledge_r_item_id_0f6d7f_idx'),
),
]
@@ -0,0 +1,68 @@
# Generated by Django 6.1.2 on 2026-10-20 17:46
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('knowledge', '0001_initial'),
]
operations = [
migrations.AddField(
model_name='saveditem',
name='embed_url',
field=models.URLField(blank=True, max_length=2048),
),
migrations.AddField(
model_name='saveditem',
name='favicon_url',
field=models.URLField(blank=True, max_length=2048),
),
migrations.AddField(
model_name='saveditem',
name='image_alt',
field=models.CharField(blank=True, max_length=300),
),
migrations.AddField(
model_name='saveditem',
name='metadata_attempts',
field=models.PositiveSmallIntegerField(default=0),
),
migrations.AddField(
model_name='saveditem',
name='metadata_error',
field=models.CharField(blank=True, max_length=200),
),
migrations.AddField(
model_name='saveditem',
name='metadata_fetched_at',
field=models.DateTimeField(blank=True, null=True),
),
migrations.AddField(
model_name='saveditem',
name='metadata_retry_at',
field=models.DateTimeField(blank=True, null=True),
),
migrations.AddField(
model_name='saveditem',
name='preview_mode',
field=models.CharField(choices=[('preview', 'Preview'), ('plain', 'Plain link'), ('embed', 'Playable embed')], default='preview', max_length=12),
),
migrations.AddField(
model_name='saveditem',
name='provider',
field=models.CharField(blank=True, max_length=40),
),
migrations.AddField(
model_name='saveditem',
name='site_name',
field=models.CharField(blank=True, max_length=120),
),
migrations.AddField(
model_name='saveditem',
name='user_description',
field=models.TextField(blank=True),
),
]
View File
+75
View File
@@ -0,0 +1,75 @@
import uuid
from urllib.parse import urlsplit
from django.conf import settings
from django.db import models
class SavedItem(models.Model):
class Status(models.TextChoices):
SAVED = 'saved', 'Saved'
READ = 'read', 'Read'
ARCHIVED = 'archived', 'Archived'
class MetadataStatus(models.TextChoices):
PENDING = 'pending', 'Pending'
READY = 'ready', 'Ready'
ERROR = 'error', 'Error'
id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
owner = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name='knowledge_items')
original_url = models.URLField(max_length=2048)
url_key = models.CharField(max_length=2048)
canonical_url = models.URLField(max_length=2048, blank=True)
title = models.CharField(max_length=300, blank=True)
user_description = models.TextField(blank=True)
extracted_title = models.CharField(max_length=300, blank=True)
description = models.TextField(blank=True)
thumbnail_url = models.URLField(max_length=2048, blank=True)
image_alt = models.CharField(max_length=300, blank=True)
site_name = models.CharField(max_length=120, blank=True)
favicon_url = models.URLField(max_length=2048, blank=True)
provider = models.CharField(max_length=40, blank=True)
embed_url = models.URLField(max_length=2048, blank=True)
preview_mode = models.CharField(max_length=12, choices=[('preview', 'Preview'), ('plain', 'Plain link'), ('embed', 'Playable embed')], default='preview')
notes = models.TextField(blank=True)
tags = models.JSONField(default=list, blank=True)
saved_reason = models.CharField(max_length=300, blank=True)
deferral_reason = models.CharField(max_length=120, blank=True)
status = models.CharField(max_length=12, choices=Status.choices, default=Status.SAVED)
metadata_status = models.CharField(max_length=12, choices=MetadataStatus.choices, default=MetadataStatus.PENDING)
metadata_error = models.CharField(max_length=200, blank=True)
metadata_fetched_at = models.DateTimeField(null=True, blank=True)
metadata_retry_at = models.DateTimeField(null=True, blank=True)
metadata_attempts = models.PositiveSmallIntegerField(default=0)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
read_at = models.DateTimeField(null=True, blank=True)
last_surfaced_at = models.DateTimeField(null=True, blank=True)
snoozed_until = models.DateTimeField(null=True, blank=True)
class Meta:
constraints = [models.UniqueConstraint(fields=['owner', 'url_key'], name='knowledge_owner_url_unique')]
indexes = [models.Index(fields=['owner', 'status', '-created_at']), models.Index(fields=['owner', 'last_surfaced_at'])]
ordering = ['-created_at']
@property
def domain(self):
return urlsplit(self.original_url).hostname or self.original_url
class CaptureToken(models.Model):
owner = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name='knowledge_tokens')
name = models.CharField(max_length=80)
token_hash = models.CharField(max_length=64, unique=True)
created_at = models.DateTimeField(auto_now_add=True)
revoked_at = models.DateTimeField(null=True, blank=True)
class RediscoveryEvent(models.Model):
item = models.ForeignKey(SavedItem, on_delete=models.CASCADE, related_name='rediscovery_events')
channel = models.CharField(max_length=12, choices=[('mcp', 'MCP'), ('ntfy', 'ntfy')])
outcome = models.CharField(max_length=20)
created_at = models.DateTimeField(auto_now_add=True)
class Meta:
indexes = [models.Index(fields=['item', '-created_at'])]
+83
View File
@@ -0,0 +1,83 @@
import random
import socket
from datetime import timedelta
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen
from django.conf import settings
from django.contrib.auth import get_user_model
from django.db import transaction
from django.db import models
from django.utils import timezone
from .models import RediscoveryEvent, SavedItem
class NotificationError(Exception):
pass
def send_ntfy_notification(url, title, message, timeout=10):
# Matches TasksNest's UTF-8 POST + Title header convention. URL comes from server environment.
request = Request(url, data=message.encode('utf-8'),
headers={'Content-Type': 'text/plain; charset=utf-8', 'Title': title}, method='POST')
try:
with urlopen(request, timeout=timeout) as response:
status = response.getcode()
except HTTPError as error:
raise NotificationError(f'ntfy responded with HTTP {error.code}.') from error
except (TimeoutError, socket.timeout, URLError, OSError) as error:
raise NotificationError('Could not connect to ntfy.') from error
if not 200 <= status < 300:
raise NotificationError(f'ntfy responded with HTTP {status}.')
def choose_item(user, mode='forgotten', now=None):
now = now or timezone.now()
cutoff = now - timedelta(days=14)
items = list(SavedItem.objects.filter(owner=user, status=SavedItem.Status.SAVED,
created_at__lte=now - timedelta(days=2)).filter(
models.Q(snoozed_until__isnull=True) | models.Q(snoozed_until__lte=now)).filter(
models.Q(last_surfaced_at__isnull=True) | models.Q(last_surfaced_at__lte=cutoff))[:500])
if not items:
return None
if mode == 'random':
return random.choice(items)
# "Timely" is deliberately recency based, not an unsupported claim about price or availability.
if mode == 'timely':
return max(items, key=lambda item: item.created_at)
return min(items, key=lambda item: item.last_surfaced_at or item.created_at)
def rediscover_once(now=None):
now = now or timezone.now()
if not settings.KNOWLEDGE_NTFY_ENABLED:
return 'disabled'
if not settings.KNOWLEDGE_NTFY_URL or not settings.KNOWLEDGE_NTFY_USER_ID:
return 'unconfigured'
local_hour = timezone.localtime(now).hour
start, end = settings.KNOWLEDGE_NTFY_QUIET_START, settings.KNOWLEDGE_NTFY_QUIET_END
in_quiet = start <= local_hour < end if start < end else local_hour >= start or local_hour < end
if in_quiet:
return 'quiet_hours'
user = get_user_model().objects.filter(pk=settings.KNOWLEDGE_NTFY_USER_ID).first()
if user is None:
return 'unknown_user'
week_start = now - timedelta(days=7)
delivered = RediscoveryEvent.objects.filter(item__owner=user, channel='ntfy', outcome='delivered', created_at__gte=week_start).count()
if delivered >= max(0, min(settings.KNOWLEDGE_NTFY_WEEKLY_LIMIT, 7)):
return 'weekly_limit'
mode = settings.KNOWLEDGE_NTFY_MODE if settings.KNOWLEDGE_NTFY_MODE in ('random', 'forgotten', 'timely') else 'forgotten'
item = choose_item(user, mode, now)
if item is None:
return 'no_eligible_items'
title = item.title or item.extracted_title or 'Saved link to revisit'
message = f'{title}\n{item.original_url}'
if item.saved_reason:
message += f'\nYou saved it because: {item.saved_reason}'
send_ntfy_notification(settings.KNOWLEDGE_NTFY_URL, 'Knowledge Library', message)
with transaction.atomic():
item.last_surfaced_at = now
item.save(update_fields=['last_surfaced_at', 'updated_at'])
RediscoveryEvent.objects.create(item=item, channel='ntfy', outcome='delivered')
return 'delivered'
+80
View File
@@ -0,0 +1,80 @@
import ipaddress
import re
from urllib.parse import urlsplit, urlunsplit
from django.core.exceptions import ValidationError
from django.db.models import Q
from django.utils import timezone
from datetime import timedelta
from .models import SavedItem
def clean_url(value):
value = (value or '').strip()
if len(value) > 2048 or any(ord(c) < 32 for c in value):
raise ValidationError('Enter a valid URL under 2048 characters.')
try:
parts = urlsplit(value)
host = parts.hostname
port = parts.port
except ValueError as exc:
raise ValidationError('Enter a valid URL.') from exc
if parts.scheme.lower() not in ('http', 'https') or not host or parts.username or parts.password:
raise ValidationError('Only public HTTP(S) URLs are accepted.')
host = host.lower().rstrip('.')
if '.' not in host and ':' not in host:
raise ValidationError('A public hostname is required.')
try:
address = ipaddress.ip_address(host.strip('[]'))
except ValueError:
address = None
if address and not address.is_global:
raise ValidationError('Local and private addresses are not accepted.')
if host in ('localhost', 'localhost.localdomain') or host.endswith(('.local', '.internal', '.localhost')):
raise ValidationError('Local hostnames are not accepted.')
authority = host if ':' not in host else f'[{host}]'
if port and port != (443 if parts.scheme.lower() == 'https' else 80):
authority += f':{port}'
key = urlunsplit((parts.scheme.lower(), authority, parts.path or '/', parts.query, ''))
if len(key) > 2048:
raise ValidationError('URL is too long.')
return key
def save_item(owner, url, **fields):
key = clean_url(url)
allowed = {'title', 'notes', 'saved_reason', 'deferral_reason', 'tags'}
defaults = {name: value for name, value in fields.items() if name in allowed}
item, created = SavedItem.objects.get_or_create(owner=owner, url_key=key,
defaults={'original_url': url.strip(), **defaults})
return item, created
def search_items(owner, query, limit=20):
words = re.findall(r'[\w-]{2,}', (query or '').lower())[:8]
qs = SavedItem.objects.filter(owner=owner).exclude(status=SavedItem.Status.ARCHIVED)
for word in words:
qs = qs.filter(Q(title__icontains=word) | Q(extracted_title__icontains=word) |
Q(original_url__icontains=word) | Q(description__icontains=word) |
Q(notes__icontains=word) | Q(saved_reason__icontains=word) | Q(tags__icontains=word))
return list(qs[:max(1, min(limit, 100))])
def relevant_items(owner, context):
words = set(re.findall(r'[\w-]{4,}', (context or '').lower()))
words -= {'this', 'that', 'with', 'from', 'about', 'what', 'would', 'could', 'should', 'there', 'their'}
if not words:
return []
now = timezone.now()
candidates = SavedItem.objects.filter(owner=owner, status=SavedItem.Status.SAVED).filter(
Q(snoozed_until__isnull=True) | Q(snoozed_until__lte=now)).filter(
Q(last_surfaced_at__isnull=True) | Q(last_surfaced_at__lte=now - timedelta(days=14)))
scored = []
for item in candidates[:500]:
text = ' '.join([item.title, item.extracted_title, item.description, item.saved_reason, ' '.join(item.tags)]).lower()
hits = words & set(re.findall(r'[\w-]{4,}', text))
if len(hits) >= 2 or (len(hits) == 1 and len(next(iter(hits))) >= 6):
scored.append((len(hits), item, sorted(hits)))
scored.sort(key=lambda row: (-row[0], -row[1].created_at.timestamp()))
return scored[:3]
+4
View File
@@ -0,0 +1,4 @@
.knowledge-form{margin-bottom:20px}.knowledge-fields{display:grid;gap:6px;margin-bottom:14px;max-width:680px}.knowledge-fields label,.knowledge-search label{font-weight:700}.knowledge-fields input,.knowledge-search input,.knowledge-actions input,.knowledge-actions textarea,.knowledge-actions select{width:100%;padding:9px;border:1px solid var(--border);border-radius:8px;background:var(--surface);color:var(--text)}.knowledge-search{max-width:680px}.knowledge-search>div{display:flex;gap:8px}.knowledge-list{display:grid;gap:14px;margin-top:20px}.knowledge-item{padding:0;overflow:hidden;display:grid;grid-template-columns:minmax(0,220px) minmax(0,1fr)}.knowledge-item:not(:has(.knowledge-image-wrap)){grid-template-columns:1fr}.knowledge-image-wrap{background:var(--surface-secondary);min-height:180px;display:grid;place-items:center}.knowledge-image{width:100%;height:100%;max-height:300px;object-fit:cover}.knowledge-image-fallback{color:var(--text-secondary)}.knowledge-body{padding:20px;min-width:0}.knowledge-site{font-size:11px;color:var(--text-secondary);font-weight:700}.knowledge-body h2{font-size:19px;overflow-wrap:anywhere}.knowledge-description,.knowledge-reason{color:var(--text-secondary)}.knowledge-state{font-size:11px;color:var(--text-muted)}.knowledge-actions{display:flex;gap:12px;align-items:start;flex-wrap:wrap;margin-top:14px}.knowledge-actions button,.knowledge-actions summary,.knowledge-play{border:1px solid var(--border);border-radius:7px;padding:7px 10px;background:var(--surface-secondary);color:var(--text);cursor:pointer}.knowledge-actions details{min-width:min(100%,250px)}.knowledge-actions details[open]{width:min(100%,450px)}.knowledge-actions details form{display:grid;gap:10px;padding-top:12px}.knowledge-actions label{display:grid;gap:4px;font-weight:700}.knowledge-actions textarea{min-height:75px}.knowledge-player{margin-top:12px}.knowledge-third-party{font-size:11px;color:var(--text-muted);margin:5px 0}.knowledge-player iframe{width:100%;aspect-ratio:16/9;border:0;border-radius:8px}@media(max-width:680px){.knowledge-item{grid-template-columns:1fr}.knowledge-image-wrap{height:190px;min-height:0}.knowledge-body{padding:16px}}@media(prefers-reduced-motion:reduce){.knowledge-item{transition:none}}
.knowledge-favicon{width:16px;height:16px;object-fit:contain;vertical-align:middle;margin-right:5px}
.knowledge-item--embed{grid-template-columns:1fr}.knowledge-item--embed .knowledge-image-wrap{max-height:330px}.knowledge-item--embed .knowledge-player{min-height:54px}
.knowledge-image-wrap{overflow:hidden}.knowledge-image{display:block}@media(max-width:680px){.knowledge-image-wrap{height:190px}.knowledge-image{height:190px;max-height:190px}}
+40
View File
@@ -0,0 +1,40 @@
document.addEventListener('DOMContentLoaded', () => {
document.addEventListener('error', (event) => {
if (event.target.matches?.('.knowledge-favicon')) { event.target.hidden = true; return; }
if (!event.target.matches?.('.knowledge-image')) return;
event.target.hidden = true;
const fallback = event.target.parentElement.querySelector('.knowledge-image-fallback');
if (fallback) fallback.hidden = false;
}, true);
document.addEventListener('click', (event) => {
const button = event.target.closest?.('.knowledge-play');
if (!button) return;
const player = button.closest('.knowledge-player');
const url = player?.dataset.embedUrl || '';
if (!/^https:\/\/www\.youtube-nocookie\.com\/embed\/[A-Za-z0-9_-]{11}$/.test(url)) return;
const frame = document.createElement('iframe');
frame.src = url;
frame.title = 'YouTube video player';
frame.referrerPolicy = 'no-referrer';
frame.allow = 'accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; web-share';
frame.allowFullscreen = true;
player.replaceChildren(frame);
frame.focus();
});
const started = Date.now();
const poll = async () => {
if (document.hidden || Date.now() - started > 120000) return;
const cards = [...document.querySelectorAll('.knowledge-item[data-metadata-status="pending"]')].slice(0, 20);
for (const card of cards) {
try {
const response = await fetch(card.dataset.cardUrl, {credentials: 'same-origin', cache: 'no-store'});
if (!response.ok) continue;
const html = await response.text();
const documentFragment = new DOMParser().parseFromString(html, 'text/html');
const replacement = documentFragment.querySelector('.knowledge-item');
if (replacement && replacement.dataset.metadataStatus !== 'pending') card.replaceWith(replacement);
} catch (_) { /* Preserve the current card on a transient polling failure. */ }
}
};
const timer = setInterval(() => { if (Date.now() - started > 120000) clearInterval(timer); else poll(); }, 10000);
});
@@ -0,0 +1,12 @@
<article class="widget-card knowledge-item{% if item.preview_mode == 'embed' %} knowledge-item--embed{% endif %}" id="knowledge-item-{{ item.id }}" data-card-url="{% url 'knowledge:item_card' item.id %}" data-metadata-status="{{ item.metadata_status }}">
{% if item.preview_mode != 'plain' and item.thumbnail_url %}<div class="knowledge-image-wrap"><img class="knowledge-image" src="{{ item.thumbnail_url }}" alt="{{ item.image_alt|default:'Preview image for saved link' }}" loading="lazy" referrerpolicy="no-referrer"><span class="knowledge-image-fallback" hidden>Image unavailable</span></div>{% endif %}
<div class="knowledge-body">
<p class="knowledge-site">{% if item.favicon_url and item.preview_mode != 'plain' %}<img class="knowledge-favicon" src="{{ item.favicon_url }}" alt="" loading="lazy" referrerpolicy="no-referrer">{% endif %}{% if item.site_name %}{{ item.site_name }}{% else %}{{ item.domain }}{% endif %}{% if item.provider == 'youtube' %} · YouTube{% endif %}</p>
<h2><a href="{{ item.original_url }}" target="_blank" rel="noopener noreferrer">{{ item.title|default:item.extracted_title|default:item.original_url }}</a></h2>
{% if item.preview_mode != 'plain' %}{% if item.user_description or item.description %}<p class="knowledge-description">{{ item.user_description|default:item.description }}</p>{% endif %}{% endif %}
{% if item.saved_reason %}<p class="knowledge-reason">Saved because: {{ item.saved_reason }}</p>{% endif %}
<p class="knowledge-state"><small>Saved {{ item.created_at|date:'j M Y' }} · {% if item.metadata_status == 'pending' %}Preview loading{% elif item.metadata_status == 'error' %}Preview unavailable{% if item.metadata_error %}: {{ item.metadata_error }}{% endif %}{% else %}Preview updated {{ item.metadata_fetched_at|date:'j M Y' }}{% endif %}</small></p>
{% if item.provider == 'youtube' and item.preview_mode != 'plain' and item.embed_url %}<div class="knowledge-player" data-embed-url="{{ item.embed_url }}"><button type="button" class="knowledge-play">Play video</button><p class="knowledge-third-party">Playing loads YouTube content.</p></div>{% endif %}
<div class="knowledge-actions"><details><summary>Edit preview</summary><form method="post" action="{% url 'knowledge:edit' item.id %}">{% csrf_token %}<label>Your title<input name="title" value="{{ item.title }}" maxlength="300"></label><label>Your description<textarea name="description" maxlength="2000">{{ item.user_description }}</textarea></label><label>Display mode<select name="preview_mode"><option value="preview" {% if item.preview_mode == 'preview' %}selected{% endif %}>Preview</option><option value="plain" {% if item.preview_mode == 'plain' %}selected{% endif %}>Plain link</option>{% if item.provider == 'youtube' %}<option value="embed" {% if item.preview_mode == 'embed' %}selected{% endif %}>Playable embed</option>{% endif %}</select></label><button type="submit">Save changes</button></form></details><form method="post" action="{% url 'knowledge:refresh' item.id %}">{% csrf_token %}<button type="submit">Refresh preview</button></form><form method="post" action="{% url 'knowledge:archive' item.id %}">{% csrf_token %}<button type="submit">Archive</button></form></div>
</div>
</article>
+10
View File
@@ -0,0 +1,10 @@
{% extends 'core/base.html' %}{% load static %}
{% block extra_head %}<link rel="stylesheet" href="{% static 'knowledge/previews.css' %}"><script src="{% static 'knowledge/previews.js' %}" defer></script>{% endblock %}
{% block content %}
<div class="page-heading"><div><h1>Knowledge Library</h1><p>Save things you want to revisit when the time is right.</p></div><a class="button" href="{% url 'knowledge:tokens' %}">Capture tokens</a></div>
<section class="widget-card knowledge-form"><h2>Save a link</h2>
{% if error %}<p role="alert">{{ error }}</p>{% endif %}
<form method="post" action="{% url 'knowledge:add' %}">{% csrf_token %}<div class="knowledge-fields"><label for="save-url">URL</label><input id="save-url" name="url" type="url" required maxlength="2048" value="{{ form_url }}"><label for="save-title">Your title (optional)</label><input id="save-title" name="title" maxlength="300"><label for="save-reason">Why save it? (optional)</label><input id="save-reason" name="saved_reason" maxlength="300"></div><button class="button" type="submit">Save link</button></form></section>
<form method="get" role="search" class="knowledge-search"><label for="knowledge-search">Search saved links</label><div><input id="knowledge-search" type="search" name="q" value="{{ query }}"><button class="button" type="submit">Search</button></div></form>
<div class="knowledge-list">{% for item in items %}{% include 'knowledge/_item_card.html' %}{% empty %}<p>No saved links found.</p>{% endfor %}</div>
{% endblock %}
@@ -0,0 +1,5 @@
{% extends 'core/base.html' %}
{% block content %}<h1>Capture tokens</h1><p>Create a token for an Apple Shortcut that sends a URL to this library. Tokens only permit saving links.</p>
{% if secret %}<div class="widget-card" role="status"><strong>Copy this token now; it will not be shown again.</strong><p><code style="overflow-wrap:anywhere">{{ secret }}</code></p></div>{% endif %}
<form method="post">{% csrf_token %}<label for="token-name">Token name</label><input id="token-name" name="name" value="Apple Shortcut" maxlength="80"><button class="button" type="submit">Create token</button></form>
<h2>Existing tokens</h2><ul>{% for token in tokens %}<li>{{ token.name }} · {{ token.created_at|date:'j M Y' }} {% if token.revoked_at %}(revoked){% else %}<form method="post" style="display:inline">{% csrf_token %}<input type="hidden" name="action" value="revoke"><input type="hidden" name="token_id" value="{{ token.id }}"><button type="submit">Revoke</button></form>{% endif %}</li>{% empty %}<li>No tokens yet.</li>{% endfor %}</ul><a href="{% url 'knowledge:index' %}">Back to library</a>{% endblock %}
+183
View File
@@ -0,0 +1,183 @@
import hashlib
import json
from django.contrib.auth import get_user_model
from django.test import TestCase
from django.urls import reverse
from django.core.management import call_command
from django.test import override_settings
from django.utils import timezone
from datetime import timedelta
from unittest.mock import patch
from .models import CaptureToken, SavedItem
from .services import relevant_items, save_item
from .notifications import rediscover_once
from .metadata import MetadataError, fetch_metadata, public_address, youtube_video_id
class KnowledgeTests(TestCase):
def setUp(self):
self.alice = get_user_model().objects.create_user('alice', password='test-password')
self.bob = get_user_model().objects.create_user('bob', password='test-password')
def test_capture_is_idempotent_and_owner_scoped(self):
token = 'capture-secret'
CaptureToken.objects.create(owner=self.alice, name='Shortcut', token_hash=hashlib.sha256(token.encode()).hexdigest())
url = reverse('knowledge_api_add')
headers = {'HTTP_AUTHORIZATION': f'Bearer {token}', 'content_type': 'application/json'}
first = self.client.post(url, data=json.dumps({'url': 'https://example.org/esp32#top', 'title': 'ESP32'}), **headers)
second = self.client.post(url, data=json.dumps({'url': 'https://EXAMPLE.org/esp32'}), **headers)
self.assertEqual(first.status_code, 201)
self.assertEqual(second.status_code, 200)
self.assertTrue(second.json()['duplicate'])
self.assertEqual(SavedItem.objects.filter(owner=self.alice).count(), 1)
self.assertEqual(SavedItem.objects.filter(owner=self.bob).count(), 0)
self.assertEqual(self.client.post(url, data='{}', content_type='application/json').status_code, 401)
def test_private_url_and_cross_user_visibility(self):
token = 'capture-secret'
CaptureToken.objects.create(owner=self.alice, name='Shortcut', token_hash=hashlib.sha256(token.encode()).hexdigest())
response = self.client.post(reverse('knowledge_api_add'), data=json.dumps({'url': 'http://127.0.0.1/admin'}),
content_type='application/json', HTTP_AUTHORIZATION=f'Bearer {token}')
self.assertEqual(response.status_code, 400)
item, _ = save_item(self.alice, 'https://example.org/sensor', title='ESP32 sensor microphone')
self.assertEqual(relevant_items(self.bob, 'ESP32 sensor microphone'), [])
self.assertEqual(relevant_items(self.alice, 'ESP32 sensor microphone')[0][1], item)
self.client.force_login(self.bob)
self.assertNotContains(self.client.get(reverse('knowledge:index')), 'ESP32 sensor microphone')
self.assertEqual(self.client.post(reverse('knowledge:archive', args=[item.pk])).status_code, 404)
def test_token_revocation(self):
self.client.force_login(self.alice)
self.client.post(reverse('knowledge:tokens'), {'name': 'Shortcut'})
token = CaptureToken.objects.get(owner=self.alice)
self.client.post(reverse('knowledge:tokens'), {'action': 'revoke', 'token_id': token.pk})
token.refresh_from_db()
self.assertIsNotNone(token.revoked_at)
@override_settings(KNOWLEDGE_NTFY_ENABLED=True, KNOWLEDGE_NTFY_URL='https://ntfy.example.org/topic',
KNOWLEDGE_NTFY_WEEKLY_LIMIT=1, KNOWLEDGE_NTFY_QUIET_START=23, KNOWLEDGE_NTFY_QUIET_END=6)
@patch('knowledge.notifications.send_ntfy_notification')
def test_ntfy_limit_and_cooldown(self, sender):
item, _ = save_item(self.alice, 'https://example.org/esp32', title='ESP32 sensors')
SavedItem.objects.filter(pk=item.pk).update(created_at=timezone.now() - timedelta(days=5))
with override_settings(KNOWLEDGE_NTFY_USER_ID=str(self.alice.pk)):
now = timezone.now().replace(hour=12)
self.assertEqual(rediscover_once(now), 'delivered')
self.assertEqual(rediscover_once(now), 'weekly_limit')
sender.assert_called_once()
@patch('knowledge.metadata.socket.getaddrinfo')
def test_metadata_rejects_private_dns_answer(self, resolver):
resolver.return_value = [(None, None, None, None, ('192.168.1.1', 443))]
with self.assertRaises(MetadataError):
public_address('example.org', 443)
@patch('knowledge.metadata.PinnedHTTPConnection')
@patch('knowledge.metadata.public_address', return_value='93.184.215.14')
def test_metadata_reads_only_bounded_html(self, resolver, connection_type):
response = connection_type.return_value.getresponse.return_value
response.status = 200
response.getheader.side_effect = lambda name: {'Content-Type': 'text/html; charset=utf-8', 'Content-Length': '90'}.get(name)
response.read.side_effect = [b'<title>Useful ESP32 page</title><meta name="description" content="A sensor guide">', b'']
result = fetch_metadata('https://example.org/esp32')
self.assertEqual(result['extracted_title'], 'Useful ESP32 page')
self.assertEqual(result['description'], 'A sensor guide')
connection_type.assert_called_once_with('example.org', 443, '93.184.215.14', True)
@patch('knowledge.metadata._fetch_bytes')
def test_open_graph_precedence_and_fallback(self, fetch):
html = b'''<title>HTML title</title><meta name="description" content="HTML description">
<meta name="twitter:title" content="Twitter title"><meta name="twitter:image" content="https://example.org/tw.jpg">
<meta property="og:title" content="OG title"><meta property="og:description" content="OG description">
<meta property="og:image" content="https://example.org/og.jpg"><meta property="og:image:alt" content="A flower">
<meta property="og:site_name" content="Example Journal"><link rel="icon" href="/favicon.png">'''
fetch.return_value = ('https://example.org/article', html)
result = fetch_metadata('https://example.org/article')
self.assertEqual(result['extracted_title'], 'OG title')
self.assertEqual(result['description'], 'OG description')
self.assertEqual(result['thumbnail_url'], 'https://example.org/og.jpg')
self.assertEqual(result['image_alt'], 'A flower')
self.assertEqual(result['site_name'], 'Example Journal')
self.assertEqual(result['favicon_url'], 'https://example.org/favicon.png')
fetch.return_value = ('https://example.org/article', b'<title>HTML only</title>')
self.assertEqual(fetch_metadata('https://example.org/article')['extracted_title'], 'HTML only')
fetch.return_value = ('https://example.org/article', b'<html><head></head><body>Nothing to extract</body></html>')
self.assertEqual(fetch_metadata('https://example.org/article')['extracted_title'], '')
@patch('knowledge.metadata._fetch_bytes')
def test_youtube_oembed_uses_allowlisted_embed(self, fetch):
fetch.return_value = ('https://www.youtube.com/oembed', json.dumps({
'title': 'Circuit demo', 'author_name': 'Maker channel',
'thumbnail_url': 'https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg'}).encode())
result = fetch_metadata('https://youtu.be/dQw4w9WgXcQ')
self.assertEqual(result['site_name'], 'Maker channel')
self.assertEqual(result['embed_url'], 'https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ')
self.assertEqual(youtube_video_id('https://youtube.com.evil.test/watch?v=dQw4w9WgXcQ'), '')
@patch('knowledge.metadata.PinnedHTTPConnection')
@patch('knowledge.metadata.public_address', return_value='93.184.215.14')
def test_redirect_to_private_address_is_blocked(self, resolver, connection_type):
response = connection_type.return_value.getresponse.return_value
response.status = 302
response.getheader.return_value = 'http://127.0.0.1/admin'
with self.assertRaises(MetadataError):
fetch_metadata('https://example.org/article')
@patch('knowledge.metadata.PinnedHTTPConnection')
@patch('knowledge.metadata.public_address', return_value='93.184.215.14')
def test_timeout_is_a_safe_failure(self, resolver, connection_type):
import socket
connection_type.return_value.request.side_effect = socket.timeout()
with self.assertRaises(MetadataError):
fetch_metadata('https://example.org/article')
@patch('knowledge.management.commands.fetch_knowledge_metadata.fetch_metadata')
def test_metadata_refresh_preserves_user_edits_and_cache(self, fetch):
item, _ = save_item(self.alice, 'https://example.org/article')
self.client.force_login(self.alice)
self.client.post(reverse('knowledge:edit', args=[item.pk]), {
'title': 'My title', 'description': 'My notes on this', 'preview_mode': 'preview'})
fetch.return_value = {'extracted_title': 'Publisher title', 'description': 'Publisher description',
'thumbnail_url': 'https://example.org/image.jpg', 'image_alt': 'Image', 'site_name': 'Example',
'favicon_url': '', 'provider': 'web', 'embed_url': '', 'canonical_url': ''}
call_command('fetch_knowledge_metadata')
item.refresh_from_db()
self.assertEqual(item.title, 'My title')
self.assertEqual(item.user_description, 'My notes on this')
self.assertEqual(item.description, 'Publisher description')
self.assertEqual(item.metadata_status, SavedItem.MetadataStatus.READY)
call_command('fetch_knowledge_metadata')
self.assertEqual(fetch.call_count, 1)
self.assertContains(self.client.get(reverse('knowledge:index')), 'My title')
self.assertContains(self.client.get(reverse('knowledge:index')), 'My notes on this')
def test_preview_escapes_metadata_and_defers_youtube_embed(self):
item, _ = save_item(self.alice, 'https://youtu.be/dQw4w9WgXcQ')
item.provider = 'youtube'
item.embed_url = 'https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ'
item.extracted_title = '<script>alert(1)</script>'
item.thumbnail_url = 'https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg'
item.save()
self.client.force_login(self.alice)
response = self.client.get(reverse('knowledge:index'))
self.assertContains(response, '&lt;script&gt;alert(1)&lt;/script&gt;')
self.assertNotContains(response, '<iframe')
self.assertContains(response, 'Play video')
self.assertContains(response, 'knowledge-image-fallback')
self.client.force_login(self.bob)
self.assertEqual(self.client.get(reverse('knowledge:item_card', args=[item.pk])).status_code, 404)
@patch('knowledge.management.commands.fetch_knowledge_metadata.fetch_metadata', side_effect=MetadataError('HTTP 503.'))
def test_worker_retries_with_backoff_and_keeps_saved_link(self, fetch):
item, _ = save_item(self.alice, 'https://example.org/broken')
call_command('fetch_knowledge_metadata')
item.refresh_from_db()
self.assertEqual(item.metadata_status, SavedItem.MetadataStatus.ERROR)
self.assertEqual(item.metadata_attempts, 1)
self.assertGreater(item.metadata_retry_at, timezone.now())
call_command('fetch_knowledge_metadata')
self.assertEqual(fetch.call_count, 1)
self.client.force_login(self.alice)
self.assertContains(self.client.get(reverse('knowledge:index')), 'Preview unavailable')
self.assertContains(self.client.get(reverse('knowledge:index')), 'https://example.org/broken')
+13
View File
@@ -0,0 +1,13 @@
from django.urls import path
from . import views
app_name = 'knowledge'
urlpatterns = [
path('', views.index, name='index'),
path('add/', views.add, name='add'),
path('items/<uuid:item_id>/archive/', views.archive, name='archive'),
path('items/<uuid:item_id>/card/', views.item_card, name='item_card'),
path('items/<uuid:item_id>/edit/', views.edit, name='edit'),
path('items/<uuid:item_id>/refresh/', views.refresh, name='refresh'),
path('tokens/', views.tokens, name='tokens'),
]
+129
View File
@@ -0,0 +1,129 @@
import hashlib
import json
import secrets
from datetime import timedelta
from django.contrib.auth.decorators import login_required
from django.core.exceptions import ValidationError
from django.core.cache import cache
from django.http import JsonResponse
from django.shortcuts import get_object_or_404, redirect, render
from django.utils import timezone
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from .models import CaptureToken, SavedItem
from .services import save_item, search_items
@login_required
def index(request):
query = request.GET.get('q', '').strip()[:200]
items = search_items(request.user, query, 100) if query else SavedItem.objects.filter(owner=request.user).exclude(status=SavedItem.Status.ARCHIVED)[:100]
return render(request, 'knowledge/index.html', {'title': 'Knowledge Library', 'section': 'knowledge', 'items': items, 'query': query})
@login_required
def item_card(request, item_id):
item = get_object_or_404(SavedItem, pk=item_id, owner=request.user)
response = render(request, 'knowledge/_item_card.html', {'item': item})
response['Cache-Control'] = 'private, no-store'
return response
@login_required
@require_POST
def add(request):
try:
item, created = save_item(request.user, request.POST.get('url'),
title=request.POST.get('title', '').strip()[:300],
notes=request.POST.get('notes', '').strip()[:3000],
saved_reason=request.POST.get('saved_reason', '').strip()[:300])
except ValidationError as exc:
return render(request, 'knowledge/index.html', {'title': 'Knowledge Library', 'section': 'knowledge',
'items': SavedItem.objects.filter(owner=request.user)[:100], 'error': exc.messages[0], 'form_url': request.POST.get('url', '')}, status=400)
return redirect('knowledge:index')
@login_required
@require_POST
def archive(request, item_id):
item = get_object_or_404(SavedItem, pk=item_id, owner=request.user)
item.status = SavedItem.Status.ARCHIVED
item.save(update_fields=['status', 'updated_at'])
return redirect('knowledge:index')
@login_required
@require_POST
def edit(request, item_id):
item = get_object_or_404(SavedItem, pk=item_id, owner=request.user)
mode = request.POST.get('preview_mode', 'preview')
if mode not in ('preview', 'plain', 'embed') or (mode == 'embed' and item.provider != 'youtube'):
return JsonResponse({'error': 'Invalid preview mode'}, status=400)
item.title = request.POST.get('title', '').strip()[:300]
item.user_description = request.POST.get('description', '').strip()[:2000]
item.preview_mode = mode
item.save(update_fields=['title', 'user_description', 'preview_mode', 'updated_at'])
return redirect('knowledge:index')
@login_required
@require_POST
def refresh(request, item_id):
item = get_object_or_404(SavedItem, pk=item_id, owner=request.user)
if item.metadata_fetched_at and item.metadata_fetched_at > timezone.now() - timedelta(minutes=5):
return redirect('knowledge:index')
item.metadata_status = SavedItem.MetadataStatus.PENDING
item.metadata_retry_at = None
item.metadata_error = ''
item.metadata_attempts = 0
item.save(update_fields=['metadata_status', 'metadata_retry_at', 'metadata_error', 'metadata_attempts', 'updated_at'])
return redirect('knowledge:index')
@login_required
def tokens(request):
secret = None
if request.method == 'POST':
if request.POST.get('action') == 'revoke':
token = get_object_or_404(CaptureToken, pk=request.POST.get('token_id'), owner=request.user)
token.revoked_at = timezone.now()
token.save(update_fields=['revoked_at'])
else:
secret = secrets.token_urlsafe(32)
CaptureToken.objects.create(owner=request.user, name=request.POST.get('name', 'Apple Shortcut')[:80],
token_hash=hashlib.sha256(secret.encode()).hexdigest())
return render(request, 'knowledge/tokens.html', {'title': 'Capture tokens', 'section': 'knowledge',
'tokens': CaptureToken.objects.filter(owner=request.user).order_by('-created_at'), 'secret': secret})
@csrf_exempt
@require_POST
def api_add(request):
if len(request.body) > 16_384:
return JsonResponse({'error': 'Request too large'}, status=413)
header = request.headers.get('Authorization', '')
if not header.startswith('Bearer ') or len(header) > 180:
return JsonResponse({'error': 'Bearer capture token required'}, status=401)
token_hash = hashlib.sha256(header[7:].encode()).hexdigest()
token = CaptureToken.objects.select_related('owner').filter(token_hash=token_hash, revoked_at__isnull=True).first()
if token is None:
return JsonResponse({'error': 'Invalid capture token'}, status=401)
rate_key = f'knowledge-capture:{token.pk}:{timezone.now():%Y%m%d%H%M}'
if not cache.add(rate_key, 1, 90):
try:
if cache.incr(rate_key) > 30:
return JsonResponse({'error': 'Too many captures; try again shortly'}, status=429)
except ValueError:
cache.set(rate_key, 1, 90)
try:
payload = json.loads(request.body)
if not isinstance(payload, dict):
raise ValueError()
item, created = save_item(token.owner, payload.get('url'),
title=str(payload.get('title') or '')[:300], notes=str(payload.get('notes') or '')[:3000],
saved_reason=str(payload.get('saved_reason') or '')[:300])
except (ValueError, TypeError, ValidationError) as exc:
return JsonResponse({'error': str(exc) or 'Invalid JSON'}, status=400)
return JsonResponse({'id': str(item.pk), 'created': created, 'duplicate': not created,
'url': item.original_url, 'metadata_status': item.metadata_status}, status=201 if created else 200)
+38 -2
View File
@@ -34,6 +34,7 @@ from projects import services
from projects.models import Activity, Card, CardComment, CardRevision, CardAttachment, Column, Project, Tag, ProjectDocument, DocumentationSync
from projects import attachments
from projects import documentation
from knowledge import services as knowledge_services
def _verified(raw):
@@ -150,11 +151,21 @@ def _safe(operation):
def create_server():
server = MCPServer('Common Ground Projects', description='Projects, Kanban cards, and Markdown specifications.',
server = MCPServer('Common Ground', description='Projects and a separate personal knowledge library.',
token_verifier=OAuthTokenVerifier(), auth=AuthSettings(
issuer_url=AnyHttpUrl(settings.OAUTH_ISSUER_URL),
resource_server_url=AnyHttpUrl(settings.MCP_PUBLIC_URL), required_scopes=[], validate_token_resource=False))
@server.tool(structured_output=True, description='Find up to three relevant links in the connected user’s private Knowledge Library when the conversation overlaps their saved interests. Call opportunistically for concrete topics; an empty result means do not interrupt the user. This tool cannot observe conversations unless called by the client.')
async def find_relevant_saved_interests(context: str) -> dict[str, Any]:
def run():
user = _actor('knowledge:read')
matches = knowledge_services.relevant_items(user, context[:2000])
return {'items': [{'id': str(item.pk), 'title': item.title or item.extracted_title or item.original_url,
'url': item.original_url, 'saved_reason': item.saved_reason,
'why_relevant': 'Matches ' + ', '.join(hits)} for _, item, hits in matches]}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='List projects accessible to the connected user, with counts and repository metadata.')
async def projects_list(limit: int = 50, offset: int = 0) -> dict[str, Any]:
def run():
@@ -530,6 +541,30 @@ def create_server():
return _card_data(services.move_card(user, _card(user, card_id, write=True), Column.objects.get(pk=UUID(column_id)), position, origin='mcp'))
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Move a card to another editable project. Requires the destination project UUID and expected_revision; optionally choose an active destination column and provide an idempotency key. Preserves the card UUID, notes, files, and history; returns warnings if tags or assignee must be cleared.')
async def cards_move_project(card_id: str, target_project: str, expected_revision: int,
target_column_id: str | None = None,
idempotency_key: str | None = None) -> dict[str, Any]:
def run():
user = _actor('projects:write')
card = _card(user, card_id, write=True)
try:
project_id = UUID(target_project)
except (ValueError, TypeError, AttributeError):
raise ValidationError('target_project must be a project UUID.')
target = services.project_for(user, project_id, write=True)
column = None
if target_column_id:
try:
column = Column.objects.get(pk=UUID(target_column_id))
except (Column.DoesNotExist, ValueError, TypeError, AttributeError):
raise ValidationError('Destination column is unavailable.')
moved, result = services.move_card_to_project(
user, card, target, target_column=column, expected_revision=expected_revision,
idempotency_key=idempotency_key, origin='mcp')
return {**_card_data(moved), 'move': result}
return await sync_to_async(lambda: _safe(run))()
@server.tool(structured_output=True, description='Reorder a card within its current column using a zero-based position.')
async def cards_reorder(card_id: str, position: int) -> dict[str, Any]:
def run():
@@ -701,7 +736,8 @@ def create_server():
async def system_capabilities() -> dict[str, Any]:
_actor()
return {'scopes': ['projects:read', 'projects:write'], 'max_page_size': 100, 'version': '0.3',
'transport': 'streamable_http', 'documentation': ['docs_list', 'docs_search', 'docs_read', 'docs_history', 'docs_diff']}
'transport': 'streamable_http', 'documentation': ['docs_list', 'docs_search', 'docs_read', 'docs_history', 'docs_diff'],
'card_moves': {'same_project': 'cards_move', 'between_projects': 'cards_move_project'}}
return server
@@ -0,0 +1,30 @@
# Generated by Django 6.1.2 on 2026-10-22 01:16
import django.db.models.deletion
from django.conf import settings
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
('projects', '0006_documentationsync_projectdocument'),
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
migrations.CreateModel(
name='ProjectMoveKey',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('key', models.CharField(max_length=128)),
('payload_hash', models.CharField(max_length=64)),
('result', models.JSONField()),
('created_at', models.DateTimeField(auto_now_add=True)),
('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL)),
],
options={
'constraints': [models.UniqueConstraint(fields=('user', 'key'), name='unique_project_move_key')],
},
),
]
+11
View File
@@ -215,6 +215,17 @@ class BulkUpdateKey(models.Model):
constraints = [models.UniqueConstraint(fields=['user', 'key'], name='unique_bulk_update_key')]
class ProjectMoveKey(models.Model):
user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
key = models.CharField(max_length=128)
payload_hash = models.CharField(max_length=64)
result = models.JSONField()
created_at = models.DateTimeField(auto_now_add=True)
class Meta:
constraints = [models.UniqueConstraint(fields=['user', 'key'], name='unique_project_move_key')]
class Activity(models.Model):
project = models.ForeignKey(Project, on_delete=models.CASCADE, related_name='activity')
card = models.ForeignKey(Card, null=True, blank=True, on_delete=models.CASCADE, related_name='activity')
+96 -1
View File
@@ -8,7 +8,7 @@ from django.core.validators import URLValidator
from django.shortcuts import get_object_or_404
from django.utils import timezone
from django.utils.text import slugify
from .models import Activity, Board, BulkUpdateKey, Card, CardRevision, Column, CreationKey, Membership, Project, Tag
from .models import Activity, Board, BulkUpdateKey, Card, CardRevision, Column, CreationKey, Membership, Project, ProjectMoveKey, Tag
class RevisionConflict(Exception):
@@ -145,6 +145,101 @@ def move_card(user, card, column, position=None, origin='web', record_revision=T
return card
@transaction.atomic
def move_card_to_project(user, card, target_project, *, target_column=None, expected_revision,
idempotency_key=None, origin='web'):
"""Move a card between editable projects without replacing its identity or children."""
if idempotency_key:
if len(idempotency_key) > 128:
raise ValidationError('Idempotency key is too long.')
payload = json.dumps({'card': str(card.pk), 'target_project': str(target_project.pk),
'target_column': str(target_column.pk) if target_column else None,
'expected_revision': int(expected_revision)}, sort_keys=True)
payload_hash = hashlib.sha256(payload.encode()).hexdigest()
user.__class__.objects.select_for_update().get(pk=user.pk)
existing = ProjectMoveKey.objects.select_for_update().filter(user=user, key=idempotency_key).first()
if existing:
if existing.payload_hash != payload_hash:
raise ValidationError('Idempotency key was already used with different move details.')
current = Card.objects.select_for_update().select_related('project').get(pk=card.pk)
project_for(user, current.project_id, write=True)
if current.project_id != target_project.pk:
raise ValidationError('The original move is no longer available to replay.')
return current, existing.result
card = Card.objects.select_for_update().select_related('project', 'column').get(pk=card.pk)
source = project_for(user, card.project_id, write=True)
target_project = project_for(user, target_project.pk, write=True)
if source.pk == target_project.pk:
raise ValidationError('Choose a different project. Use the column move for this project.')
if source.archived or target_project.archived:
raise ValidationError('Cards cannot be moved from or into an archived project.')
if card.revision != int(expected_revision):
raise RevisionConflict(card.revision)
if target_column is None:
active_columns = target_project.board.columns.filter(archived=False)
target_column = active_columns.filter(is_default=True).first() or active_columns.first()
if (target_column is None or target_column.board_id != target_project.board.pk or target_column.archived):
raise ValidationError('Column is not available in the destination project.')
warnings = []
if card.assignee_id and card.assignee_id != target_project.owner_id and not Membership.objects.filter(project=target_project, user_id=card.assignee_id).exists():
warnings.append(f"Assignee {card.assignee.get_full_name() or card.assignee.username} was cleared because they do not have access to the destination project.")
card.assignee = None
old_tags = list(card.tags.all())
target_tags = list(Tag.objects.filter(project=target_project).order_by('pk'))
tags_by_name = {tag.name.casefold(): tag for tag in target_tags}
mapped_tags = []
for tag in old_tags:
match = tags_by_name.get(tag.name.casefold())
if match:
mapped_tags.append(match)
else:
warnings.append(f"Tag “{tag.name}” was cleared because it does not exist in the destination project.")
old_column_id = card.column_id
old_column_name = card.column.name
original_updated_at = card.updated_at
siblings = list(Card.objects.filter(column=target_column, archived=False).exclude(pk=card.pk).order_by('position', 'created_at'))
card.project = target_project
card.column = target_column
card.position = len(siblings)
card.completed_at = timezone.now() if target_column.is_done else None
card.revision += 1
card.full_clean()
card.save(update_fields=['project', 'column', 'position', 'completed_at', 'revision', 'assignee'])
card.updated_at = original_updated_at
card.tags.set(mapped_tags)
for index, sibling in enumerate(Card.objects.filter(column_id=old_column_id, archived=False).order_by('position', 'created_at')):
if sibling.position != index:
sibling.position = index
sibling.save(update_fields=['position'])
for index, sibling in enumerate(siblings):
if sibling.position != index:
sibling.position = index
sibling.save(update_fields=['position'])
# The card's prior activity follows its stable UUID into the destination.
Activity.objects.filter(card=card).update(project=target_project)
CardRevision.objects.create(card=card, revision=card.revision, markdown=card.description_markdown, actor=user)
detail = {'from_project': str(source.pk), 'from_column': str(old_column_id),
'from_column_name': old_column_name, 'to_project': str(target_project.pk),
'to_column': str(target_column.pk), 'to_column_name': target_column.name}
Activity.objects.create(project=source, actor=user, action='card.moved_project_out',
detail={'card_id': str(card.pk), 'title': card.title, **detail}, origin=origin)
Activity.objects.create(project=target_project, card=card, actor=user, action='card.moved_project',
detail=detail, origin=origin)
result = {'source_project_id': str(source.pk), 'source_project_name': source.name,
'source_column_id': str(old_column_id),
'target_project_id': str(target_project.pk), 'target_column_id': str(target_column.pk),
'target_project_name': target_project.name, 'target_column_name': target_column.name,
'revision': card.revision, 'url': f'/projects/cards/{card.pk}/', 'warnings': warnings}
if idempotency_key:
ProjectMoveKey.objects.create(user=user, key=idempotency_key, payload_hash=payload_hash, result=result)
return card, result
@transaction.atomic
def set_default(user, column):
project_for(user, column.board.project_id, write=True)
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
+1
View File
@@ -0,0 +1 @@
.project-card-messages{margin:0 0 1rem}.project-card-message{margin:0;padding:.8rem 1rem;border-radius:.7rem;background:var(--surface);color:var(--text);border:1px solid var(--border)}.project-card-message.success{border-color:var(--accent);background:color-mix(in srgb,var(--accent) 10%,var(--surface))}.project-card-message.error{border-color:var(--danger,#b42318)}.project-card-actions-menu .project-move-unavailable{display:block;padding:.65rem .8rem;color:var(--text-muted);font-size:.8rem}
+47
View File
@@ -0,0 +1,47 @@
(() => {
const dialog = document.querySelector('[data-project-move-dialog]');
if (!dialog || dialog.dataset.initialized) return;
dialog.dataset.initialized = 'true';
const projectSelect = dialog.querySelector('[data-move-project]');
const columnSelect = dialog.querySelector('[data-move-column]');
const confirmation = dialog.querySelector('[data-move-confirmation]');
const form = dialog.querySelector('[data-project-move-form]');
const opener = document.querySelector('[data-open-move-dialog]');
const source = document.querySelector('.project-card-heading .project-card-eyebrow')?.textContent.trim() || 'this project';
const update = () => {
if (!projectSelect || !columnSelect) return;
const selectedProject = projectSelect.selectedOptions[0];
const projectId = selectedProject.value;
const defaultId = selectedProject.dataset.defaultColumn;
const defaultName = selectedProject.dataset.defaultName;
for (const option of columnSelect.options) {
const visible = !option.dataset.projectId || option.dataset.projectId === projectId;
option.hidden = !visible;
option.disabled = !visible;
}
const requested = [...columnSelect.options].find(option => option.value === defaultId);
if (requested) columnSelect.value = requested.value;
else columnSelect.value = '';
const chosen = columnSelect.selectedOptions[0];
const columnName = chosen?.value ? chosen.textContent.split(' · ').slice(1).join(' · ').replace(/ \(default\)$/, '') : defaultName;
confirmation.textContent = `Move this card from ${source} to ${selectedProject.textContent} · ${columnName}? Its notes, files, and history will move with it.`;
};
opener?.addEventListener('click', () => {
update();
dialog.showModal();
});
dialog.querySelectorAll('[data-close-move-dialog]').forEach(button => button.addEventListener('click', () => dialog.close()));
dialog.addEventListener('close', () => opener?.focus());
projectSelect?.addEventListener('change', update);
columnSelect?.addEventListener('change', update);
form?.addEventListener('submit', () => {
const submit = form.querySelector('[data-move-submit]');
if (submit) {
submit.disabled = true;
submit.textContent = 'Moving…';
}
});
update();
})();
File diff suppressed because one or more lines are too long
+2 -1
View File
@@ -1,4 +1,4 @@
<div id="kanban-columns" class="d-flex gap-3 overflow-auto" style="min-height:20rem">
<div id="kanban-columns" class="d-flex gap-3 overflow-auto" style="min-height:20rem" aria-describedby="board-scroll-help">
{% for column in columns %}
<section class="card flex-shrink-0" style="width:19rem;border-top:4px solid {{ column.color }}" data-column-card="{{ column.id }}">
<div class="card-header d-flex justify-content-between align-items-center">
@@ -31,6 +31,7 @@
</div>
</article>
{% endfor %}
{% if not column.visible_cards %}<p class="project-column-empty">{% if show_archived %}No archived cards in this column.{% else %}No cards in this column yet.{% endif %}</p>{% endif %}
</div>
</section>
{% endfor %}
+11 -1
View File
@@ -1 +1,11 @@
<div class="row g-3">{% for project in projects %}<div class="col-md-6 col-xl-4"><div class="card h-100"><div class="card-body"><h2 class="h5"><a href="{% url 'projects:board' project.id %}">{{ project.name }}</a></h2><p>{{ project.description|truncatechars:180 }}</p><small>{{ project.card_count }} cards</small><div class="d-flex flex-wrap align-items-center gap-2 mt-3"><a class="btn btn-outline-primary btn-sm" href="{% url 'projects:docs_home' project.id %}">Browse documentation</a>{% if project.git_repository_url %}<a href="{{ project.git_repository_url }}" rel="noopener noreferrer">Repository</a>{% endif %}</div></div></div></div>{% empty %}<p>No projects found.</p>{% endfor %}</div>{% if page_obj.has_other_pages %}<nav aria-label="Project pages" class="mt-3">{% if page_obj.has_previous %}<a href="?{{ filters_query }}&page={{ page_obj.previous_page_number }}">Previous</a>{% endif %} <span>Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}</span> {% if page_obj.has_next %}<a href="?{{ filters_query }}&page={{ page_obj.next_page_number }}">Next</a>{% endif %}</nav>{% endif %}
{% if projects %}<div class="projects-card-grid" aria-label="{% if show_archived %}Archived projects{% else %}Active projects{% endif %}">
{% for project in projects %}<article class="project-index-card{% if project.archived %} is-archived{% endif %}">
<div class="project-index-card-top"><span class="project-index-icon" aria-hidden="true"><i class="bi bi-kanban"></i></span>{% if project.archived %}<span class="project-archived-badge"><i class="bi bi-archive" aria-hidden="true"></i> Archived</span>{% endif %}</div>
<h2><a href="{% url 'projects:board' project.id %}">{{ project.name }}</a></h2>
<p class="project-index-description">{{ project.description|default:'No project description yet.'|truncatechars:180 }}</p>
<div class="project-index-progress"><div class="project-index-progress-copy"><span>{{ project.done_card_count }} of {{ project.active_card_count }} active cards done</span><strong>{{ project.progress_percent }}%</strong></div><div class="project-index-progress-track" role="progressbar" aria-valuenow="{{ project.progress_percent }}" aria-valuemin="0" aria-valuemax="100" aria-label="{{ project.name }} completion"><span style="width:{{ project.progress_percent }}%"></span></div></div>
<div class="project-index-meta"><span><i class="bi bi-card-checklist" aria-hidden="true"></i>{{ project.card_count }} card{{ project.card_count|pluralize }}</span>{% if project.git_repository_url %}<a href="{{ project.git_repository_url }}" rel="noopener noreferrer"><i class="bi bi-github" aria-hidden="true"></i> Repository</a>{% endif %}</div>
<div class="project-index-actions"><a class="btn btn-success" href="{% url 'projects:board' project.id %}"><i class="bi bi-arrow-up-right" aria-hidden="true"></i> Open board</a><a class="btn btn-outline-secondary" href="{% url 'projects:docs_home' project.id %}"><i class="bi bi-journal-text" aria-hidden="true"></i><span class="visually-hidden">Browse documentation for {{ project.name }}</span><span aria-hidden="true">Docs</span></a></div>
</article>{% endfor %}
</div>{% else %}<div class="projects-empty-state"><span class="projects-empty-icon" aria-hidden="true"><i class="bi bi-kanban"></i></span><h2>{% if query %}No matching projects{% elif show_archived %}No archived projects{% else %}No projects yet{% endif %}</h2><p>{% if query %}Try a different project or card search.{% elif show_archived %}Archived projects will appear here.{% else %}Create a project to start organizing cards and specifications.{% endif %}</p>{% if not query and not show_archived %}<a class="btn btn-success" href="{% url 'projects:create' %}"><i class="bi bi-plus-lg" aria-hidden="true"></i> New project</a>{% endif %}</div>{% endif %}
{% if page_obj.has_other_pages %}<nav class="projects-pagination" aria-label="Project pages">{% if page_obj.has_previous %}<a class="btn btn-outline-secondary" href="?{% if filters_query %}{{ filters_query }}&amp;{% endif %}page={{ page_obj.previous_page_number }}"><i class="bi bi-arrow-left" aria-hidden="true"></i> Previous</a>{% else %}<span></span>{% endif %}<span>Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}</span>{% if page_obj.has_next %}<a class="btn btn-outline-secondary" href="?{% if filters_query %}{{ filters_query }}&amp;{% endif %}page={{ page_obj.next_page_number }}">Next <i class="bi bi-arrow-right" aria-hidden="true"></i></a>{% else %}<span></span>{% endif %}</nav>{% endif %}
+106 -53
View File
@@ -1,59 +1,112 @@
{% extends 'core/base.html' %}
{% load static %}
{% block extra_head %}<link rel="stylesheet" href="{% static 'projects/board_mobile.css' %}">{% endblock %}
{% block content %}
<style>.htmx-indicator{display:none}.htmx-request.htmx-indicator,.htmx-request .htmx-indicator{display:inline}</style>
<div class="d-flex flex-wrap justify-content-between align-items-start gap-3 mb-3">
<div><a href="{% url 'projects:list' %}">All projects</a><h1>{{ project.name }}</h1><p>{{ project.description }}</p>{% if project.git_repository_url %}<a href="{{ project.git_repository_url }}" rel="noopener noreferrer">Repository</a>{% endif %}<p class="mt-2 mb-0">{{ done_count }} of {{ total_count }} cards done</p></div>
<div class="d-flex flex-wrap align-items-center gap-2">
<a class="btn btn-primary" href="{% url 'projects:docs_home' project.id %}">Browse documentation</a>
{% if can_edit %}<a class="btn btn-outline-secondary" href="{% url 'projects:edit' project.id %}">Edit project</a>{% if project.archived %}<form class="d-inline" method="post" action="{% url 'projects:restore' project.id %}">{% csrf_token %}<button class="btn btn-outline-success">Restore project</button></form>{% else %}<form class="d-inline" method="post" action="{% url 'projects:archive' project.id %}">{% csrf_token %}<button class="btn btn-outline-danger">Archive project</button></form><a class="btn btn-success" href="{% url 'projects:card_create' project.id %}">New card</a>{% endif %}{% endif %}
</div>
<div class="project-board-page">
<header class="project-board-header">
<div class="project-board-heading">
<a class="project-back-link" href="{% url 'projects:list' %}"><i class="bi bi-arrow-left" aria-hidden="true"></i><span>All projects</span></a>
<div class="project-title-row"><div><h1>{{ project.name }}</h1>{% if project.git_repository_url %}<a class="project-repo-link" href="{{ project.git_repository_url }}" rel="noopener noreferrer"><i class="bi bi-github" aria-hidden="true"></i> Repository</a>{% endif %}</div>
{% if can_edit %}<details class="project-actions-menu"><summary aria-label="Project actions"><i class="bi bi-three-dots" aria-hidden="true"></i><span class="visually-hidden">Project actions</span></summary><div class="project-actions-popover"><a href="{% url 'projects:edit' project.id %}">Edit project</a>{% if project.archived %}<form method="post" action="{% url 'projects:restore' project.id %}">{% csrf_token %}<button type="submit">Restore project</button></form>{% else %}<form method="post" action="{% url 'projects:archive' project.id %}" onsubmit="return confirm('Archive this project?')">{% csrf_token %}<button type="submit" class="text-danger">Archive project</button></form>{% endif %}</div></details>{% endif %}
</div>
{% if project.description %}<p class="project-description">{{ project.description }}</p>{% endif %}
<div class="project-progress" aria-label="{{ done_count }} of {{ total_count }} cards complete"><div class="project-progress-copy"><strong>{{ done_count }} / {{ total_count }}</strong><span>cards complete</span></div><div class="project-progress-track" role="progressbar" aria-valuenow="{{ progress_percent }}" aria-valuemin="0" aria-valuemax="100" aria-label="Project completion"><span style="width:{{ progress_percent }}%"></span></div></div>
</div>
<div class="project-header-actions">{% if can_edit and not project.archived %}<a class="btn btn-success project-new-card" href="{% url 'projects:card_create' project.id %}"><i class="bi bi-plus-lg" aria-hidden="true"></i> New card</a>{% endif %}<a class="btn btn-outline-secondary project-docs-link" href="{% url 'projects:docs_home' project.id %}"><i class="bi bi-journal-text" aria-hidden="true"></i> Browse documentation</a></div>
</header>
<div class="project-priority-summary" aria-label="Open cards by priority">{% for label,count in priority_counts %}<span><i class="priority-dot priority-{{ label|lower }}" aria-hidden="true"></i>{{ label }} <strong>{{ count }}</strong></span>{% endfor %}</div>
<form class="project-board-filters" method="get" role="search" id="project-board-filters">
<label class="project-search"><i class="bi bi-search" aria-hidden="true"></i><span class="visually-hidden">Search cards</span><input class="form-control" name="q" value="{{ query }}" placeholder="Search cards and specifications" hx-get="{% url 'projects:board' project.id %}" hx-trigger="input changed delay:300ms" hx-target="#board-results" hx-include="closest form" hx-indicator="#board-search-loading"></label>
<button class="btn btn-outline-secondary project-filter-open" type="button" aria-haspopup="dialog" aria-controls="project-filter-sheet" aria-expanded="false"><i class="bi bi-sliders" aria-hidden="true"></i><span>Filters</span><span class="project-filter-count" data-filter-count aria-label="{{ active_filter_count }} active filters" {% if not active_filter_count %}hidden{% endif %}>{{ active_filter_count }}</span></button>
<section class="project-filter-sheet" id="project-filter-sheet" role="dialog" aria-modal="true" aria-labelledby="filter-sheet-title" hidden>
<div class="project-filter-scrim" data-filter-close></div><div class="project-filter-panel"><div class="project-filter-heading"><h2 id="filter-sheet-title">Filter cards</h2><button type="button" class="project-filter-close" aria-label="Close filters" data-filter-close><i class="bi bi-x-lg" aria-hidden="true"></i></button></div>
<label class="project-filter-field">Priority<select class="form-select" name="priority" aria-label="Priority" hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><option value="">All priorities</option><option value="high" {% if selected_priority == 'high' %}selected{% endif %}>High</option><option value="medium" {% if selected_priority == 'medium' %}selected{% endif %}>Medium</option><option value="low" {% if selected_priority == 'low' %}selected{% endif %}>Low</option></select></label>
<label class="project-filter-field">Type<select class="form-select" name="card_type" aria-label="Card type" hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><option value="">All types</option>{% for value,label in card_types %}<option value="{{ value }}" {% if value == selected_type %}selected{% endif %}>{{ label }}</option>{% endfor %}</select></label>
<label class="project-filter-field">Column<select class="form-select" name="column" aria-label="Column" hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><option value="">All columns</option>{% for choice in columns %}<option value="{{ choice.id }}" {% if choice.id|stringformat:'s' == selected_column %}selected{% endif %}>{{ choice.name }}</option>{% endfor %}</select></label>
<label class="project-filter-field">Assignee<select class="form-select" name="assignee" aria-label="Assignee" hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><option value="">All assignees</option>{% for person in assignable %}<option value="{{ person.id }}" {% if person.id|stringformat:'s' == selected_assignee %}selected{% endif %}>{{ person.username }}</option>{% endfor %}</select></label>
<label class="project-filter-field">Tag<select class="form-select" name="tag" aria-label="Tag" hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><option value="">All tags</option>{% for tag in tags %}<option value="{{ tag.id }}" {% if tag.id|stringformat:'s' == selected_tag %}selected{% endif %}>{{ tag.name }}</option>{% endfor %}</select></label>
<div class="project-filter-footer"><a class="btn btn-link" href="{% url 'projects:board' project.id %}">Clear all</a><button class="btn btn-success" type="button" data-filter-close>Done</button></div>
</div>
</section>
<label class="project-archived-toggle"><input class="form-check-input" type="checkbox" name="archived" value="1" {% if show_archived %}checked{% endif %} hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><span>Show archived cards</span></label>
</form>
<span id="board-search-loading" class="htmx-indicator project-loading" role="status">Updating cards…</span>
{% if can_edit and not show_archived %}<div class="project-bulk-toolbar" id="bulk-toolbar"><span id="bulk-count" role="status" aria-live="polite">0 cards selected</span><button type="button" class="btn btn-outline-primary btn-sm" id="bulk-edit-button" disabled>Bulk edit</button><button type="button" class="btn btn-outline-secondary btn-sm" id="bulk-clear-button">Clear selection</button></div>{% endif %}
<section class="project-board-section" aria-label="Project board"><p class="visually-hidden" id="board-scroll-help">On narrow screens, scroll horizontally to see more columns. Use the move controls on each card to move it without dragging.</p>{% if columns|length > 1 %}<div class="project-board-scroll-hint" aria-hidden="true"><i class="bi bi-arrow-left-right"></i> Scroll to see more columns</div>{% endif %}<div id="board-results">{% include 'projects/_board.html' %}</div></section>
{% if can_edit %}<div class="project-board-management"><a class="btn btn-outline-secondary" href="{% url 'projects:column_create' project.id %}">Add column</a><a class="btn btn-outline-secondary" href="{% url 'projects:tag_create' project.id %}">Add tag</a></div>{% endif %}
<section class="project-activity" id="project-activity" aria-labelledby="project-activity-title"><div class="project-section-heading"><div><p class="project-section-eyebrow">UPDATES</p><h2 id="project-activity-title">Recent activity</h2></div>{% if older_activity %}<a href="#all-project-activity" data-open-activity>View all</a>{% endif %}</div>
{% if recent_activity %}<ol class="project-activity-list">{% for event in recent_activity %}<li><span class="project-activity-marker" aria-hidden="true"><i class="bi bi-arrow-left-right"></i></span><div><p>{% if event.card %}<a href="{% url 'projects:card' event.card_id %}">{{ event.card.title }}</a> {{ event.display_action }}{% else %}{{ event.display_action }}{% endif %}</p><small>{% if event.actor %}{{ event.actor }}{% else %}A former member{% endif %} · <time datetime="{{ event.created_at|date:'c' }}" title="{{ event.created_at|date:'DATETIME_FORMAT' }}">{{ event.created_at|timesince }} ago</time></small></div></li>{% endfor %}</ol>
{% if older_activity %}<details class="project-all-activity" id="all-project-activity"><summary>View all activity ({{ older_activity|length }} older events)</summary><ol class="project-activity-list">{% for event in older_activity %}<li><span class="project-activity-marker" aria-hidden="true"><i class="bi bi-arrow-left-right"></i></span><div><p>{% if event.card %}<a href="{% url 'projects:card' event.card_id %}">{{ event.card.title }}</a> {{ event.display_action }}{% else %}{{ event.display_action }}{% endif %}</p><small>{% if event.actor %}{{ event.actor }}{% else %}A former member{% endif %} · <time datetime="{{ event.created_at|date:'c' }}">{{ event.created_at|date:'M j, Y · H:i' }}</time></small></div></li>{% endfor %}</ol></details>{% endif %}
{% else %}<p class="project-activity-empty">No activity yet. Updates will appear here.</p>{% endif %}
</section>
</div>
<div class="d-flex gap-3 flex-wrap mb-3">{% for label,count in priority_counts %}<span class="badge text-bg-light border">{{ label }}: {{ count }} open</span>{% endfor %}</div>
<form class="row g-2 mb-3" method="get" role="search">
<div class="col"><input class="form-control" name="q" value="{{ query }}" placeholder="Search cards and specifications" aria-label="Search cards" hx-get="{% url 'projects:board' project.id %}" hx-trigger="input changed delay:300ms" hx-target="#board-results" hx-include="closest form" hx-indicator="#board-search-loading"></div>
<div class="col-auto"><select class="form-select" name="priority" aria-label="Priority" hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><option value="">All priorities</option><option value="high" {% if selected_priority == 'high' %}selected{% endif %}>High</option><option value="medium" {% if selected_priority == 'medium' %}selected{% endif %}>Medium</option><option value="low" {% if selected_priority == 'low' %}selected{% endif %}>Low</option></select></div>
<div class="col-auto"><select class="form-select" name="card_type" aria-label="Card type" hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><option value="">All types</option>{% for value,label in card_types %}<option value="{{ value }}" {% if value == selected_type %}selected{% endif %}>{{ label }}</option>{% endfor %}</select></div>
<div class="col-auto"><select class="form-select" name="column" aria-label="Column" hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><option value="">All columns</option>{% for choice in columns %}<option value="{{ choice.id }}" {% if choice.id|stringformat:'s' == selected_column %}selected{% endif %}>{{ choice.name }}</option>{% endfor %}</select></div>
<div class="col-auto"><select class="form-select" name="assignee" aria-label="Assignee" hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><option value="">All assignees</option>{% for person in assignable %}<option value="{{ person.id }}" {% if person.id|stringformat:'s' == selected_assignee %}selected{% endif %}>{{ person.username }}</option>{% endfor %}</select></div>
<div class="col-auto"><select class="form-select" name="tag" aria-label="Tag" hx-get="{% url 'projects:board' project.id %}" hx-trigger="change" hx-target="#board-results" hx-include="closest form"><option value="">All tags</option>{% for tag in tags %}<option value="{{ tag.id }}" {% if tag.id|stringformat:'s' == selected_tag %}selected{% endif %}>{{ tag.name }}</option>{% endfor %}</select></div>
<div class="col-auto"><label><input type="checkbox" name="archived" value="1" {% if show_archived %}checked{% endif %}> Archived</label></div>
<div class="col-auto"><a class="btn btn-outline-secondary" href="{% url 'projects:board' project.id %}">Clear</a></div>
</form>
<span id="board-search-loading" class="htmx-indicator" role="status">Searching…</span>
{% if can_edit and not show_archived %}<div class="d-flex align-items-center gap-2 mb-2" id="bulk-toolbar"><span id="bulk-count" role="status" aria-live="polite">0 cards selected</span><button type="button" class="btn btn-outline-primary btn-sm" id="bulk-edit-button" disabled>Bulk edit</button><button type="button" class="btn btn-outline-secondary btn-sm" id="bulk-clear-button">Clear selection</button></div>{% endif %}
<div id="board-results">{% include 'projects/_board.html' %}</div>
{% if can_edit %}<a class="btn btn-outline-secondary mt-3" href="{% url 'projects:column_create' project.id %}">Add column</a>
<a class="btn btn-outline-secondary mt-3" href="{% url 'projects:tag_create' project.id %}">Add tag</a>{% endif %}
<h2 class="h5 mt-4">Recent activity</h2><ul>{% for event in recent_activity %}<li>{{ event.created_at }} · {{ event.action }}{% if event.actor %} by {{ event.actor }}{% endif %}</li>{% empty %}<li>No activity yet.</li>{% endfor %}</ul>
<script src="https://unpkg.com/htmx.org@2.0.4"></script>
{% if can_edit %}
<script src="https://cdn.jsdelivr.net/npm/sortablejs@1.15.6/Sortable.min.js"></script>
<script>
const csrf = document.querySelector('[name=csrfmiddlewaretoken]').value;
function wireBoard() {
document.querySelectorAll('[data-column]').forEach(el => new Sortable(el, {group:'cards', animation:150, onEnd:event => {
const form = new FormData(); form.append('column_id', event.to.dataset.column); form.append('position', event.newIndex);
fetch(event.item.dataset.move, {method:'POST', headers:{'X-CSRFToken':csrf}, body:form}).then(response => {if (!response.ok) location.reload()});
}}));
const columns = document.querySelector('#kanban-columns');
if (columns) new Sortable(columns, {animation:150, handle:'.card-header', onEnd:() => {
const form = new FormData();
columns.querySelectorAll('[data-column-card]').forEach(item => form.append('columns', item.dataset.columnCard));
fetch('{% url 'projects:column_reorder' project.id %}', {method:'POST', headers:{'X-CSRFToken':csrf}, body:form}).then(response => {if (!response.ok) location.reload()});
}});
}
wireBoard(); document.body.addEventListener('htmx:afterSwap', wireBoard);
const bulkCount = document.getElementById('bulk-count');
function selectedBulkCards() { return [...document.querySelectorAll('.bulk-card-choice:checked')]; }
function updateBulkCount() { if (!bulkCount) return; const n = selectedBulkCards().length; bulkCount.textContent = `${n} card${n === 1 ? '' : 's'} selected`; document.getElementById('bulk-edit-button').disabled = n === 0; }
document.addEventListener('change', event => { if (event.target.matches('.bulk-card-choice')) updateBulkCount(); });
document.getElementById('bulk-clear-button')?.addEventListener('click', () => { selectedBulkCards().forEach(box => box.checked = false); updateBulkCount(); });
document.getElementById('bulk-edit-button')?.addEventListener('click', () => {
const query = new URLSearchParams(); selectedBulkCards().forEach(box => query.append('card', box.value));
location.href = '{% url 'projects:cards_bulk_edit' project.id %}?' + query.toString();
});
document.body.addEventListener('htmx:afterSwap', updateBulkCount);
</script>
{% csrf_token %}
{% endif %}
<script src="https://unpkg.com/htmx.org@2.0.4"></script>
{% if can_edit %}<script src="https://cdn.jsdelivr.net/npm/sortablejs@1.15.6/Sortable.min.js"></script>{% endif %}
<script>
(() => {
const csrf = document.querySelector('[name=csrfmiddlewaretoken]')?.value;
const sortables = new WeakMap();
function destroyBoard(root) { if (!root) return; root.querySelectorAll('[data-column], #kanban-columns').forEach(node => { sortables.get(node)?.destroy(); sortables.delete(node); }); }
function wireBoard(root = document) {
{% if can_edit %}
root.querySelectorAll('[data-column]').forEach(el => { if (sortables.has(el)) return; const instance = new Sortable(el, {group:'cards', animation:150, onEnd:event => {
const form = new FormData(); form.append('column_id', event.to.dataset.column); form.append('position', event.newIndex);
fetch(event.item.dataset.move, {method:'POST', headers:{'X-CSRFToken':csrf}, body:form}).then(response => {if (!response.ok) location.reload()});
}}); sortables.set(el, instance); });
const columns = root.querySelector('#kanban-columns');
if (columns && !sortables.has(columns)) sortables.set(columns, new Sortable(columns, {animation:150, handle:'.card-header', onEnd:() => {
const form = new FormData(); columns.querySelectorAll('[data-column-card]').forEach(item => form.append('columns', item.dataset.columnCard));
fetch('{% url 'projects:column_reorder' project.id %}', {method:'POST', headers:{'X-CSRFToken':csrf}, body:form}).then(response => {if (!response.ok) location.reload()});
}}));
{% endif %}
}
wireBoard();
document.body.addEventListener('htmx:beforeSwap', event => { if (event.detail.target?.id === 'board-results') destroyBoard(event.detail.target); });
document.body.addEventListener('htmx:afterSwap', event => { if (event.detail.target?.id === 'board-results') wireBoard(event.detail.target); updateBulkCount(); });
const bulkCount = document.getElementById('bulk-count');
function selectedBulkCards() { return [...document.querySelectorAll('.bulk-card-choice:checked')]; }
function updateBulkCount() {
const toolbar = document.getElementById('bulk-toolbar');
const archivedToggle = document.querySelector('[name="archived"]');
if (toolbar && archivedToggle) toolbar.hidden = archivedToggle.checked;
if (!bulkCount || toolbar?.hidden) return;
const n = selectedBulkCards().length; bulkCount.textContent = `${n} card${n === 1 ? '' : 's'} selected`; document.getElementById('bulk-edit-button').disabled = n === 0;
}
document.addEventListener('change', event => { if (event.target.matches('.bulk-card-choice')) updateBulkCount(); });
document.getElementById('bulk-clear-button')?.addEventListener('click', () => { selectedBulkCards().forEach(box => box.checked = false); updateBulkCount(); });
document.getElementById('bulk-edit-button')?.addEventListener('click', () => { const query = new URLSearchParams(); selectedBulkCards().forEach(box => query.append('card', box.value)); location.href = '{% url 'projects:cards_bulk_edit' project.id %}?' + query.toString(); });
const sheet = document.getElementById('project-filter-sheet');
const openButton = document.querySelector('.project-filter-open');
const firstField = sheet?.querySelector('select');
let focusBeforeSheet;
function closeSheet() { if (!sheet || sheet.hidden) return; sheet.hidden = true; openButton.setAttribute('aria-expanded', 'false'); document.body.style.overflow = ''; focusBeforeSheet?.focus(); }
openButton?.addEventListener('click', () => { focusBeforeSheet = document.activeElement; sheet.hidden = false; openButton.setAttribute('aria-expanded', 'true'); document.body.style.overflow = 'hidden'; firstField?.focus(); });
sheet?.querySelectorAll('[data-filter-close]').forEach(button => button.addEventListener('click', closeSheet));
sheet?.addEventListener('keydown', event => {
if (event.key === 'Escape') { closeSheet(); return; }
if (event.key !== 'Tab') return;
const focusable = [...sheet.querySelectorAll('a[href],button:not([disabled]),select:not([disabled]),input:not([disabled]),[tabindex]:not([tabindex="-1"])')];
if (!focusable.length) return;
const first = focusable[0], last = focusable[focusable.length - 1];
if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last.focus(); }
else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first.focus(); }
});
sheet?.addEventListener('click', event => { if (event.target.classList.contains('project-filter-scrim')) closeSheet(); });
const filterCountBadge = document.querySelector('[data-filter-count]');
function updateFilterCount() {
if (!filterCountBadge) return;
const count = ['priority','card_type','column','assignee','tag'].filter(name => document.querySelector(`[name="${name}"]`)?.value).length;
filterCountBadge.textContent = count; filterCountBadge.hidden = count === 0;
filterCountBadge.setAttribute('aria-label', `${count} active filter${count === 1 ? '' : 's'}`);
}
document.getElementById('project-board-filters')?.addEventListener('change', updateFilterCount);
document.querySelector('[data-open-activity]')?.addEventListener('click', () => { const details = document.getElementById('all-project-activity'); if (details) details.open = true; });
})();
</script>
{% endblock %}
+43 -14
View File
@@ -1,18 +1,47 @@
{% extends 'core/base.html' %}{% load project_markdown static %}
{% block extra_head %}<link rel="stylesheet" href="{% static 'projects/card_detail.css' %}"><link rel="stylesheet" href="{% static 'projects/card_move.css' %}">{% endblock %}
{% block content %}
<a href="{% url 'projects:board' card.project_id %}">← {{ card.project.name }}</a>
<div class="d-flex justify-content-between mt-3"><h1>{{ card.title }}</h1>{% if can_edit %}<div><a class="btn btn-outline-secondary" href="{% url 'projects:card_edit' card.id %}">Edit</a> {% if card.archived %}<form method="post" action="{% url 'projects:card_restore' card.id %}" class="d-inline">{% csrf_token %}<button class="btn btn-outline-success">Restore</button></form>{% else %}<form method="post" action="{% url 'projects:card_archive' card.id %}" class="d-inline">{% csrf_token %}<button class="btn btn-outline-danger">Archive</button></form>{% endif %}</div>{% endif %}</div>
<p><span class="badge text-bg-secondary">{{ card.get_priority_display }}</span> {{ card.column.name }} · {{ card.get_card_type_display }} · Revision {{ card.revision }}</p>
<div class="card card-body mb-4 markdown-body">{{ card.description_markdown|safe_markdown }}</div>
<details><summary>Raw Markdown</summary><pre>{{ card.description_markdown }}</pre></details>
<section aria-labelledby="card-files-heading" class="mt-4"><h2 id="card-files-heading" class="h4">Card files</h2>
{% include 'projects/_attachment_list.html' with files=card_files %}
{% if can_edit %}<form method="post" enctype="multipart/form-data" action="{% url 'projects:attachment_upload' card.id %}" class="mb-3" data-attachment-upload>{% csrf_token %}<label for="card-files-input" class="form-label">Add card files</label><input id="card-files-input" class="form-control" type="file" name="files" multiple required><button class="btn btn-outline-primary mt-2">Upload files</button><progress hidden max="100" value="0" aria-label="Upload progress"></progress><span role="status" aria-live="polite"></span></form>{% endif %}</section>
<h2 class="h4 mt-4">Progress notes</h2>
{% for comment in comments %}<div class="card card-body mb-2"><small>{{ comment.author }} · {{ comment.created_at }}</small><p>{{ comment.body|linebreaksbr }}</p><h3 class="h6">Files on this progress note</h3>
{% include 'projects/_attachment_list.html' with files=comment.attachments.all %}
{% if can_edit %}<form method="post" enctype="multipart/form-data" action="{% url 'projects:attachment_upload' card.id %}" data-attachment-upload>{% csrf_token %}<input type="hidden" name="comment_id" value="{{ comment.id }}"><label for="note-files-{{ comment.id }}" class="form-label">Add files to this note</label><input id="note-files-{{ comment.id }}" class="form-control" type="file" name="files" multiple required><button class="btn btn-outline-primary mt-2">Upload files</button><progress hidden max="100" value="0" aria-label="Upload progress"></progress><span role="status" aria-live="polite"></span></form>{% endif %}</div>{% endfor %}
{% if can_edit %}<form method="post" action="{% url 'projects:card_comment' card.id %}">{% csrf_token %}<label for="comment">Add note</label><textarea class="form-control" id="comment" name="body" required></textarea><button class="btn btn-success mt-2">Add note</button></form>{% endif %}
<h2 class="h4 mt-4">History</h2><ul>{% for event in card.activity.all %}<li>{{ event.created_at }} · {{ event.action }} by {{ event.actor }}</li>{% endfor %}</ul>
<div class="project-card-page">
{% if messages %}<div class="project-card-messages" aria-live="polite">{% for message in messages %}<p class="project-card-message {{ message.tags }}" role="{% if message.tags == 'error' %}alert{% else %}status{% endif %}">{{ message }}</p>{% endfor %}</div>{% endif %}
<nav class="project-card-breadcrumb" aria-label="Breadcrumb"><a href="{% url 'projects:board' card.project_id %}"><i class="bi bi-arrow-left" aria-hidden="true"></i><span>{{ card.project.name }}</span></a><span aria-hidden="true">/</span><span aria-current="page">{{ card.title }}</span></nav>
{% if card.archived %}<p class="project-card-archived" role="status"><i class="bi bi-archive" aria-hidden="true"></i> This card is archived.</p>{% endif %}
<header class="project-card-header">
<div class="project-card-heading"><p class="project-card-eyebrow">{{ card.project.name }}</p><h1>{{ card.title }}</h1><div class="project-card-badges"><span class="project-card-badge priority-{{ card.priority }}">{{ card.get_priority_display }} priority</span><span class="project-card-badge"><i class="bi bi-kanban" aria-hidden="true"></i>{{ card.column.name }}</span><span class="project-card-badge"><i class="bi bi-bookmark" aria-hidden="true"></i>{{ card.get_card_type_display }}</span><span class="project-card-badge">Revision {{ card.revision }}</span>{% if card.is_blocked %}<span class="project-card-badge blocked"><i class="bi bi-exclamation-circle" aria-hidden="true"></i>Blocked</span>{% endif %}</div></div>
{% if can_edit %}<details class="project-card-actions"><summary aria-label="Card actions"><i class="bi bi-three-dots" aria-hidden="true"></i><span class="visually-hidden">Card actions</span></summary><div class="project-card-actions-menu"><a href="{% url 'projects:card_edit' card.id %}"><i class="bi bi-pencil" aria-hidden="true"></i>Edit card</a>{% if destination_options %}<button type="button" data-open-move-dialog><i class="bi bi-box-arrow-right" aria-hidden="true"></i>Move to project</button>{% else %}<span class="project-move-unavailable" role="status">No other editable projects are available.</span>{% endif %}{% if card.archived %}<form method="post" action="{% url 'projects:card_restore' card.id %}">{% csrf_token %}<button type="submit"><i class="bi bi-arrow-counterclockwise" aria-hidden="true"></i>Restore card</button></form>{% else %}<form method="post" action="{% url 'projects:card_archive' card.id %}" onsubmit="return confirm('Archive this card?')">{% csrf_token %}<button type="submit" class="danger"><i class="bi bi-archive" aria-hidden="true"></i>Archive card</button></form>{% endif %}</div></details>{% endif %}
</header>
{% if can_edit %}<dialog class="project-move-dialog" data-project-move-dialog aria-labelledby="move-card-title"><form method="post" action="{% url 'projects:card_move_project' card.id %}" data-project-move-form>{% csrf_token %}<input type="hidden" name="expected_revision" value="{{ card.revision }}"><input type="hidden" name="idempotency_key" value="{{ move_idempotency_key }}"><div class="project-move-dialog-heading"><div><p class="project-card-eyebrow">MOVE CARD</p><h2 id="move-card-title">Move to another project</h2></div><button type="button" class="project-move-close" data-close-move-dialog aria-label="Close dialog">×</button></div>
{% if destination_options %}<label for="move-target-project">Destination project</label><select id="move-target-project" class="form-select" name="target_project_id" required data-move-project>{% for option in destination_options %}<option value="{{ option.project.pk }}" data-default-column="{% if option.default_column %}{{ option.default_column.pk }}{% endif %}" data-default-name="{% if option.default_column %}{{ option.default_column.name }}{% else %}No default column{% endif %}">{{ option.project.name }}</option>{% endfor %}</select><label for="move-target-column">Destination column</label><select id="move-target-column" class="form-select" name="target_column_id" data-move-column><option value="" data-project-id="">Use project default</option>{% for option in destination_options %}{% for column in option.columns %}<option value="{{ column.pk }}" data-project-id="{{ option.project.pk }}"{% if forloop.parentloop.first and column.is_default %} selected{% endif %}>{{ option.project.name }} · {{ column.name }}{% if column.is_default %} (default){% endif %}</option>{% endfor %}{% endfor %}</select><p class="project-move-confirmation" data-move-confirmation role="status" aria-live="polite">This moves the card from {{ card.project.name }} to the selected project.</p><div class="project-move-dialog-actions"><button type="button" class="btn btn-outline-secondary" data-close-move-dialog>Cancel</button><button type="submit" class="btn btn-success" data-move-submit>Move card</button></div>{% else %}<p>No other active projects are available for you to edit.</p><button type="button" class="btn btn-outline-secondary" data-close-move-dialog>Close</button>{% endif %}</form></dialog>{% endif %}
<div class="project-card-layout">
<main class="project-card-main">
<section class="project-detail-panel project-description-panel" aria-labelledby="card-description-title"><div class="project-detail-heading"><div><p class="project-card-eyebrow">CARD DETAILS</p><h2 id="card-description-title">Description</h2></div><span class="project-updated">Updated {{ card.updated_at|timesince }} ago</span></div>
{% if card.description_markdown %}<div class="project-card-markdown markdown-body">{{ card.description_markdown|safe_markdown }}</div>{% else %}<p class="project-empty-state">No description has been added to this card.</p>{% endif %}
<details class="project-raw-markdown"><summary><i class="bi bi-code-slash" aria-hidden="true"></i> View raw Markdown</summary><pre><code>{{ card.description_markdown }}</code></pre></details>
</section>
<section class="project-card-notes" id="progress-notes" aria-labelledby="progress-notes-title"><div class="project-detail-heading"><div><p class="project-card-eyebrow">DISCUSSION</p><h2 id="progress-notes-title">Progress notes <span class="project-count">{{ comments|length }}</span></h2></div></div>
{% if can_edit %}<form class="project-note-form" method="post" action="{% url 'projects:card_comment' card.id %}">{% csrf_token %}<label for="comment">Add a progress note</label><textarea class="form-control" id="comment" name="body" rows="3" required placeholder="Share an update…"></textarea><div class="project-note-submit"><small>Notes are visible to project members.</small><button class="btn btn-success" type="submit"><i class="bi bi-send" aria-hidden="true"></i> Add note</button></div></form>{% endif %}
<div class="project-note-list">{% for comment in comments %}<article class="project-note-card"><header><span class="project-note-avatar" aria-hidden="true">{{ comment.author.username|slice:':1'|upper }}</span><div><strong>{{ comment.author }}</strong><time datetime="{{ comment.created_at|date:'c' }}" title="{{ comment.created_at|date:'DATETIME_FORMAT' }}">{{ comment.created_at|date:'M j, Y · H:i' }}</time></div></header><p class="project-note-body">{{ comment.body|linebreaksbr }}</p><h3 class="project-note-files-title">Files on this progress note</h3>{% include 'projects/_attachment_list.html' with files=comment.attachments.all %}
{% if can_edit %}<form method="post" enctype="multipart/form-data" action="{% url 'projects:attachment_upload' card.id %}" class="project-upload-form" data-attachment-upload>{% csrf_token %}<input type="hidden" name="comment_id" value="{{ comment.id }}"><label for="note-files-{{ comment.id }}"><i class="bi bi-paperclip" aria-hidden="true"></i> Add files to this note</label><input id="note-files-{{ comment.id }}" class="form-control" type="file" name="files" multiple required><button class="btn btn-outline-secondary" type="submit">Upload files</button><progress hidden max="100" value="0" aria-label="Upload progress"></progress><span role="status" aria-live="polite"></span></form>{% endif %}
</article>{% empty %}<p class="project-empty-state">No progress notes yet.</p>{% endfor %}</div>
</section>
</main>
<aside class="project-card-sidebar" aria-label="Card information">
<section class="project-detail-panel project-properties" aria-labelledby="card-properties-title"><div class="project-detail-heading"><h2 id="card-properties-title">Card info</h2></div><dl>
<div><dt>Status</dt><dd>{{ card.column.name }}</dd></div><div><dt>Priority</dt><dd><span class="project-property-dot priority-{{ card.priority }}"></span>{{ card.get_priority_display }}</dd></div><div><dt>Type</dt><dd>{{ card.get_card_type_display }}</dd></div><div><dt>Assignee</dt><dd>{% if card.assignee %}{{ card.assignee.get_full_name|default:card.assignee.username }}{% else %}Unassigned{% endif %}</dd></div><div><dt>Due date</dt><dd>{% if card.due_date %}<time datetime="{{ card.due_date|date:'Y-m-d' }}">{{ card.due_date|date:'M j, Y' }}</time>{% else %}No due date{% endif %}</dd></div><div><dt>Created</dt><dd><time datetime="{{ card.created_at|date:'c' }}">{{ card.created_at|date:'M j, Y' }}</time></dd></div>
{% if card.tags.exists %}<div class="project-tags-row"><dt>Tags</dt><dd>{% for tag in card.tags.all %}<span class="project-tag">{{ tag.name }}</span>{% endfor %}</dd></div>{% endif %}
</dl>{% if card.is_blocked and card.blocked_reason %}<div class="project-blocked-reason"><strong>Blocked because</strong><p>{{ card.blocked_reason }}</p></div>{% endif %}</section>
<section class="project-detail-panel project-card-files" aria-labelledby="card-files-heading"><div class="project-detail-heading"><h2 id="card-files-heading">Card files <span class="project-count">{{ card_files|length }}</span></h2></div>{% include 'projects/_attachment_list.html' with files=card_files %}
{% if can_edit %}<form method="post" enctype="multipart/form-data" action="{% url 'projects:attachment_upload' card.id %}" class="project-upload-form" data-attachment-upload>{% csrf_token %}<label for="card-files-input"><i class="bi bi-paperclip" aria-hidden="true"></i> Add card files</label><input id="card-files-input" class="form-control" type="file" name="files" multiple required><button class="btn btn-outline-secondary" type="submit">Upload files</button><progress hidden max="100" value="0" aria-label="Upload progress"></progress><span role="status" aria-live="polite"></span></form>{% endif %}
</section>
<details class="project-detail-panel project-card-history"><summary><span><i class="bi bi-clock-history" aria-hidden="true"></i> History</span><span class="project-count">{{ history|length }}</span></summary>{% if history %}<ol class="project-history-list">{% for event in history %}<li><p>{{ event.display_action }}</p><small>{% if event.actor %}{{ event.actor }}{% else %}A former member{% endif %} · <time datetime="{{ event.created_at|date:'c' }}" title="{{ event.created_at|date:'DATETIME_FORMAT' }}">{{ event.created_at|date:'M j, Y · H:i' }}</time></small></li>{% endfor %}</ol>{% else %}<p class="project-empty-state">No history yet.</p>{% endif %}</details>
</aside>
</div>
</div>
<script defer src="{% static 'projects/attachments.js' %}"></script>
{% if can_edit and destination_options %}<script defer src="{% static 'projects/card_move.js' %}"></script>{% endif %}
{% endblock %}
+16 -1
View File
@@ -1 +1,16 @@
{% extends 'core/base.html' %}{% block content %}<style>.htmx-indicator{display:none}.htmx-request.htmx-indicator,.htmx-request .htmx-indicator{display:inline}</style><div class="d-flex justify-content-between align-items-center mb-4"><div><h1>Projects</h1><p>Boards and specifications across your workspace.</p></div><a class="btn btn-success" href="{% url 'projects:create' %}">New project</a></div><p><a href="{% url 'projects:list' %}">Active</a> · <a href="{% url 'projects:list' %}?archived=1">Archived</a></p><form method="get" role="search" class="mb-3"><label for="project-search" class="form-label">Search projects and cards</label><input id="project-search" class="form-control" name="q" value="{{ query }}" hx-get="{% url 'projects:list' %}{% if show_archived %}?archived=1{% endif %}" hx-trigger="input changed delay:300ms" hx-target="#project-results" hx-indicator="#search-loading"><span id="search-loading" class="htmx-indicator" role="status">Searching…</span> <a class="btn btn-sm btn-outline-secondary" href="{% url 'projects:list' %}{% if show_archived %}?archived=1{% endif %}">Clear</a></form><div id="project-results">{% include 'projects/_project_list.html' %}</div><script src="https://unpkg.com/htmx.org@2.0.4"></script>{% endblock %}
{% extends 'core/base.html' %}{% load static %}
{% block extra_head %}<link rel="stylesheet" href="{% static 'projects/project_list.css' %}">{% endblock %}
{% block content %}
<div class="projects-index">
<header class="projects-index-header"><div><p class="projects-index-eyebrow">WORKSPACE</p><h1>Projects</h1><p class="projects-index-intro">Boards and specifications across your workspace.</p></div><a class="btn btn-success projects-new-button" href="{% url 'projects:create' %}"><i class="bi bi-plus-lg" aria-hidden="true"></i> New project</a></header>
<nav class="projects-view-tabs" aria-label="Project views"><a href="{% url 'projects:list' %}{% if query %}?q={{ query|urlencode }}{% endif %}" {% if not show_archived %}aria-current="page"{% endif %}><i class="bi bi-grid" aria-hidden="true"></i> Active</a><a href="{% url 'projects:list' %}?{% if query %}q={{ query|urlencode }}&amp;{% endif %}archived=1" {% if show_archived %}aria-current="page"{% endif %}><i class="bi bi-archive" aria-hidden="true"></i> Archived</a></nav>
<form class="projects-search-form" method="get" role="search">
{% if show_archived %}<input type="hidden" name="archived" value="1">{% endif %}
<label class="projects-search-box" for="project-search"><i class="bi bi-search" aria-hidden="true"></i><span class="visually-hidden">Search projects and cards</span><input id="project-search" class="form-control" name="q" value="{{ query }}" placeholder="Search projects and cards" hx-get="{% url 'projects:list' %}{% if show_archived %}?archived=1{% endif %}" hx-trigger="input changed delay:300ms" hx-target="#project-results" hx-include="closest form" hx-indicator="#search-loading"></label>
<span id="search-loading" class="htmx-indicator" role="status">Searching projects…</span>
{% if query %}<a class="btn btn-outline-secondary projects-clear-search" href="{% url 'projects:list' %}{% if show_archived %}?archived=1{% endif %}"><i class="bi bi-x-lg" aria-hidden="true"></i><span>Clear</span></a>{% endif %}
</form>
<div id="project-results">{% include 'projects/_project_list.html' %}</div>
</div>
<script src="https://unpkg.com/htmx.org@2.0.4"></script>
{% endblock %}
+41 -1
View File
@@ -1,10 +1,12 @@
import base64
import hashlib
import json
import asyncio
import os
from urllib.parse import parse_qs, urlparse
from django.contrib.auth import get_user_model
from django.test import TestCase, Client as DjangoClient
from django.test import TestCase, TransactionTestCase, Client as DjangoClient
from django.conf import settings
from asgiref.sync import async_to_sync
from unittest.mock import patch
@@ -58,6 +60,13 @@ class OAuthMcpTests(TestCase):
project = create_project(self.user, name='Private')
self.assertEqual(self.client.get(f'/projects/{project.pk}/').status_code, 302)
def test_cross_project_move_tool_is_registered_with_revision_and_uuid_contract(self):
tool = create_server()._tool_manager.get_tool('cards_move_project')
self.assertIn('another editable project', tool.description)
self.assertEqual(set(tool.parameters['required']), {'card_id', 'target_project', 'expected_revision'})
self.assertIn('idempotency_key', tool.parameters['properties'])
def test_client_registration_requires_authenticated_user_and_csrf(self):
metadata = {'client_name': 'Private test client', 'redirect_uris': ['https://client.example/callback'],
'grant_types': ['authorization_code', 'refresh_token'], 'token_endpoint_auth_method': 'none'}
@@ -90,3 +99,34 @@ class OAuthMcpTests(TestCase):
with patch('mcp_server.server.get_access_token', return_value=read):
with self.assertRaises(ToolError):
async_to_sync(server.call_tool)('cards_set_priority', {'card_id': card['id'], 'priority': 'high', 'expected_revision': 1})
class CrossProjectMoveMcpTests(TransactionTestCase):
def test_cross_project_move_mcp_handler_returns_same_move_result(self):
user = get_user_model().objects.create_user('move-mcp-user', password='test-password')
source = create_project(user, name='MCP source')
destination = create_project(user, name='MCP destination')
from .services import create_card
card = create_card(user, source, title='Move through MCP')
server = create_server()
tool = server._tool_manager.get_tool('cards_move_project')
class InlineAwaitable:
def __init__(self, function):
self.function = function
async def __call__(self):
return self.function()
with patch('mcp_server.server._actor', return_value=user), \
patch('mcp_server.server.sync_to_async', side_effect=lambda function: InlineAwaitable(function)), \
patch.dict(os.environ, {'DJANGO_ALLOW_ASYNC_UNSAFE': 'true'}):
data = asyncio.run(tool.fn(card_id=str(card.pk), target_project=str(destination.pk),
target_column_id=str(destination.board.columns.get(is_default=True).pk),
expected_revision=card.revision))
card.refresh_from_db()
self.assertEqual(data['id'], str(card.pk))
self.assertEqual(data['project_id'], str(destination.pk))
self.assertEqual(data['revision'], 2)
self.assertEqual(data['move']['source_project_id'], str(source.pk))
self.assertEqual(data['move']['target_column_id'], str(card.column_id))
+209 -6
View File
@@ -1,14 +1,14 @@
from django.contrib.auth import get_user_model
from django.test import TestCase, override_settings
from django.test import TestCase, Client, override_settings
from django.core.exceptions import ValidationError
from django.urls import reverse
from django.http import HttpResponse
from django.http import HttpResponse, Http404
from django.utils import timezone
from unittest.mock import patch
from .models import Activity, Card, CardRevision, Membership, Profile
from .models import Activity, Card, CardRevision, CardComment, CardAttachment, Column, Membership, Profile, Tag
from .forms import ProfileForm
from .middleware import ProfileTimezoneMiddleware
from .services import RevisionConflict, bulk_update_cards, card_for, create_card, create_project, move_card, update_card, update_column
from .services import RevisionConflict, bulk_update_cards, card_for, create_card, create_project, move_card, move_card_to_project, update_card, update_column
class ProjectWorkflowTests(TestCase):
@@ -46,17 +46,220 @@ class ProjectWorkflowTests(TestCase):
card.refresh_from_db()
self.assertIsNotNone(card.completed_at)
def test_cross_project_move_preserves_identity_and_children_and_maps_project_data(self):
destination = create_project(self.owner, name='Destination')
card = create_card(self.owner, self.project, title='Keep me', markdown='# Keep this')
source_sibling = create_card(self.owner, self.project, title='Source sibling')
destination_sibling = create_card(self.owner, destination, title='Destination sibling')
original_updated_at = card.updated_at
card.assignee = self.other
card.save(update_fields=['assignee'])
Membership.objects.create(project=destination, user=self.other, role='viewer')
comment = CardComment.objects.create(card=card, author=self.owner, body='Progress note')
attachment = CardAttachment.objects.create(card=card, comment=comment, file='card-attachments/test.txt',
original_filename='test.txt', title='Source file', mime_type='text/plain', byte_size=4, sha256='a' * 64)
source_tag = Tag.objects.create(project=self.project, name='Roadmap')
target_tag = Tag.objects.create(project=destination, name='roadmap')
card.tags.add(source_tag)
old_activity = card.activity.first()
destination_column = destination.board.columns.get(is_default=True)
moved, result = move_card_to_project(self.owner, card, destination,
target_column=destination_column, expected_revision=card.revision, idempotency_key='move-preserve')
moved.refresh_from_db()
self.assertEqual(moved.pk, card.pk)
self.assertEqual(moved.project_id, destination.pk)
self.assertEqual(moved.column_id, destination_column.pk)
self.assertEqual(moved.position, 1)
source_sibling.refresh_from_db()
self.assertEqual(source_sibling.position, 0)
destination_sibling.refresh_from_db()
self.assertEqual(destination_sibling.position, 0)
self.assertEqual(moved.revision, card.revision + 1)
self.assertEqual(moved.description_markdown, '# Keep this')
self.assertEqual(moved.updated_at, original_updated_at)
self.assertEqual(moved.assignee_id, self.other.pk)
self.assertEqual(list(moved.revisions.order_by('revision').values_list('revision', flat=True)), [1, 2])
self.assertEqual(list(moved.tags.all()), [target_tag])
self.assertEqual(moved.comments.get(pk=comment.pk).body, 'Progress note')
self.assertEqual(moved.attachments.get(pk=attachment.pk).file.name, 'card-attachments/test.txt')
old_activity.refresh_from_db()
self.assertEqual(old_activity.project_id, destination.pk)
self.assertTrue(moved.activity.filter(action='card.moved_project').exists())
source_event = Activity.objects.get(project=self.project, action='card.moved_project_out')
self.assertEqual(source_event.detail['card_id'], str(card.pk))
self.assertEqual(result['source_project_id'], str(self.project.pk))
self.assertEqual(result['revision'], moved.revision)
def test_cross_project_move_clears_invalid_assignee_and_tags_with_warnings(self):
destination = create_project(self.owner, name='Destination')
card = create_card(self.owner, self.project, title='Transfer')
card.assignee = self.other
card.save(update_fields=['assignee'])
tag = Tag.objects.create(project=self.project, name='Only here')
card.tags.add(tag)
moved, result = move_card_to_project(self.owner, card, destination, expected_revision=card.revision)
self.assertIsNone(moved.assignee_id)
self.assertFalse(moved.tags.exists())
self.assertEqual(len(result['warnings']), 2)
def test_cross_project_move_validates_access_column_revision_and_idempotency(self):
destination = create_project(self.owner, name='Destination')
private_destination = create_project(self.other, name='Private destination')
archived_destination = create_project(self.owner, name='Archived destination')
archived_destination.archived = True
archived_destination.save(update_fields=['archived'])
card = create_card(self.owner, self.project, title='Transfer')
foreign_column = private_destination.board.columns.get(is_default=True)
with self.assertRaises(ValidationError):
move_card_to_project(self.owner, card, destination, target_column=foreign_column, expected_revision=1)
with self.assertRaises(RevisionConflict):
move_card_to_project(self.owner, card, destination, expected_revision=0)
with self.assertRaises(Http404):
move_card_to_project(self.owner, card, private_destination, expected_revision=1)
with self.assertRaises(ValidationError):
move_card_to_project(self.owner, card, archived_destination, expected_revision=1)
moved, _ = move_card_to_project(self.owner, card, destination, expected_revision=1, idempotency_key='retry-1')
replay, result = move_card_to_project(self.owner, card, destination, expected_revision=1, idempotency_key='retry-1')
self.assertEqual(replay.pk, moved.pk)
self.assertEqual(result['revision'], moved.revision)
with self.assertRaises(ValidationError):
move_card_to_project(self.owner, card, private_destination, expected_revision=1, idempotency_key='retry-1')
def test_cross_project_move_ui_requires_csrf_and_shows_success_or_stale_feedback(self):
destination = create_project(self.owner, name='Destination')
card = create_card(self.owner, self.project, title='Transfer')
browser = Client(enforce_csrf_checks=True)
browser.force_login(self.owner)
detail = browser.get(reverse('projects:card', args=[card.pk]))
self.assertContains(detail, 'Move to project')
self.assertContains(detail, 'Destination')
csrf = browser.cookies['csrftoken'].value
move_url = reverse('projects:card_move_project', args=[card.pk])
payload = {'target_project_id': str(destination.pk), 'target_column_id': '',
'expected_revision': str(card.revision), 'idempotency_key': 'web-move-1'}
self.assertEqual(browser.post(move_url, payload).status_code, 403)
stale = browser.post(move_url, {**payload, 'expected_revision': '0', 'idempotency_key': 'web-stale'}, HTTP_X_CSRFTOKEN=csrf)
self.assertEqual(stale.status_code, 302)
stale_detail = browser.get(reverse('projects:card', args=[card.pk]))
self.assertContains(stale_detail, 'This card changed before it could be moved.')
response = browser.post(move_url, payload, HTTP_X_CSRFTOKEN=csrf)
self.assertEqual(response.status_code, 302)
self.assertEqual(response['Location'], reverse('projects:card', args=[card.pk]))
self.assertEqual(Card.objects.get(pk=card.pk).project_id, destination.pk)
self.assertContains(browser.get(reverse('projects:card', args=[card.pk])), 'Moved “Transfer” from BoomCast to Destination.')
def test_cross_project_move_rolls_back_when_revision_creation_fails(self):
destination = create_project(self.owner, name='Destination')
card = create_card(self.owner, self.project, title='Transfer')
with patch.object(CardRevision.objects, 'create', side_effect=RuntimeError('revision store unavailable')):
with self.assertRaises(RuntimeError):
move_card_to_project(self.owner, card, destination, expected_revision=card.revision)
card.refresh_from_db()
self.assertEqual(card.project_id, self.project.pk)
self.assertEqual(card.revision, 1)
self.assertFalse(Activity.objects.filter(action='card.moved_project_out').exists())
def test_board_filters_and_escaped_markdown(self):
card = create_card(self.owner, self.project, title='Danger', markdown='<script>alert(1)</script>\n\n# Safe')
self.client.force_login(self.owner)
response = self.client.get(reverse('projects:board', args=[self.project.pk]), {'priority': 'medium'})
self.assertContains(response, 'Danger')
visible = [card for column in response.context['columns'] for card in column.visible_cards]
self.assertEqual([item.pk for item in visible], [card.pk])
response = self.client.get(reverse('projects:board', args=[self.project.pk]), {'priority': 'high'})
self.assertNotContains(response, 'Danger')
visible = [item for column in response.context['columns'] for item in column.visible_cards]
self.assertEqual(visible, [])
response = self.client.get(reverse('projects:card', args=[card.pk]))
self.assertNotContains(response, '<script>alert(1)</script>', html=False)
self.assertContains(response, '<h1>Safe</h1>', html=False)
def test_board_archive_filter_and_mobile_filter_sheet(self):
active = create_card(self.owner, self.project, title='Active card')
archived = create_card(self.owner, self.project, title='Archived card')
archived.archived = True
archived.save(update_fields=['archived'])
self.client.force_login(self.owner)
response = self.client.get(reverse('projects:board', args=[self.project.pk]))
visible = [card for column in response.context['columns'] for card in column.visible_cards]
self.assertEqual([card.pk for card in visible], [active.pk])
self.assertContains(response, 'role="dialog"')
self.assertContains(response, 'Show archived cards')
response = self.client.get(reverse('projects:board', args=[self.project.pk]), {'archived': '1'})
visible = [card for column in response.context['columns'] for card in column.visible_cards]
self.assertEqual([card.pk for card in visible], [archived.pk])
def test_board_progress_is_zero_safe_and_activity_is_human_readable(self):
self.client.force_login(self.owner)
response = self.client.get(reverse('projects:board', args=[self.project.pk]))
self.assertEqual(response.context['progress_percent'], 0)
self.assertContains(response, '0 / 0')
card = create_card(self.owner, self.project, title='Timeline card')
for index in range(5):
Activity.objects.create(project=self.project, card=card, actor=self.owner,
action='card.moved', detail={'sequence': index})
response = self.client.get(reverse('projects:board', args=[self.project.pk]))
self.assertEqual(len(response.context['recent_activity']), 3)
self.assertGreater(len(response.context['older_activity']), 0)
self.assertContains(response, 'moved a card')
self.assertContains(response, 'View all')
def test_card_detail_uses_responsive_layout_and_readable_history(self):
card = create_card(self.owner, self.project, title='Detail view card', markdown='# Description\n\nCard detail text.')
self.client.force_login(self.owner)
response = self.client.get(reverse('projects:card', args=[card.pk]))
self.assertEqual(response.status_code, 200)
self.assertContains(response, 'projects/card_detail.css')
self.assertContains(response, 'Description')
self.assertContains(response, 'Card info')
self.assertContains(response, 'Progress notes')
self.assertContains(response, 'View raw Markdown')
self.assertContains(response, 'created this card')
self.assertContains(response, 'Edit card')
self.assertContains(response, 'Add a progress note')
def test_card_detail_preserves_viewer_read_only_permissions(self):
card = create_card(self.owner, self.project, title='Viewer detail card', markdown='Readable for the team.')
Membership.objects.create(project=self.project, user=self.other, role='viewer')
self.client.force_login(self.other)
response = self.client.get(reverse('projects:card', args=[card.pk]))
self.assertContains(response, 'Readable for the team.')
self.assertContains(response, 'Card info')
self.assertNotContains(response, 'Edit card')
self.assertNotContains(response, 'Add a progress note')
self.assertNotContains(response, 'Add card files')
def test_projects_index_preserves_search_access_and_archived_view(self):
finished = create_card(self.owner, self.project, title='Searchable milestone')
move_card(self.owner, finished, self.project.board.columns.get(is_done=True))
archived_card = create_card(self.owner, self.project, title='Old milestone')
archived_card.archived = True
archived_card.save(update_fields=['archived'])
private_project = create_project(self.other, name='Private workspace')
self.client.force_login(self.owner)
url = reverse('projects:list')
response = self.client.get(url)
self.assertContains(response, 'projects/project_list.css')
self.assertContains(response, 'BoomCast')
self.assertNotContains(response, 'Private workspace')
project = next(item for item in response.context['projects'] if item.pk == self.project.pk)
self.assertEqual(project.card_count, 2)
self.assertEqual(project.active_card_count, 1)
self.assertEqual(project.done_card_count, 1)
self.assertEqual(project.progress_percent, 100)
response = self.client.get(url, {'q': 'Searchable'})
self.assertContains(response, 'BoomCast')
self.assertContains(response, 'Open board')
response = self.client.get(url, {'q': 'Searchable'}, HTTP_HX_REQUEST='true')
self.assertContains(response, 'BoomCast')
self.assertEqual(response.context['query'], 'Searchable')
self.project.archived = True
self.project.save(update_fields=['archived'])
response = self.client.get(url, {'archived': '1'})
self.assertContains(response, 'Archived')
self.assertContains(response, 'BoomCast')
self.assertNotContains(response, 'Private workspace')
def test_completion_flag_updates_existing_cards(self):
card = create_card(self.owner, self.project, title='Complete later')
column = card.column
+1
View File
@@ -27,6 +27,7 @@ urlpatterns = [
path('cards/<uuid:card_id>/', views.card_detail, name='card'),
path('cards/<uuid:card_id>/edit/', views.card_edit, name='card_edit'),
path('cards/<uuid:card_id>/move/', views.card_move, name='card_move'),
path('cards/<uuid:card_id>/move-project/', views.card_move_project, name='card_move_project'),
path('cards/<uuid:card_id>/comment/', views.card_comment, name='card_comment'),
path('cards/<uuid:card_id>/attachments/', views.attachment_upload, name='attachment_upload'),
path('attachments/<uuid:attachment_id>/download/', views.attachment_download, name='attachment_download'),
+73 -5
View File
@@ -1,5 +1,6 @@
from django.contrib.auth.decorators import login_required
from django.contrib.auth import get_user_model
from django.contrib import messages
from django.contrib.auth.views import LoginView
from django.core.cache import cache
from django.core import signing
@@ -20,7 +21,7 @@ from django.utils import timezone
from django.conf import settings
from oauth2_provider.models import get_access_token_model, revoke_access_token
from .forms import CardForm, ColumnForm, ProfileForm, ProjectForm, TagForm
from .models import Activity, Card, CardComment, CardAttachment, Column, Profile, Membership, Tag
from .models import Activity, Card, CardComment, CardAttachment, Column, Profile, Membership, Tag, Project
from . import services
from . import attachments
from . import documentation
@@ -30,6 +31,21 @@ from .models import DocumentationSync, ProjectDocument
from urllib.parse import quote
ACTIVITY_ACTION_LABELS = {
'project.created': 'created the project', 'card.created': 'created a card',
'card.updated': 'updated a card', 'card.moved': 'moved a card',
'card.moved_project': 'moved this card to another project',
'card.moved_project_out': 'moved a card to another project',
'card.assigned': 'changed a card assignment', 'card.tags_changed': 'updated card tags',
'card.bulk_updated': 'updated a card', 'column.updated': 'updated a column',
'attachment.added': 'added an attachment', 'attachment.deleted': 'removed an attachment',
}
def activity_display_action(action):
return ACTIVITY_ACTION_LABELS.get(action, action.replace('.', ' ').replace('_', ' '))
class ThrottledLoginView(LoginView):
template_name = 'projects/login.html'
@@ -62,8 +78,14 @@ def project_list(request):
projects = services.accessible(request.user).filter(archived=show_archived)
if query:
projects = projects.filter(Q(name__icontains=query) | Q(description__icontains=query) | Q(cards__title__icontains=query) | Q(cards__description_markdown__icontains=query) | Q(tag__name__icontains=query)).distinct()
projects = projects.annotate(card_count=Count('cards', distinct=True)).order_by('name')
projects = projects.annotate(
card_count=Count('cards', distinct=True),
active_card_count=Count('cards', filter=Q(cards__archived=False), distinct=True),
done_card_count=Count('cards', filter=Q(cards__archived=False, cards__column__is_done=True), distinct=True),
).order_by('name')
page_obj = Paginator(projects, 12).get_page(request.GET.get('page'))
for project in page_obj:
project.progress_percent = round(project.done_card_count * 100 / project.active_card_count) if project.active_card_count else 0
filters = request.GET.copy(); filters.pop('page', None)
template = 'projects/_project_list.html' if request.headers.get('HX-Request') else 'projects/list.html'
return render(request, template, {'projects': page_obj, 'page_obj': page_obj, 'filters_query': filters.urlencode(), 'query': query, 'show_archived': show_archived, 'section': 'projects', 'title': 'Projects'})
@@ -133,8 +155,14 @@ def board(request, project_id):
column.active_count = Card.objects.filter(column=column, archived=False).count()
assignable_ids = [project.owner_id, *project.memberships.values_list('user_id', flat=True)]
active_cards = Card.objects.filter(project=project, archived=False)
context = {'project': project, 'columns': columns, 'page_obj': page_obj, 'filters_query': filters.urlencode(), 'query': query, 'title': project.name, 'section': 'projects', 'card_count': len(cards), 'total_count': active_cards.count(), 'done_count': active_cards.filter(column__is_done=True).count(), 'priority_counts': [(label, active_cards.filter(priority=value, column__is_done=False).count()) for value, label in Card.PRIORITY], 'recent_activity': Activity.objects.filter(project=project).select_related('actor')[:5], 'selected_priority': request.GET.get('priority', ''), 'selected_type': request.GET.get('card_type', ''), 'selected_assignee': request.GET.get('assignee', ''), 'selected_tag': request.GET.get('tag', ''), 'selected_column': request.GET.get('column', ''), 'show_archived': show_archived, 'tags': Tag.objects.filter(project=project).order_by('name'), 'assignable': get_user_model().objects.filter(pk__in=assignable_ids).order_by('username'), 'card_types': Card.TYPE, 'can_edit': can_edit}
template = 'projects/_board.html' if request.headers.get('HX-Request') else 'projects/board.html'
is_htmx = bool(request.headers.get('HX-Request'))
all_activity = [] if is_htmx else list(Activity.objects.filter(project=project).select_related('actor', 'card'))
for event in all_activity:
event.display_action = activity_display_action(event.action)
done_count = active_cards.filter(column__is_done=True).count()
total_count = active_cards.count()
context = {'project': project, 'columns': columns, 'page_obj': page_obj, 'filters_query': filters.urlencode(), 'query': query, 'title': project.name, 'section': 'projects', 'card_count': len(cards), 'total_count': total_count, 'done_count': done_count, 'progress_percent': round(done_count * 100 / total_count) if total_count else 0, 'priority_counts': [(label, active_cards.filter(priority=value, column__is_done=False).count()) for value, label in Card.PRIORITY], 'recent_activity': all_activity[:3], 'older_activity': all_activity[3:], 'selected_priority': request.GET.get('priority', ''), 'selected_type': request.GET.get('card_type', ''), 'selected_assignee': request.GET.get('assignee', ''), 'selected_tag': request.GET.get('tag', ''), 'selected_column': request.GET.get('column', ''), 'show_archived': show_archived, 'active_filter_count': sum(bool(request.GET.get(key)) for key in ('priority', 'card_type', 'column', 'assignee', 'tag')), 'tags': Tag.objects.filter(project=project).order_by('name'), 'assignable': get_user_model().objects.filter(pk__in=assignable_ids).order_by('username'), 'card_types': Card.TYPE, 'can_edit': can_edit}
template = 'projects/_board.html' if is_htmx else 'projects/board.html'
return render(request, template, context)
@@ -204,11 +232,51 @@ def card_create(request, project_id):
def card_detail(request, card_id):
card = services.card_for(request.user, card_id)
can_edit = card.project.owner_id == request.user.pk or Membership.objects.filter(project=card.project, user=request.user, role='editor').exists()
return render(request, 'projects/card.html', {'card': card, 'can_edit': can_edit, 'title': card.title, 'section': 'projects',
history = card.activity.select_related('actor').all()
for event in history:
event.display_action = activity_display_action(event.action).replace('a card', 'this card')
destinations = Project.objects.filter(archived=False).filter(Q(owner=request.user) | Q(memberships__user=request.user, memberships__role='editor')).exclude(pk=card.project_id).distinct().select_related('board').order_by('name') if can_edit else Project.objects.none()
destination_options = []
for project in destinations:
columns = list(project.board.columns.filter(archived=False).order_by('position'))
if not columns:
continue
default_column = next((column for column in columns if column.is_default), columns[0])
destination_options.append({'project': project, 'columns': columns,
'default_column': default_column})
return render(request, 'projects/card.html', {'card': card, 'can_edit': can_edit, 'title': card.title, 'section': 'projects', 'history': history,
'destination_options': destination_options, 'move_idempotency_key': uuid.uuid4(),
'card_files': card.attachments.filter(comment__isnull=True).select_related('uploaded_by'),
'comments': card.comments.prefetch_related('attachments').select_related('author').order_by('created_at')})
@login_required
@require_POST
def card_move_project(request, card_id):
card = services.card_for(request.user, card_id, write=True)
try:
target_id = uuid.UUID(request.POST.get('target_project_id', ''))
target_project = services.project_for(request.user, target_id, write=True)
column_id = request.POST.get('target_column_id') or None
target_column = get_object_or_404(Column, pk=column_id) if column_id else None
moved, result = services.move_card_to_project(
request.user, card, target_project, target_column=target_column,
expected_revision=request.POST.get('expected_revision'),
idempotency_key=request.POST.get('idempotency_key') or None,
)
except services.RevisionConflict as conflict:
messages.error(request, f'This card changed before it could be moved. Current revision: {conflict.current}. Reload the card and try again.')
return redirect('projects:card', card_id=card.pk)
except (ValueError, TypeError, ValidationError) as exc:
messages.error(request, '; '.join(exc.messages) if isinstance(exc, ValidationError) else 'The card could not be moved. Reload the card and try again.')
return redirect('projects:card', card_id=card.pk)
message = f'Moved “{moved.title}” from {result["source_project_name"]} to {result["target_project_name"]}.'
if result['warnings']:
message += ' ' + ' '.join(result['warnings'])
messages.success(request, message)
return redirect('projects:card', card_id=moved.pk)
@login_required
@require_POST
def attachment_upload(request, card_id):