From 03d7afc6a19efeb1426a5b64a76be2d3bd05b500 Mon Sep 17 00:00:00 2001 From: Joren de Graaf Date: Tue, 20 Oct 2026 14:17:46 +0200 Subject: [PATCH] latest changes --- .gitignore | 1 + README.md | 4 +- config/settings.py | 5 + .../static/dashboard/companion-dashboard.js | 76 +++ dashboard/static/dashboard/companion.css | 11 + dashboard/static/dashboard/companion.js | 578 ++++++++++++++++++ dashboard/templates/dashboard/index.html | 6 +- dashboard/tests/companion_movement.html | 305 +++++++++ docs/card-attachments.md | 23 + docs/companion-movement.md | 17 + .../project-documentation-wiki-evaluation.md | 81 +++ mcp_server/server.py | 81 ++- projects/apps.py | 10 + projects/attachments.py | 102 ++++ projects/migrations/0004_bulkupdatekey.py | 30 + projects/migrations/0005_cardattachment.py | 41 ++ projects/models.py | 38 ++ projects/services.py | 104 +++- projects/static/projects/attachments.js | 44 ++ .../templates/projects/_attachment_list.html | 8 + projects/templates/projects/_board.html | 1 + projects/templates/projects/board.html | 11 + projects/templates/projects/bulk_edit.html | 26 + projects/templates/projects/card.html | 10 +- projects/test_attachments.py | 112 ++++ projects/tests.py | 75 ++- projects/urls.py | 6 + projects/views.py | 138 ++++- 28 files changed, 1929 insertions(+), 15 deletions(-) create mode 100644 dashboard/static/dashboard/companion-dashboard.js create mode 100644 dashboard/static/dashboard/companion.css create mode 100644 dashboard/static/dashboard/companion.js create mode 100644 dashboard/tests/companion_movement.html create mode 100644 docs/card-attachments.md create mode 100644 docs/companion-movement.md create mode 100644 docs/research/project-documentation-wiki-evaluation.md create mode 100644 projects/attachments.py create mode 100644 projects/migrations/0004_bulkupdatekey.py create mode 100644 projects/migrations/0005_cardattachment.py create mode 100644 projects/static/projects/attachments.js create mode 100644 projects/templates/projects/_attachment_list.html create mode 100644 projects/templates/projects/bulk_edit.html create mode 100644 projects/test_attachments.py diff --git a/.gitignore b/.gitignore index 03d9a38..6999883 100644 --- a/.gitignore +++ b/.gitignore @@ -5,5 +5,6 @@ dist/ *.pyc __pycache__/ db.sqlite3 +private_media/ .DS_Store .playwright-mcp/ diff --git a/README.md b/README.md index 5e1879b..269bed7 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,8 @@ systemctl --user restart common-ground-django.service common-ground-mcp.service journalctl --user -u common-ground-mcp.service -f ``` +If running these commands from the Codex Flatpak shell, prefix them with `flatpak-spawn --host` so they reach the host's systemd user manager. For example: `flatpak-spawn --host systemctl --user restart common-ground-mcp.service`. + The Django process on port 8765 provides a local dashboard and OAuth server. The public Caddy configuration currently forwards the dashboard and OAuth routes to a separate Django process at `100.91.62.59:2345`, and MCP routes to `100.91.62.59:8766`. An unauthenticated `GET /mcp` should return HTTP 401. Optional settings for the user services belong in `~/.config/common-ground/env`, outside the repository. After changing that file, restart the affected service. Remote clients use the public HTTPS reverse proxy. Route `/mcp` and `/.well-known/oauth-protected-resource/mcp` to the Tailscale-only MCP listener on port 8766, and the dashboard plus OAuth discovery and `/o/` to the Django process on port 2345. The processes must share the same database and `DJANGO_SECRET_KEY`. Keep MCP off public and LAN interfaces; the Tailscale address is reachable through the authenticated tailnet. @@ -36,7 +38,7 @@ For `https://projects.jorendegraaf.eu`, MCP advertises `MCP_PUBLIC_URL=https://p ## OAuth and MCP -The Django server hosts OAuth authorization, token, revocation, and discovery endpoints under `/o/` and `/.well-known/oauth-authorization-server`. The MCP process hosts `/mcp` and `/.well-known/oauth-protected-resource/mcp`. The server registers 51 tools; reads require `projects:read`, and writes require `projects:write`. OAuth authorization codes require PKCE. Tokens expire after one hour, can be revoked from Profile, and are stored hashed by django-oauth-toolkit. +The Django server hosts OAuth authorization, token, revocation, and discovery endpoints under `/o/` and `/.well-known/oauth-authorization-server`. The MCP process hosts `/mcp` and `/.well-known/oauth-protected-resource/mcp`. Reads require `projects:read`, and writes require `projects:write`. OAuth authorization codes require PKCE. Tokens expire after one hour, can be revoked from Profile, and are stored hashed by django-oauth-toolkit. After deploying new MCP tools, restart the MCP service and refresh its ChatGPT plugin connection so the updated tool list appears. Authenticated dynamic client registration is enabled at `/o/register/`. A signed-in user can register a client; session requests also need a CSRF token. Anonymous registration is denied. You can also create a public authorization-code client in Django admin, setting its exact HTTPS redirect URI and the needed scopes. Profile shows active grants and revocation controls. diff --git a/config/settings.py b/config/settings.py index 9daf68f..b408395 100644 --- a/config/settings.py +++ b/config/settings.py @@ -43,6 +43,11 @@ STATIC_URL = "static/" TIME_ZONE = 'Europe/Amsterdam' USE_TZ = True STATICFILES_DIRS = [BASE_DIR / "dist"] if (BASE_DIR / "dist").exists() else [] +MEDIA_ROOT = Path(os.environ.get('PROJECTS_PRIVATE_MEDIA_ROOT', BASE_DIR / 'private_media')) +# Deliberately no MEDIA_URL or web-server alias: attachments are served only by authorized views. +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)) DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField" DATABASES = {'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': BASE_DIR / 'db.sqlite3'}} CACHES = { diff --git a/dashboard/static/dashboard/companion-dashboard.js b/dashboard/static/dashboard/companion-dashboard.js new file mode 100644 index 0000000..ad42310 --- /dev/null +++ b/dashboard/static/dashboard/companion-dashboard.js @@ -0,0 +1,76 @@ +(() => { + const grid = document.querySelector('#widget-grid'); + const toggle = document.querySelector('#companion-toggle'); + if (!grid || !toggle || !window.BrowserCompanion) return; + const motion = matchMedia('(prefers-reduced-motion: reduce)'); + const dark = matchMedia('(prefers-color-scheme: dark)'); + const name = () => { + const theme = document.documentElement.dataset.theme; + return theme === 'dark' || (theme !== 'light' && dark.matches) ? 'Dahlia' : 'Pixel'; + }; + let companion = null; + let refreshFrame = 0; + let refreshTimer = 0; + let lastRefresh = 0; + const refresh = () => { + if (refreshTimer || refreshFrame) return; + refreshTimer = setTimeout(() => { + refreshTimer = 0; + refreshFrame = requestAnimationFrame(() => { + refreshFrame = 0; + lastRefresh = performance.now(); + companion?.refresh(); + }); + }, Math.max(0, 50 - (performance.now() - lastRefresh))); + }; + const setVisible = visible => { + if (visible && !companion) companion = new window.BrowserCompanion({ + root: document.body, + surfaces: () => [...grid.querySelectorAll('[data-widget-platform="bottom"]')].flatMap(card => { + const body = card.querySelector('.widget-body'); + const firstLevel = body ? [...body.children] : []; + const candidates = [card.querySelector('.widget-card-head'), ...firstLevel]; + // Structural sections can contain the actual bordered ledges one level down. + for (const child of firstLevel) { + if (child.tagName === 'SECTION' || child.classList.contains('rain-layout')) + candidates.push(...child.children); + } + // The radar's visible frame is nested in layout wrappers and is a useful ledge. + const radarFrames = body ? [...body.querySelectorAll('.rain-radar-frame')] : []; + candidates.push(...radarFrames); + const cardRect = card.getBoundingClientRect(); + const tops = [...new Set(candidates)].filter(element => { + if (!element || element.matches('button, input, select, textarea, a, [role="button"]')) return false; + const rect = element.getBoundingClientRect(); + return rect.width >= 18 && rect.height >= 12 && rect.top > cardRect.top + 12 && rect.top < cardRect.bottom - 12; + }).map(element => ({ element, edge: 'top', card })); + return [{ element: card, edge: 'bottom', card, explicit: true }, ...tops, + ...radarFrames.map(element => ({ element, edge: 'bottom', card })), + { element: card, edge: 'top', card, explicit: true }]; + }), + reducedMotion: () => motion.matches, + name, + debug: new URLSearchParams(location.search).has('companionDebug'), + debugSpeed: new URLSearchParams(location.search).has('companionFast') ? 10 : 1, + }); + if (!visible && companion) { companion.destroy(); companion = null; } + toggle.setAttribute('aria-pressed', String(visible)); + toggle.textContent = visible ? 'Hide companion' : 'Show companion'; + try { localStorage.setItem('dashboard-companion-visible', String(visible)); } catch (_) { /* Optional preference. */ } + }; + toggle.addEventListener('click', () => setVisible(!companion)); + const observer = new MutationObserver(refresh); + observer.observe(grid, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-span', 'class', 'style', 'hidden'] }); + const resize = new ResizeObserver(refresh); + resize.observe(grid); + window.addEventListener('resize', refresh, { passive: true }); + window.addEventListener('scroll', refresh, { passive: true }); + motion.addEventListener('change', () => companion?.setReducedMotion(motion.matches)); + dark.addEventListener('change', () => { companion?.setName(name()); refresh(); }); + new MutationObserver(() => { companion?.setName(name()); refresh(); }).observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme', 'class', 'style'] }); + document.addEventListener('htmx:afterSwap', refresh); + document.addEventListener('dashboard:widget-mounted', refresh); + document.addEventListener('dashboard:widget-unmounted', refresh); + try { setVisible(localStorage.getItem('dashboard-companion-visible') !== 'false'); } + catch (_) { setVisible(true); } +})(); diff --git a/dashboard/static/dashboard/companion.css b/dashboard/static/dashboard/companion.css new file mode 100644 index 0000000..6bb175f --- /dev/null +++ b/dashboard/static/dashboard/companion.css @@ -0,0 +1,11 @@ +.companion-box{position:fixed;top:0;left:0;z-index:40;width:18px;height:18px;margin:-18px 0 0 -9px;border:3px solid #155e75;border-radius:3px;background:#ecfeff;pointer-events:none;will-change:transform} +.companion-box[hidden]{display:none} +.companion-box span{position:absolute;left:50%;bottom:22px;transform:translateX(-50%);white-space:nowrap;padding:2px 6px;border:1px solid var(--border);border-radius:5px;background:var(--surface);color:var(--text);font-size:10px;font-weight:700;box-shadow:var(--shadow)} +.companion-box[data-state="walking"]{border-color:#166534}.companion-box[data-state="jumping"]{border-color:#7c3aed}.companion-box[data-state="purring"]{border-color:#be185d}.companion-box[data-state="batting"]{border-color:#b45309}.companion-box[data-state="sleeping"]{border-color:#475569} +.companion-box[data-state="climbing"]{border-color:#0f766e}.companion-box[data-state="pulling-up"]{border-color:#a21caf}.companion-box[data-state="climb-hopping"]{border-color:#a16207}.companion-box[data-state="landing"]{border-color:#1d4ed8} +.companion-debug{position:fixed;inset:0;pointer-events:none;z-index:39}.companion-debug i{position:absolute;display:block}.companion-debug-surface{border-top:2px solid #1d4ed8}.companion-debug-edge{border-left:2px dashed #a21caf}.companion-debug span{position:fixed;right:8px;bottom:8px;max-width:min(90vw,460px);padding:5px 8px;background:var(--surface);color:var(--text);border:1px solid var(--border);font:11px/1.4 monospace} +.companion-debug-route{height:0;border-top:1px dashed #047857;transform-origin:0 0}.companion-debug-rejected{width:6px;height:6px;border:1px solid #b91c1c;border-radius:50%} +@media(prefers-color-scheme:dark){.companion-box{background:#172c32;border-color:#67e8f9}.companion-box[data-state="walking"]{border-color:#86efac}.companion-box[data-state="jumping"]{border-color:#c4b5fd}.companion-box[data-state="purring"]{border-color:#f9a8d4}.companion-box[data-state="batting"]{border-color:#fcd34d}.companion-box[data-state="sleeping"]{border-color:#cbd5e1}} +[data-theme="dark"] .companion-box{background:#172c32;border-color:#67e8f9}[data-theme="dark"] .companion-box[data-state="walking"]{border-color:#86efac}[data-theme="dark"] .companion-box[data-state="jumping"]{border-color:#c4b5fd}[data-theme="dark"] .companion-box[data-state="purring"]{border-color:#f9a8d4}[data-theme="dark"] .companion-box[data-state="batting"]{border-color:#fcd34d}[data-theme="dark"] .companion-box[data-state="sleeping"]{border-color:#cbd5e1} +[data-theme="light"] .companion-box{background:#ecfeff;border-color:#155e75}[data-theme="light"] .companion-box[data-state="walking"]{border-color:#166534}[data-theme="light"] .companion-box[data-state="jumping"]{border-color:#7c3aed}[data-theme="light"] .companion-box[data-state="purring"]{border-color:#be185d}[data-theme="light"] .companion-box[data-state="batting"]{border-color:#b45309}[data-theme="light"] .companion-box[data-state="sleeping"]{border-color:#475569} +@media(prefers-reduced-motion:reduce){.companion-box{will-change:auto}} diff --git a/dashboard/static/dashboard/companion.js b/dashboard/static/dashboard/companion.js new file mode 100644 index 0000000..dea405d --- /dev/null +++ b/dashboard/static/dashboard/companion.js @@ -0,0 +1,578 @@ +/* Portable companion movement. The host supplies visible surfaces and preferences. */ +(() => { + 'use strict'; + const STATES = ['idle', 'walking', 'jumping', 'landing', 'climbing', 'pulling-up', 'climb-hopping', 'purring', 'batting', 'sleeping']; + const DEFAULTS = Object.freeze({ bodySize: 18, maxJumpHorizontalS: 3, maxJumpRiseS: 1.5, + maxJumpDropS: 2, preferredJumpHorizontalS: 1.8, maxStepUpS: .3, minClimbHeightS: 1, + climbSpeedSPerSec: 1.2, walkSpeedSPerSec: 2, jumpDurationMinMs: 350, + jumpDurationMaxMs: 650, pullUpDurationMinMs: 400, pullUpDurationMaxMs: 700, + buttWiggleChance: .25, climbHopChance: .15, climbHopMaxDistanceS: .8, + minLandingWidthS: .8, edgeClearanceS: .15, centerRightPreference: .7, + maxRouteTransitions: 16, stuckTimeoutMs: 4000, + idleMinMs: 12000, idleMaxMs: 20000, sleepMinMs: 20000, sleepMaxMs: 45000, + emoteMinMs: 2200, emoteMaxMs: 3800, emoteCooldownMs: 16000, + sleepCooldownMs: 90000, activeMinTransitions: 2, activeMaxTransitions: 5, + activeMovePauseMs: 450, activeChance: .65, sleepChance: .12, emoteChance: .32 }); + const LIMITS = { bodySize: [8, 80], maxJumpHorizontalS: [.5, 6], maxJumpRiseS: [.2, 3], + maxJumpDropS: [.2, 4], preferredJumpHorizontalS: [.3, 4], maxStepUpS: [0, 1], + minClimbHeightS: [.3, 4], climbSpeedSPerSec: [.2, 5], walkSpeedSPerSec: [.2, 6], + jumpDurationMinMs: [150, 1500], jumpDurationMaxMs: [200, 2000], + pullUpDurationMinMs: [150, 1500], pullUpDurationMaxMs: [200, 2000], + buttWiggleChance: [0, 1], climbHopChance: [0, 1], climbHopMaxDistanceS: [.1, 2], + minLandingWidthS: [.5, 3], edgeClearanceS: [0, .8], centerRightPreference: [0, 1], + maxRouteTransitions: [2, 40], stuckTimeoutMs: [500, 15000], + idleMinMs: [10000, 120000], idleMaxMs: [10000, 180000], + sleepMinMs: [10000, 180000], sleepMaxMs: [10000, 300000], + emoteMinMs: [800, 15000], emoteMaxMs: [800, 20000], + emoteCooldownMs: [1000, 120000], sleepCooldownMs: [10000, 600000], + activeMinTransitions: [1, 12], activeMaxTransitions: [1, 20], + activeMovePauseMs: [100, 3000], activeChance: [0, 1], + sleepChance: [0, 1], emoteChance: [0, 1] }; + const clamp = (v, a, b) => Math.max(a, Math.min(b, v)); + function configure(overrides = {}) { + if (!overrides || typeof overrides !== 'object') overrides = {}; + const result = {}; + for (const [key, value] of Object.entries(DEFAULTS)) { + const proposed = overrides[key]; + result[key] = typeof proposed === 'number' && Number.isFinite(proposed) + ? clamp(proposed, ...LIMITS[key]) : value; + } + result.preferredJumpHorizontalS = Math.min(result.preferredJumpHorizontalS, result.maxJumpHorizontalS); + result.jumpDurationMaxMs = Math.max(result.jumpDurationMinMs, result.jumpDurationMaxMs); + result.pullUpDurationMaxMs = Math.max(result.pullUpDurationMinMs, result.pullUpDurationMaxMs); + result.idleMaxMs = Math.max(result.idleMinMs, result.idleMaxMs); + result.sleepMaxMs = Math.max(result.sleepMinMs, result.sleepMaxMs); + result.emoteMaxMs = Math.max(result.emoteMinMs, result.emoteMaxMs); + result.activeMaxTransitions = Math.max(result.activeMinTransitions, result.activeMaxTransitions); + return result; + } + const gap = (a, b) => Math.max(0, b.left - a.right, a.left - b.right); + const landingX = (surface, fromX, config) => clamp(fromX, surface.left + config.bodySize / 2 + config.edgeClearanceS * config.bodySize, + surface.right - config.bodySize / 2 - config.edgeClearanceS * config.bodySize); + function jumpAnchors(source, target, rise, config) { + const size = config.bodySize, clearance = size * config.edgeClearanceS; + let fromX = landingX(source, (target.left + target.right) / 2, config); + if (rise > config.maxStepUpS * size) { + const outside = [target.left - size / 2 - clearance, target.right + size / 2 + clearance] + .map(x => landingX(source, x, config)) + .filter(x => x + size / 2 + clearance <= target.left || x - size / 2 - clearance >= target.right); + if (!outside.length) return null; + fromX = outside.sort((a, b) => Math.abs(a - target.left) - Math.abs(b - target.left))[0]; + } else if (rise < -config.maxStepUpS * size) { + const sides = [source.left + size / 2 + clearance, source.right - size / 2 - clearance]; + fromX = sides.sort((a, b) => Math.abs(landingX(target, a, config) - a) - + Math.abs(landingX(target, b, config) - b))[0]; + } + return { fromX, toX: landingX(target, fromX, config) }; + } + function targetArcClear(source, target, fromX, toX, rise, config) { + if (rise <= config.maxStepUpS * config.bodySize) return true; + const size = config.bodySize, arc = Math.max(size * .65, rise + size * .5); + for (let step = 1; step < 10; step++) { + const t = step / 10, x = fromX + (toX - fromX) * t; + const y = source.y + (target.y - source.y) * t - Math.sin(Math.PI * t) * arc; + if (x + size / 2 > target.rect.left && x - size / 2 < target.rect.right && + y > target.rect.top + .5 && y - size < target.rect.bottom) return false; + } + return true; + } + function visibleBorder(style, side) { + if (!style || ['none', 'hidden'].includes(style[`border${side}Style`]) || + parseFloat(style[`border${side}Width`]) < 1) return false; + const color = style[`border${side}Color`]?.trim().toLowerCase() || ''; + if (color === 'transparent') return false; + const alpha = color.match(/(?:rgba\([^)]*,\s*|rgb\([^)]*\/\s*|color\([^)]*\/\s*)([\d.]+%?)\s*\)$/)?.[1]; + return alpha === undefined || (alpha.endsWith('%') ? parseFloat(alpha) / 100 : Number(alpha)) > .05; + } + function visibleRect(element, root) { + if (!element?.isConnected) return null; + const rect = element.getBoundingClientRect(); + if (rect.width < 1 || rect.height < 1) return null; + let left = rect.left, right = rect.right, top = rect.top, bottom = rect.bottom, opacity = 1; + for (let node = element; node && node !== root?.parentElement; node = node.parentElement) { + const style = getComputedStyle(node); + opacity *= Number(style.opacity); + if (style.display === 'none' || style.visibility !== 'visible' || opacity <= .05) return null; + if (node !== element && ['hidden', 'clip', 'scroll', 'auto'].includes(style.overflowX)) { + const clip = node.getBoundingClientRect(); left = Math.max(left, clip.left); right = Math.min(right, clip.right); + } + if (node !== element && ['hidden', 'clip', 'scroll', 'auto'].includes(style.overflowY)) { + const clip = node.getBoundingClientRect(); top = Math.max(top, clip.top); bottom = Math.min(bottom, clip.bottom); + } + } + return right > left && bottom > top ? { left, right, top, bottom, width: right - left, height: bottom - top } : null; + } + function discover(entries, root, config) { + const surfaces = [], edges = [], rejected = []; + for (const [index, raw] of entries.slice(0, 160).entries()) { + const entry = raw.element ? raw : { element: raw }; + const element = entry.element, rect = visibleRect(element, root); + if (!rect) { rejected.push({ element, reason: 'hidden or clipped' }); continue; } + const explicit = entry.explicit === true; + if (!explicit && element.matches?.('button, input, select, textarea, a, [contenteditable], [role="button"]')) { + rejected.push({ element, reason: 'interactive control' }); continue; + } + const style = getComputedStyle(element); + const edge = entry.edge === 'bottom' ? 'bottom' : 'top'; + const native = element.getBoundingClientRect(); + if ((edge === 'top' && rect.top > native.top + .5) || + (edge === 'bottom' && rect.bottom < native.bottom - .5)) { + rejected.push({ element, reason: 'edge clipped' }); continue; + } + if (!explicit && !visibleBorder(style, edge === 'top' ? 'Top' : 'Bottom')) { + rejected.push({ element, reason: 'borderless' }); continue; + } + const card = entry.card || element; + const cardRect = visibleRect(card, root); + if (!cardRect) continue; + const inset = config.edgeClearanceS * config.bodySize; + const left = Math.max(rect.left, cardRect.left + inset); + const right = Math.min(rect.right, cardRect.right - inset); + const y = edge === 'top' ? rect.top : rect.bottom; + if (right - left < config.bodySize * Math.max(1, config.minLandingWidthS) + 2 * inset || + y < rect.top - .5 || y > rect.bottom + .5) { + rejected.push({ element, reason: 'too narrow' }); continue; + } + const surface = { id: `${index}:${edge}`, element, card, edge, rect, left, right, y, + anchor: { left: rect.left, top: rect.top }, explicit }; + surfaces.push(surface); + if (edge === 'top') { + for (const side of ['Left', 'Right']) { + if (!explicit && !visibleBorder(style, side)) continue; + const x = side === 'Left' ? rect.left : rect.right; + const height = rect.bottom - rect.top; + if (height < config.bodySize * config.minClimbHeightS || height > innerHeight * 4) continue; + edges.push({ id: `${surface.id}:${side}`, element, card, side: side.toLowerCase(), x, + top: rect.top, bottom: rect.bottom, platform: surface.id }); + } + } + } + return { surfaces, edges, rejected }; + } + function pathClear(a, b, surfaces, config, kind) { + const size = config.bodySize, margin = config.edgeClearanceS * size; + const left = Math.min(a.x, b.x) - size / 2 - margin; + const right = Math.max(a.x, b.x) + size / 2 + margin; + const top = Math.min(a.y, b.y) - size - (kind === 'jump' ? size * .55 : 0); + const bottom = Math.max(a.y, b.y) - margin; + return !surfaces.some(surface => { + if (surface.id === a.id || surface.id === b.id || surface.card === a.card && surface.element === a.element) return false; + const rect = surface.rect; + if (kind === 'drop' && rect.bottom <= a.y) return false; + if (rect.right <= left || rect.left >= right || rect.bottom <= top || rect.top >= bottom) return false; + // A parent card contains the route; its border is not an obstacle inside it. + if (rect.left <= left && rect.right >= right && rect.top <= top && rect.bottom >= bottom) return false; + return true; + }); + } + function graphFor(surfaces, edges, config) { + const graph = new Map(surfaces.map(s => [s.id, []])); + const size = config.bodySize; + for (const source of surfaces) for (const target of surfaces) { + if (source === target) continue; + const rise = source.y - target.y, horizontal = gap(source, target); + const anchors = jumpAnchors(source, target, rise, config); + if (!anchors) continue; + const sourceX = anchors.fromX, targetX = anchors.toX; + const distance = Math.abs(targetX - sourceX); + const departure = { ...source, x: sourceX }, arrival = { ...target, x: targetX }; + if (Math.abs(rise) <= config.maxStepUpS * size && horizontal <= size * .4 && + pathClear(departure, arrival, surfaces, config, 'walk')) { + graph.get(source.id).push({ to: target.id, kind: 'walk', fromX: sourceX, toX: targetX, cost: 1 + distance / size }); + continue; + } + if (rise > config.maxJumpRiseS * size || -rise > config.maxJumpDropS * size || + distance > config.maxJumpHorizontalS * size || horizontal > config.maxJumpHorizontalS * size) continue; + const kind = rise < -config.maxStepUpS * size ? 'drop' : 'jump'; + if (!pathClear(departure, arrival, surfaces, config, kind)) continue; + if (!targetArcClear(source, target, sourceX, targetX, rise, config)) continue; + graph.get(source.id).push({ to: target.id, kind, fromX: sourceX, toX: targetX, + cost: (kind === 'drop' ? 3 : 2) + distance / (size * config.preferredJumpHorizontalS) + Math.abs(rise) / size }); + } + for (const edge of edges) { + const target = surfaces.find(s => s.id === edge.platform); + if (!target) continue; + for (const source of surfaces) { + if (source.id === target.id || source.y < edge.bottom - size * .45 || + source.y > edge.bottom + size * config.maxJumpRiseS || + Math.abs(landingX(source, edge.x, config) - edge.x) > size * config.maxJumpHorizontalS) continue; + const fromX = landingX(source, edge.x, config); + if (!pathClear({ ...source, x: fromX }, { ...target, x: landingX(target, edge.x, config) }, + surfaces.filter(s => s.element !== target.element), config, 'climb')) continue; + graph.get(source.id).push({ to: target.id, kind: 'climb', edge, fromX, + toX: landingX(target, edge.x, config), attachRise: Math.max(0, source.y - edge.bottom), + cost: 2.5 + (edge.bottom - edge.top) / (size * config.climbSpeedSPerSec) + + Math.max(0, source.y - edge.bottom) / size }); + } + } + return graph; + } + function routes(graph, start, limit) { + const queue = [{ id: start, cost: 0, steps: [] }], best = new Map([[start, 0]]), found = []; + while (queue.length && found.length < 100) { + queue.sort((a, b) => a.cost - b.cost); + const route = queue.shift(); + if (route.cost > best.get(route.id)) continue; + if (route.steps.length) found.push(route); + if (route.steps.length >= limit) continue; + for (const transition of graph.get(route.id) || []) { + const cost = route.cost + transition.cost; + if (cost >= (best.get(transition.to) ?? Infinity)) continue; + best.set(transition.to, cost); + queue.push({ id: transition.to, cost, steps: [...route.steps, transition] }); + } + } + return found; + } + class DebugBoxRenderer { + constructor(root) { + this.element = document.createElement('div'); + this.element.className = 'companion-box'; + this.element.setAttribute('aria-hidden', 'true'); + this.label = document.createElement('span'); + this.element.append(this.label); root.append(this.element); + } + render(position, state, name) { + this.element.dataset.state = state; + this.element.style.transform = `translate3d(${Math.round(position.x)}px,${Math.round(position.y)}px,0)`; + this.label.textContent = `${name} · ${state}`; + } + destroy() { this.element.remove(); } + } + class Companion { + constructor(options) { + this.options = options; + this.root = options.root || document.body; + this.config = configure(options.config); + this.renderer = options.renderer || new DebugBoxRenderer(this.root); + this.reduced = !!options.reducedMotion?.(); + this.name = options.name?.() || 'Companion'; + this.position = { x: 0, y: 0 }; + this.state = 'idle'; this.stateReason = 'initial placement'; this.trace = []; + this.platform = null; this.route = []; this.motion = null; + this.mode = 'calm'; this.activeRemaining = 0; + this.lastSleepAt = performance.now(); this.lastEmoteAt = -Infinity; + this.burstsSinceRest = 0; this.burstsSinceEmote = 0; + this.debugSpeed = options.debugSpeed ? clamp(Number(options.debugSpeed) || 1, 1, 20) : 1; + this.deadline = performance.now() + this.dwell('idle'); + this.lastTime = 0; this.running = true; this.dirty = true; + this.refresh(); this.tick = this.tick.bind(this); this.frame = requestAnimationFrame(this.tick); + } + dwell(activity) { + const min = this.config[`${activity}MinMs`], max = this.config[`${activity}MaxMs`]; + return (min + Math.random() * (max - min)) / this.debugSpeed; + } + setState(state, reason, now = performance.now()) { + if (this.state === state) { this.stateReason = reason; return; } + this.state = state; this.stateReason = reason; + this.trace.push({ at: Math.round(now), state, reason }); + if (this.trace.length > 12) this.trace.shift(); + } + refresh() { + const previous = this.platform; + const seen = discover(this.options.surfaces(), this.root, this.config); + this.surfaces = seen.surfaces; this.edges = seen.edges; this.rejected = seen.rejected; + this.graph = graphFor(this.surfaces, this.edges, this.config); + this.dirty = true; + const same = this.surfaces.find(s => previous && s.element === previous.element && s.edge === previous.edge); + if (same) { + this.position.x += same.anchor.left - previous.anchor.left; + this.position.y += same.anchor.top - previous.anchor.top; + this.platform = same; + if (this.motion) { + this.motion.from.x += same.anchor.left - previous.anchor.left; + this.motion.from.y += same.anchor.top - previous.anchor.top; + const destination = this.surfaces.find(s => s.element === this.motion.destination.element && s.edge === this.motion.destination.edge); + if (destination) { + this.motion.to.x += destination.anchor.left - this.motion.destination.anchor.left; + this.motion.to.y += destination.anchor.top - this.motion.destination.anchor.top; + this.motion.destination = destination; + if (this.motion.step) { + const updated = (this.graph.get(same.id) || []).find(t => + t.to === destination.id && t.kind === this.motion.step.kind); + if (!updated) this.stopAtSafeAnchor(); + else this.motion.step = updated; + } + } else this.stopAtSafeAnchor(); + } else this.position.y = same.y; + } else if (previous) this.stopAtSafeAnchor(); + else if (this.surfaces.length && !this.hasStarted) { + this.platform = this.surfaces[0]; + this.position = { x: landingX(this.platform, this.platform.left + 30, this.config), y: this.platform.y }; + this.hasStarted = true; + } else if (this.surfaces.length) { + this.stopAtSafeAnchor(); + } + this.renderer.element.hidden = !this.platform; + this.renderer.render(this.position, this.state, this.name); + this.drawDebug(); + } + stopAtSafeAnchor() { + this.motion = null; this.route = []; this.setState('idle', 'recovering safe anchor'); + this.mode = 'calm'; this.activeRemaining = 0; + this.deadline = performance.now() + this.dwell('idle'); + const nearby = this.surfaces.filter(s => Math.abs(s.y - this.position.y) < this.config.bodySize && + this.position.x >= s.left && this.position.x <= s.right) + .sort((a, b) => Math.abs(a.y - this.position.y) - Math.abs(b.y - this.position.y))[0]; + this.platform = nearby || null; + if (nearby) this.position.y = nearby.y; + this.renderer.element.hidden = !nearby; + } + choose(now) { + if (!this.platform || this.reduced) return; + if (this.mode !== 'active') { + const reachable = routes(this.graph, this.platform.id, this.config.maxRouteTransitions).length > 0; + const restReady = now - this.lastSleepAt >= this.config.sleepCooldownMs / this.debugSpeed; + const emoteReady = now - this.lastEmoteAt >= this.config.emoteCooldownMs / this.debugSpeed; + const restChance = Math.min(1, this.config.sleepChance + this.burstsSinceRest * .2); + if (restReady && this.burstsSinceRest >= 4) { + this.beginSleep(now); return; + } else if (emoteReady && this.burstsSinceEmote >= 2) { + this.beginEmote(now, 'brief activity after exploration'); return; + } else if (restReady && this.burstsSinceRest >= 2 && Math.random() < restChance) { + this.beginSleep(now); return; + } else if (reachable && Math.random() < this.config.activeChance) { + this.mode = 'active'; + this.activeRemaining = Math.round(this.config.activeMinTransitions + Math.random() * + (this.config.activeMaxTransitions - this.config.activeMinTransitions)); + this.setState('idle', `active exploration planned (${this.activeRemaining} transitions)`, now); + } else if (emoteReady && Math.random() < this.config.emoteChance) { + this.beginEmote(now, 'brief grounded activity'); return; + } else { + this.setState('idle', 'quietly observing', now); + this.deadline = now + this.dwell('idle'); return; + } + } + if (this.activeRemaining <= 0) { this.endBurst(now, 'exploration complete'); return; } + const candidates = routes(this.graph, this.platform.id, this.config.maxRouteTransitions) + .filter(route => route.steps.length <= this.activeRemaining && this.surfaces.some(s => s.id === route.id)); + if (!candidates.length) { + if (this.platform.right - this.platform.left > this.config.bodySize * 2) { + const toX = landingX(this.platform, this.position.x + + (Math.random() < .3 ? -1 : 1) * this.config.bodySize * (1 + Math.random() * 3), this.config); + if (Math.abs(toX - this.position.x) < 2) { this.endBurst(now, 'no reachable route'); return; } + this.motion = { phase: 'patrol', destination: this.platform, from: { ...this.position }, + to: { x: toX, y: this.platform.y }, start: now, + duration: Math.abs(toX - this.position.x) / + (this.config.walkSpeedSPerSec * this.config.bodySize) * 1000 }; + this.setState('walking', 'patrolling current platform', now); return; + } + this.endBurst(now, 'no reachable route'); return; + } + const immediateJumps = candidates.filter(route => ['jump', 'drop'].includes(route.steps[0]?.kind)); + const pool = immediateJumps.length && Math.random() < .55 ? immediateJumps : candidates; + const weighted = pool.map(route => { + const target = this.surfaces.find(s => s.id === route.id); + const horizontal = (target.left + target.right) / 2 / Math.max(innerWidth, 1); + return { route, weight: (1 + this.config.centerRightPreference * horizontal) / + (1 + route.cost * .12) * (1 + Math.random() * .25) }; + }); + weighted.sort((a, b) => b.weight - a.weight); + this.route = weighted[Math.floor(Math.random() * Math.min(3, weighted.length))].route.steps.slice(); + this.beginNext(now); + } + beginSleep(now) { + this.mode = 'resting'; this.lastSleepAt = now; this.burstsSinceRest = 0; + this.setState('sleeping', 'rest after exploration', now); + this.deadline = now + this.dwell('sleep'); + } + beginEmote(now, reason) { + this.lastEmoteAt = now; this.burstsSinceEmote = 0; + this.setState(Math.random() < .5 ? 'purring' : 'batting', reason, now); + this.deadline = now + this.dwell('emote'); + } + endBurst(now, reason) { + this.mode = 'calm'; this.activeRemaining = 0; this.route = []; + this.burstsSinceRest += 1; this.burstsSinceEmote += 1; + this.setState('idle', reason, now); + this.deadline = now + this.dwell('idle'); + } + beginNext(now) { + const step = this.route.shift(); + if (!step) { this.setState('idle', 'route complete on platform', now); this.deadline = now + 400; return; } + const destination = this.surfaces.find(s => s.id === step.to); + if (!destination || !(this.graph.get(this.platform.id) || []).some(e => e.to === step.to && e.kind === step.kind)) { + this.route = []; this.setState('idle', 'route invalidated', now); this.deadline = now + 1000; return; + } + const fromX = landingX(this.platform, step.fromX, this.config); + if (Math.abs(this.position.x - fromX) > 2) { + this.motion = { phase: 'approach', step, destination, from: { ...this.position }, + to: { x: fromX, y: this.platform.y }, start: now, + duration: Math.abs(fromX - this.position.x) / (this.config.walkSpeedSPerSec * this.config.bodySize) * 1000 }; + this.setState('walking', 'approach departure point', now); return; + } + this.startTransition(step, destination, now); + } + startTransition(step, destination, now) { + const current = (this.graph.get(this.platform.id) || []).find(t => + t.to === destination.id && t.kind === step.kind); + if (!current) { this.motion = null; this.route = []; this.setState('idle', 'transition invalidated', now); this.deadline = now + 1000; return; } + step = current; + const size = this.config.bodySize; + const duration = step.kind === 'walk' ? Math.abs(step.toX - this.position.x) / + (this.config.walkSpeedSPerSec * size) * 1000 : + clamp(350 + (Math.abs(step.toX - this.position.x) + Math.abs(destination.y - this.position.y)) * 2, + this.config.jumpDurationMinMs, this.config.jumpDurationMaxMs); + this.motion = { phase: step.kind, step, destination, from: { ...this.position }, + to: { x: step.toX, y: destination.y }, start: now, duration: Math.max(duration, 1) }; + this.setState(step.kind === 'climb' ? 'climbing' : step.kind === 'walk' ? 'walking' : 'jumping', + `start ${step.kind}`, now); + if (step.kind === 'climb') { + this.motion.phase = 'attach'; + this.motion.to = { x: step.edge.x + (step.edge.side === 'left' ? -size / 2 : size / 2), + y: Math.min(this.position.y, step.edge.bottom) }; + this.motion.duration = Math.max(180, Math.hypot(this.motion.to.x - this.position.x, + this.motion.to.y - this.position.y) / (this.config.walkSpeedSPerSec * size) * 1000); + if (step.attachRise > this.config.maxStepUpS * size) + this.setState('climb-hopping', 'short hop to visible climb edge', now); + } + } + advance(now) { + const m = this.motion; if (!m) return; + const t = clamp((now - m.start) / m.duration, 0, 1); + this.position.x = m.from.x + (m.to.x - m.from.x) * t; + this.position.y = m.from.y + (m.to.y - m.from.y) * t; + if (m.phase === 'jump' || m.phase === 'drop' || m.phase === 'climb-hop') { + const arc = m.phase === 'drop' ? this.config.bodySize * .25 : + Math.max(this.config.bodySize * .65, m.from.y - m.to.y + this.config.bodySize * .5); + this.position.y -= Math.sin(Math.PI * t) * arc; + } + if (m.phase === 'attach' && m.to.y < m.from.y) + this.position.y -= Math.sin(Math.PI * t) * this.config.bodySize * .3; + if (t < 1) return; + if (m.phase === 'approach') { this.startTransition(m.step, m.destination, now); return; } + if (m.phase === 'attach') { + m.phase = 'ascend'; m.from = { ...this.position }; + m.to = { x: this.position.x, y: m.destination.y + this.config.bodySize * .6 }; + m.start = now; m.duration = Math.max(1, (m.from.y - m.to.y) / + (this.config.climbSpeedSPerSec * this.config.bodySize) * 1000); + this.setState('climbing', 'attached to visible side edge', now); return; + } + if (m.phase === 'ascend') { + const hop = Math.random() < this.config.climbHopChance && + Math.abs(m.step.toX - m.step.edge.x) <= this.config.climbHopMaxDistanceS * this.config.bodySize; + m.phase = hop ? 'climb-hop' : 'pull-up'; + this.setState(hop ? 'climb-hopping' : 'pulling-up', hop ? 'short ledge hop' : 'ledge pull-up', now); + m.from = { ...this.position }; m.to = { x: m.step.toX, y: m.destination.y }; + m.start = now; + m.duration = clamp(450 + Math.random() * 150, this.config.pullUpDurationMinMs, this.config.pullUpDurationMaxMs); + m.wiggle = !hop && Math.random() < this.config.buttWiggleChance; + return; + } + this.platform = m.destination; this.motion = null; this.position.y = this.platform.y; + if (this.mode === 'active') this.activeRemaining = Math.max(0, this.activeRemaining - 1); + if (['jump', 'drop', 'climb-hop'].includes(m.phase)) { + this.setState('landing', `touchdown after ${m.phase}`, now); + this.deadline = now + 260; + } else { + this.setState('idle', `${m.phase} complete on platform`, now); + this.deadline = now + this.config.activeMovePauseMs / this.debugSpeed; + } + } + tick(now) { + if (!this.running) return; + const delta = Math.min(50, Math.max(0, now - (this.lastTime || now))); + this.lastTime = now; + if (document.hidden) { + if (!this.pausedAt) this.pausedAt = now; + this.frame = requestAnimationFrame(this.tick); return; + } + if (this.pausedAt) { + const paused = now - this.pausedAt; + if (this.motion) this.motion.start += paused; + this.deadline += paused; + this.pausedAt = 0; + } + if (this.reduced) { + this.frame = requestAnimationFrame(this.tick); return; + } + if (this.motion && now - this.motion.start > this.motion.duration + this.config.stuckTimeoutMs) { + this.stopAtSafeAnchor(); this.deadline = now + 1000; + } + if (this.motion) this.advance(now); + else if (now >= this.deadline) { + if (this.state === 'sleeping') { + this.mode = 'calm'; + this.setState('idle', 'woke from rest', now); + this.deadline = now + this.dwell('idle'); + } else if (this.state === 'purring' || this.state === 'batting') { + this.setState('idle', 'grounded activity complete', now); + this.deadline = now + this.dwell('idle'); + } else { + if (this.state === 'landing') this.setState('idle', 'landing interval complete', now); + if (this.mode === 'active' && this.activeRemaining <= 0) + this.endBurst(now, 'exploration complete'); + else if (this.route.length) this.beginNext(now); + else this.choose(now); + } + } + if (this.motion?.wiggle && this.motion.phase === 'pull-up') + this.position.x += Math.sin(now / 45) * Math.min(delta / 50, 1) * 1.5; + this.renderer.render(this.position, this.state, this.name); + this.drawDebug(); + this.frame = requestAnimationFrame(this.tick); + } + drawDebug() { + if (!this.options.debug || !this.renderer.element?.parentNode) return; + if (!this.debugElement) { + this.debugElement = document.createElement('div'); this.debugElement.className = 'companion-debug'; + this.root.append(this.debugElement); + } + this.debugElement.replaceChildren(); + for (const s of this.surfaces) { + const line = document.createElement('i'); line.className = 'companion-debug-surface'; + line.style.cssText = `left:${s.left}px;top:${s.y}px;width:${s.right - s.left}px`; + this.debugElement.append(line); + } + for (const e of this.edges) { + const line = document.createElement('i'); line.className = 'companion-debug-edge'; + line.style.cssText = `left:${e.x}px;top:${e.top}px;height:${e.bottom - e.top}px`; + this.debugElement.append(line); + } + for (const [fromId, transitions] of this.graph) { + const from = this.surfaces.find(s => s.id === fromId); + for (const transition of transitions) { + const to = this.surfaces.find(s => s.id === transition.to); + if (!from || !to) continue; + const line = document.createElement('i'); line.className = 'companion-debug-route'; + const x1 = transition.fromX, x2 = transition.toX, y1 = from.y, y2 = to.y; + const length = Math.hypot(x2 - x1, y2 - y1); + line.style.cssText = `left:${x1}px;top:${y1}px;width:${length}px;transform:rotate(${Math.atan2(y2-y1,x2-x1)}rad)`; + line.title = transition.kind; + this.debugElement.append(line); + } + } + for (const rejected of this.rejected.slice(0, 30)) { + if (!rejected.element?.isConnected) continue; + const rect = rejected.element.getBoundingClientRect(); + const mark = document.createElement('i'); mark.className = 'companion-debug-rejected'; + mark.style.cssText = `left:${rect.left}px;top:${rect.top}px`; + mark.title = rejected.reason; this.debugElement.append(mark); + } + const label = document.createElement('span'); label.textContent = + `${this.state} · ${this.platform?.id || 'none'} → ${this.motion?.destination?.id || 'none'} · ` + + `route ${this.route.map(s => s.kind).join(' → ')} · ` + + `mode ${this.mode}, steps ${this.activeRemaining}, next ${Math.max(0, Math.round(this.deadline - performance.now()))}ms, ` + + `motion ${this.motion?.phase || 'none'} · reason ${this.stateReason} · ` + + `trace ${this.trace.slice(-4).map(t => `${t.at}:${t.state}(${t.reason})`).join(' | ')} · ` + + `available jumps ${(this.graph.get(this.platform?.id) || []).filter(t => ['jump', 'drop'].includes(t.kind)).length} · ` + + `${this.surfaces.length} ledges, ${this.edges.length} edges, ${this.rejected.length} rejected ` + + `(${[...new Set(this.rejected.map(r => r.reason))].join(', ')}) · ` + + `S=${this.config.bodySize}, jump≤${this.config.maxJumpHorizontalS}S, rise≤${this.config.maxJumpRiseS}S, drop≤${this.config.maxJumpDropS}S`; + this.debugElement.append(label); + } + setReducedMotion(value) { + this.reduced = !!value; this.motion = null; this.route = []; + this.mode = 'calm'; this.activeRemaining = 0; + this.setState('idle', 'reduced motion preference'); + this.deadline = performance.now() + this.dwell('idle'); + if (this.platform) this.position.y = this.platform.y; + this.renderer.render(this.position, this.state, this.name); + } + setName(name) { this.name = name; this.renderer.render(this.position, this.state, this.name); } + destroy() { this.running = false; cancelAnimationFrame(this.frame); this.debugElement?.remove(); this.renderer.destroy(); } + } + const api = { configure, discover, graphFor, routes, visibleBorder, STATES, DEFAULTS }; + if (typeof module !== 'undefined' && module.exports) module.exports = api; + if (typeof window !== 'undefined') { window.BrowserCompanion = Companion; window.BrowserCompanionMovement = api; window.BrowserCompanionStates = STATES; } +})(); diff --git a/dashboard/templates/dashboard/index.html b/dashboard/templates/dashboard/index.html index 4c5ecba..1063ef3 100644 --- a/dashboard/templates/dashboard/index.html +++ b/dashboard/templates/dashboard/index.html @@ -1,6 +1,6 @@ -{% extends 'core/base.html' %}{% load static %}{% block content %} +{% extends 'core/base.html' %}{% load static %}{% block content %}
YOUR WORKSPACE

{{ title }}.

Make this space your own with a few useful widgets.

-
Layout saved
+
Layout saved
OverviewPersonal
{% for instance in instances %}{% include 'dashboard/widget_card.html' %}{% endfor %} @@ -10,5 +10,5 @@ {{ catalogue|length|json_script:"widget-count" }} - + {% endblock %} diff --git a/dashboard/tests/companion_movement.html b/dashboard/tests/companion_movement.html new file mode 100644 index 0000000..bb46967 --- /dev/null +++ b/dashboard/tests/companion_movement.html @@ -0,0 +1,305 @@ + +Companion movement checks +
Running…
+ + diff --git a/docs/card-attachments.md b/docs/card-attachments.md new file mode 100644 index 0000000..f9cb1fa --- /dev/null +++ b/docs/card-attachments.md @@ -0,0 +1,23 @@ +# 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. + +## Configuration + +Set `PROJECTS_PRIVATE_MEDIA_ROOT` to a persistent directory outside any web server static or public media alias. The default is `private_media/` under the repository for local development. Back up this directory alongside the database. The application account needs read/write access. No `MEDIA_URL` or public media route is configured. + +Limits default to 10 MiB per file, 50 files and 100 MiB per card. Override with `PROJECTS_ATTACHMENT_MAX_BYTES`, `PROJECTS_ATTACHMENT_MAX_FILES` and `PROJECTS_ATTACHMENT_MAX_CARD_BYTES`. MCP base64 upload/fetch has a stricter 2 MiB limit to bound tool payloads. The accepted extensions are UTF-8 text/code (`txt`, `md`, `py`, `js`, `ts`, `tsx`, `jsx`, `json`, `css`, `html`, `xml`, `csv`, `yaml`, `yml`, `sh`, `diff`, `patch`) and PNG, JPEG, WebP, PDF. HTML is always served as plain text. SVG and archives are rejected. Files are not extracted or executed. Download responses use `Content-Disposition: attachment`, `nosniff`, and `no-store`. + +## Web use + +On a card page, upload multiple files in **Card files** or beneath a specific progress note. The form works without JavaScript; JavaScript adds drag and drop, progress and inline error feedback. The card and note sections share a simple list. Safe images up to 1 MiB have a thumbnail and preview link; UTF-8 text up to 1 MiB has a text preview. Other files download. Rename changes only the display title. Deleting requires confirmation. + +All reads require project access. Upload, rename and delete require editor or owner access. Django session forms use CSRF. An attachment ID alone does not grant access. + +## MCP transfer + +`attachments_list(card_id, comment_id?, limit?, offset?)` returns metadata for card and note files. `attachments_get(attachment_id)` returns metadata. `attachments_fetch(attachment_id)` returns exact `content_base64`, SHA-256, and decoded `text` for UTF-8 files. `attachments_upload(card_id, filename, content_base64, comment_id?, title?, description?, source_path?, source_commit?)` transfers bytes to the server. `attachments_update` changes display metadata; `attachments_delete` removes bytes and metadata. Read tools require `projects:read`; writes require `projects:write`. Each tool checks card access. A remote server never reads a caller's filesystem path. + +For a local repository snapshot, read the file locally, calculate its SHA-256, base64 encode the bytes, then call `attachments_upload` with the target card and progress-note IDs. Include a repository-relative `source_path` and a Git commit SHA when available. Compare the returned SHA-256; `attachments_fetch` lets another client verify exact bytes. If a working-tree file differs from the recorded commit, describe that in the progress note; `source_commit` alone cannot establish the working-tree state. + +The tool output uses standard base64 in structured JSON so clients can reconstruct binary files. Client support for passing generated image bytes into a tool, exposing large tool payloads, and rendering fetched images must be checked against a deployed MCP connection. The local tests exercise the actual MCP tool call path for text bytes and permission denial; they cannot establish compatibility with a remote ChatGPT client before deployment. diff --git a/docs/companion-movement.md b/docs/companion-movement.md new file mode 100644 index 0000000..8a8023b --- /dev/null +++ b/docs/companion-movement.md @@ -0,0 +1,17 @@ +# Companion movement prototype + +`dashboard/static/dashboard/companion.js` is a browser-only, framework-independent movement core. A host creates `new BrowserCompanion({ surfaces, name, reducedMotion, config, debug, debugSpeed })`; `surfaces()` returns `{ element, edge: 'top' | 'bottom', card?, explicit? }` entries. The host owns DOM discovery, preferences, and lifecycle. The core owns geometry validation, the directed route graph, movement and the coloured-square renderer. A host may supply a renderer implementing `render(position, state, name)` and `destroy()`. + +`bodySize` is the collision-body height in CSS pixels, independent of future sprite padding. Distance settings ending in `S` are multiples of that size. Speed settings ending in `SPerSec` use those units per second. Durations are milliseconds. `configure()` clamps invalid numeric overrides and ignores unknown keys. The defaults are initial visual tuning values, not animal measurements. + +An ordinary nested ledge needs a visible computed top border of at least 1 CSS pixel. Climb edges need visible left or right borders. Outer widget top and bottom edges are explicit known surfaces. Interactive controls are excluded unless a host deliberately opts one in. Geometry reads are performed on host refresh events, not each animation frame. The Project Manager adapter refreshes after grid changes, scrolling, resizing and widget mount or removal. + +Directed routes include short jumps, steps, walks, side climbs and bounded drops. A short attach hop can bridge the normal grid gap to a visible climb edge if its rise stays within `maxJumpRiseS`; this allows a safe drop to a lower card to be followed by a climb back. Downward climbing is not enabled. If a destination cannot be reached through a complete safe route, the companion idles or patrols its current ledge. Page scroll keeps its position attached to the source element. A disappearing destination cancels the move and recovers only to a nearby valid ledge; otherwise the box is hidden until a safe anchor appears. Background tabs pause motion, and reduced motion stops autonomous movement. + +The activity scheduler has calm, active and resting modes. Normal calm idle lasts 12–20 seconds, sleep 20–45 seconds, and purring/batting 2.2–3.8 seconds. Active bursts plan 2–5 safe transitions before returning to calm; short movement pauses do not choose unrelated passive states. Emote and sleep cooldowns prevent rapid cycling. Rest becomes more likely after repeated bursts. These bounds and activity weights are host-overridable through `config`. For local debugging only, `?companionFast` scales dwell and cooldown time by 10 without changing movement safety or turning on the visual debug overlay. + +Append `?companionDebug` to the dashboard URL to show ledges, climb edges, graph transitions, rejected element marks, active route and movement limits. The overlay is disabled by default and never receives pointer events. + +The debug label also shows the current state reason, recent timestamped transitions, mode, remaining burst steps, next dwell timer, active motion phase, and the number of safe jump/drop edges available from the current platform. `landing` lasts 260 ms and is entered only after an airborne jump, drop, or climb hop. Walking, pull-ups, reflow, and completed routes settle to `idle` instead. + +The dependency-free browser checks live in `dashboard/tests/companion_movement.html`. Serve the repository root with a local static server and open that page; every line should report `PASS`. The Django dashboard suite remains runnable with `.venv/bin/python manage.py test dashboard`. diff --git a/docs/research/project-documentation-wiki-evaluation.md b/docs/research/project-documentation-wiki-evaluation.md new file mode 100644 index 0000000..a9d3576 --- /dev/null +++ b/docs/research/project-documentation-wiki-evaluation.md @@ -0,0 +1,81 @@ +# Project documentation and MCP evaluation + +Research snapshot: 20 October 2026. Repository inspected at `dd1ee39` with uncommitted local changes; this report makes no runtime changes. + +## Recommendation + +**Go for a small native Django documentation module; do not install or fork a wiki for the MVP.** Treat the repository's Markdown files as the source of truth. Import a versioned, project-scoped snapshot into the database for browsing and MCP retrieval, then show its source commit and freshness on every read. This gives agents a bounded, searchable map of project context without rescanning the repository each time. The database index is a cache of a declared Git snapshot, not an independent authority. + +The first milestone should be **read-only documentation**: upload a Markdown ZIP, review its preview, publish the imported snapshot, browse a tree, search, and use `docs_list`, `docs_search`, and `docs_read` over MCP. Do not accept MCP edits until there is a concrete export/reconciliation workflow. Later edits can be proposed revisions with an explicit base source commit and document hash, downloaded as Markdown ZIP or applied through a separately approved Git workflow. Never silently alter the published snapshot or repository. + +## Evidence in this project + +| Existing part | Reuse / gap | +| --- | --- | +| `projects/models.py`: `Project` has `git_repository_url`, owner, and `Membership`; `Card` and `CardRevision` store Markdown and revisions | Reuse project identity and access policy. The URL is metadata only; neither Django nor MCP clones repositories. Documents need their own path, source commit/hash, and version model, separate from Kanban cards. | +| `projects/services.py`: `accessible()` and `project_for(..., write=True)` | Reuse for **every** document query and mutation. Owner/editor can import; viewer can read. Do not rely only on template visibility or Django's global model permissions. | +| `projects/templatetags/project_markdown.py` | Python-Markdown plus `nh3` already sanitizes rendered HTML. Extract a shared renderer function and use it for docs; add a controlled link resolver for relative `.md` links. Current sanitizer allows only `http`, `https`, and `mailto` URLs, so ordinary relative links are stripped until resolved. | +| `projects/views.py`, `projects/urls.py` | Authenticated project pages and CSRF-protected POST patterns already exist. Add project-scoped docs routes and a navigation link without changing the board data model. | +| `mcp_server/server.py` | MCP uses `MCPServer`, `projects:read`/`projects:write`, `_project`, `_safe`, and bounded list patterns. Add document tools through the same service layer. Current `cards_search` and `search_global` return full Markdown per hit; docs search should return short snippets and metadata to stay useful at scale. | +| `config/settings.py` | SQLite is the configured database. Design search to work with SQLite first; consider SQLite FTS5 after profiling. PostgreSQL search is not a current dependency. | +| `projects/attachments.py`, `docs/card-attachments.md` | Useful reference for private storage, upload limits, and provenance, but card attachments do not provide a navigable documentation tree or searchable document text. | + +## Candidate comparison + +| Candidate | Current release / licence | Fit and integration cost | Verdict | +| --- | --- | --- | --- | +| [django-wakawaka](https://pypi.org/project/django-wakawaka/) | 1.7, 7 Feb 2026; MIT. Its published compatibility matrix ends at Django 5.2, with no declared Django 6.1 test. | Small dependency, but its [model](https://github.com/bartTC/django-wakawaka/blob/main/wakawaka/models.py) has a global `slug`, no project foreign key; [views](https://github.com/bartTC/django-wakawaka/blob/main/wakawaka/views.py) query all pages and use global Django permissions. Its [page template](https://github.com/bartTC/django-wakawaka/blob/main/wakawaka/templates/wakawaka/page.html) uses `urlize|wikify|linebreaks`, not Markdown. Replacing the template is easy, but adding project isolation, paths, imports, source snapshots, and MCP would replace much of its behavior. The inspected revision view also looks up a revision by ID without checking it belongs to the requested page, making a direct integration unsuitable for project-private docs. | No dependency or fork for MVP. Retest Django 6.1 only if considering it later. | +| [django-wiki (`wiki`)](https://pypi.org/project/wiki/) | 0.13.0, 31 Jul 2026; GPL-3.0. [Package metadata](https://github.com/django-wiki/django-wiki/blob/main/pyproject.toml) requires `Django>=4.2,<6.1` and several app dependencies. | Mature, revisioned wiki with Markdown and tree features, but dependency constraint conflicts with this repo's `Django>=6.1,<6.2`. Its plugin and renderer stack would add a second content system. | No-go on current stack. | +| [Waliki](https://pypi.org/project/waliki/) | 0.8.1, 26 Mar 2017; BSD. | Git-backed premise is attractive, but its published documentation targets Django 1.8/1.9-era Python. No evidence of current Django 6.1 compatibility. | No-go; major port/fork risk. | +| [djiki](https://pypi.org/project/djiki/) | 0.9, 1 May 2022; BSD-3-Clause. | Its inspected models use globally unique page titles/language, not project-scoped file paths. Published classifiers stop at Python 3.10, with no current Django 6.1 evidence. | No-go for this use case. | +| Native Django docs module | No new wiki dependency or third-party licence | Smallest domain fit: project/path uniqueness, Git provenance, import preview, permission checks, MCP output shape, and existing sanitizer can be designed together. | Recommended. | + +The Wakawaka renderer verdict is especially clear: there is no Markdown renderer to replace. A template override could call `safe_markdown`, but the default CamelCase substitution and global data model still conflict with normal repository Markdown. Forking it would create long-term maintenance without removing the custom work. + +## Proposed shape + +1. `ProjectDocument`: `project`, normalized case-preserving POSIX `path` (e.g. `README.md`, `docs/architecture/mcp.md`), raw Markdown, content SHA-256, title extracted from heading or filename, `revision`, source commit, imported time, and status. Unique `(project, path)`; index `(project, path)` and search fields. A separate `DocumentRevision` stores immutable previous content, actor, timestamp, and source/proposal type if editing is added. +2. `DocumentSnapshot` or import batch records project, source commit supplied by uploader, ZIP hash, imported time, counts, and outcome. Record whether the commit was verified against a trusted repository checkout; an uploader-supplied SHA alone is **unverified provenance**. A published snapshot stays queryable until a complete replacement succeeds. Display freshness as "as of commit X / imported at Y"; do not claim current Git state unless verified. +3. Navigation is generated from paths, with `README.md` as landing page when present and `AGENTS.md` visible as a first-class context file. Preserve exact Markdown text for MCP. Resolve relative links against the source document's parent path; rewrite only links to imported documents and anchors. External links retain the current sanitizer's URL restrictions. Report broken internal links on import. +4. A project docs page offers tree, search, raw/view modes, source commit, stale/unverified badge, and import/export controls for editors. Missing docs state explains how to upload an archive. Use normal login, CSRF, and project authorization. Do not show a success state after a partial import failure. + +### MCP contract and agent context + +| Tool | Return shape / controls | +| --- | --- | +| `docs_list(project, prefix?, cursor?, limit?)` | Paths, titles, hashes, revision, snapshot/commit, modified time; stable path order, at most 100 items, cursor pagination. | +| `docs_search(query, project?, cursor?, limit?)` | Search only accessible projects; path/title, bounded excerpt, project ID, commit/hash, and direct read locator. Limit query and excerpt size. Search metadata first, full text second. Do not return whole files per hit. | +| `docs_read(project, path, revision?, start_line?, line_count?)` | Exact Markdown or a bounded line window, total line count, hash, source commit, verified/stale status, canonical path. Reject invalid paths and excessive output; permit explicit paging for large files. | + +For the user's memory goal, start each work session with `docs_list` or targeted `docs_search`, then `docs_read` for the few relevant files. A small curated `docs/PROJECT_CONTEXT.md` or existing `AGENTS.md` can point to architecture, conventions, deployment, and current decisions; the index should not auto-concatenate all documents into every response. Keep path/hash/commit in replies so the agent can tell when context is old and inspect live source before changing code. The docs index reduces repeated discovery, but it cannot guarantee that unimported code changes are reflected. + +Later `docs_create`/`docs_update` should require `projects:write`, project editor rights, normalized path, size cap, and `expected_revision` plus `base_source_commit`/content hash. Store proposals separately from published Git-backed content. Guard deletion as a proposal or tombstone, with explicit export and conflict handling. No direct Git fetch/push, credentials, or arbitrary filesystem paths in MVP. + +## ZIP workflow and controls + +Preview before commit: accept only UTF-8 `.md` files from declared roots (`README.md`, `AGENTS.md`, `docs/**` or a selected docs subtree); display additions, changes, removals, broken links, and conflict warnings. Reject duplicate normalized paths, absolute paths, `..`, backslashes or ambiguous separators, symlinks and other nonregular entries, hidden control files, and oversized archives. Bound compressed bytes, expanded bytes, file count, per-file bytes, compression ratio, and nesting depth; inspect ZIP metadata before reading and stream under limits. Normalize Unicode and define case-collision behavior. Require the expected previous snapshot ID/commit before a re-import; publish atomically. Export Markdown paths plus a manifest with source commit and hashes; exclude server-only metadata and secrets. Import must never extract directly into the repository or execute contents. + +## Work estimate and stages + +These are rough engineering estimates, not commitments; integration and review may change them. + +| Stage | Scope | Estimate | +| --- | --- | --- | +| 1 | Models/migrations, service authorization, path validation, snapshot provenance, tests | 2–3 days | +| 2 | ZIP preview/import/export, limits, link checks, atomic replacement, tests | 2–4 days | +| 3 | Browsing/search UI, renderer/link adapter, accessible states | 2–3 days | +| 4 | Read-only MCP tools, pagination/output limits, permission tests | 1–2 days | +| Later | Proposed edits/reconciliation/export, conflict handling | 2–4 days after workflow decision | + +An MVP is roughly **7–12 engineering days**. The main uncertainties are archive scale, exact desired Git provenance, and whether a read-only import meets the workflow. No implementation is blocked by a missing wiki library. + +## Decisions before implementation + +- Choose the ingestion boundary: manual ZIP upload first (recommended) or trusted server-side checkout. The current Git URL is metadata and must not become an arbitrary fetch target without host allowlisting, credential design, and SSRF controls. +- Choose whether the initial import mirrors only tracked documentation files or allows uploaded notes not in Git. If Git is authoritative, label non-Git notes separately. +- Decide when a snapshot is considered stale. An import timestamp alone cannot prove repository freshness; a trusted commit check or explicit manual refresh is needed. +- Decide whether cross-project `docs_search` should be enabled for every authorized membership or opt-in for sensitive projects. The existing MCP `search_global` searches across all accessible projects, so the former is consistent with present behavior. + +## Sources and inspection method + +Local sources: `requirements.txt`, `config/settings.py`, `projects/models.py`, `projects/services.py`, `projects/views.py`, `projects/templatetags/project_markdown.py`, `mcp_server/server.py`, `projects/attachments.py`, and `README.md`. Upstream release metadata came from the linked PyPI pages; package source distributions were inspected directly for models, views, templates, and dependency declarations. These findings establish design fit, not runtime compatibility tests against Django 6.1. diff --git a/mcp_server/server.py b/mcp_server/server.py index daab669..12b9d8b 100644 --- a/mcp_server/server.py +++ b/mcp_server/server.py @@ -1,5 +1,7 @@ """Streamable HTTP MCP server for project management. Run on port 8766.""" import os +import base64 +import binascii from datetime import date from typing import Any, Literal from urllib.parse import urlsplit @@ -28,7 +30,8 @@ from mcp.server.transport_security import TransportSecuritySettings from pydantic import AnyHttpUrl from projects import services -from projects.models import Activity, Card, CardComment, CardRevision, Column, Project, Tag +from projects.models import Activity, Card, CardComment, CardRevision, CardAttachment, Column, Project, Tag +from projects import attachments def _verified(raw): @@ -101,7 +104,7 @@ def _column_data(column): def _safe(operation): try: return operation() - except (Http404, Project.DoesNotExist, Card.DoesNotExist, Column.DoesNotExist, CardRevision.DoesNotExist, Tag.DoesNotExist, get_user_model().DoesNotExist): + except (Http404, Project.DoesNotExist, Card.DoesNotExist, Column.DoesNotExist, CardRevision.DoesNotExist, CardAttachment.DoesNotExist, Tag.DoesNotExist, get_user_model().DoesNotExist): raise ToolError('not_found: project or card is unavailable') except PermissionDenied: raise ToolError('permission_denied: write access required') @@ -261,6 +264,14 @@ def create_server(): return _card_data(services.update_card(user, card, expected_revision=expected_revision, origin='mcp', **values)) return await sync_to_async(lambda: _safe(run))() + @server.tool(structured_output=True, description='Preview or atomically update 1–100 cards in one project. Supply every card ID and current revision. Changes may contain column_id, priority, assignee_id (null clears), or tag_ids (empty list clears). Dry run has no writes. Retries require the same idempotency key and payload.') + async def cards_bulk_update(project: str, card_ids: list[str], expected_revisions: dict[str, int], changes: dict[str, Any], dry_run: bool = True, idempotency_key: str | None = None) -> dict[str, Any]: + def run(): + user = _actor('projects:write') + p = _project(user, project, write=True) + return services.bulk_update_cards(user, p, card_ids, expected_revisions, changes, dry_run=dry_run, idempotency_key=idempotency_key, origin='mcp') + return await sync_to_async(lambda: _safe(run))() + @server.tool(structured_output=True, description='List cards in an accessible project; filter by priority, column, or archived state.') async def cards_list(project: str, priority: Literal['low', 'medium', 'high'] | None = None, card_type: Literal['feature', 'bug', 'task', 'research', 'idea'] | None = None, column_id: str | None = None, tag_id: int | None = None, assignee_id: int | None = None, archived: bool = False, limit: int = 50, offset: int = 0) -> dict[str, Any]: def run(): @@ -314,6 +325,72 @@ def create_server(): return {'items': [{'id': c.pk, 'body': c.body, 'author_id': c.author_id, 'created_at': c.created_at.isoformat()} for c in card.comments.order_by('-created_at')[:min(max(limit, 1), 100)]]} return await sync_to_async(lambda: _safe(run))() + @server.tool(structured_output=True, description='List card and progress-note attachment metadata. Set comment_id to limit to one progress note; otherwise includes both kinds. Paginated, with a card UUID required.') + async def attachments_list(card_id: str, comment_id: int | None = None, limit: int = 50, offset: int = 0) -> dict[str, Any]: + def run(): + card = _card(_actor(), card_id) + qs = CardAttachment.objects.filter(card=card).order_by('created_at', 'id') + if comment_id is not None: + if not card.comments.filter(pk=comment_id).exists(): raise ValidationError('Progress note does not belong to this card.') + qs = qs.filter(comment_id=comment_id) + return {'items': [attachments.attachment_data(a) for a in qs[max(offset, 0):max(offset, 0) + min(max(limit, 1), 100)]], 'total': qs.count()} + return await sync_to_async(lambda: _safe(run))() + + @server.tool(structured_output=True, description='Get attachment metadata by stable UUID after checking access to its card.') + async def attachments_get(attachment_id: str) -> dict[str, Any]: + def run(): + item = CardAttachment.objects.get(pk=UUID(attachment_id)) + _card(_actor(), str(item.card_id)) + return attachments.attachment_data(item) + return await sync_to_async(lambda: _safe(run))() + + @server.tool(structured_output=True, description='Fetch exact attachment bytes as base64 (maximum 2 MiB), with SHA-256 and UTF-8 text for supported text files. Access to the card is required.') + async def attachments_fetch(attachment_id: str) -> dict[str, Any]: + def run(): + item = CardAttachment.objects.get(pk=UUID(attachment_id)) + _card(_actor(), str(item.card_id)) + if item.byte_size > attachments.MAX_MCP_BYTES: raise ValidationError('Attachment exceeds MCP fetch limit; download via the authenticated web UI.') + with item.file.open('rb') as stream: data = stream.read(attachments.MAX_MCP_BYTES + 1) + if len(data) != item.byte_size: raise ValidationError('Stored file size differs from metadata.') + result = {**attachments.attachment_data(item), 'content_base64': base64.b64encode(data).decode('ascii')} + if item.mime_type == 'text/plain': result['text'] = data.decode('utf-8') + return result + return await sync_to_async(lambda: _safe(run))() + + @server.tool(structured_output=True, description='Upload exact file bytes encoded as standard base64 to a card or specified progress note. Maximum 2 MiB. Optional source_path and source_commit record an immutable repository snapshot; server paths are never read.') + async def attachments_upload(card_id: str, filename: str, content_base64: str, comment_id: int | None = None, title: str = '', description: str = '', source_path: str = '', source_commit: str = '') -> dict[str, Any]: + def run(): + user = _actor('projects:write'); card = _card(user, card_id, write=True) + if len(content_base64) > (attachments.MAX_MCP_BYTES * 4 // 3 + 8): raise ValidationError('MCP upload exceeds 2 MiB.') + try: data = base64.b64decode(content_base64, validate=True) + except (binascii.Error, ValueError): raise ValidationError('Invalid base64 content.') + if len(data) > attachments.MAX_MCP_BYTES: raise ValidationError('MCP upload exceeds 2 MiB.') + item = attachments.upload_attachment(user, card, filename=filename, data=data, comment_id=comment_id, + title=title, description=description, source='mcp', source_path=source_path, source_commit=source_commit) + return attachments.attachment_data(item) + return await sync_to_async(lambda: _safe(run))() + + @server.tool(structured_output=True, description='Update an attachment display title or description. File bytes and provenance remain unchanged.') + async def attachments_update(attachment_id: str, title: str | None = None, description: str | None = None) -> dict[str, Any]: + def run(): + item = CardAttachment.objects.get(pk=UUID(attachment_id)) + _card(_actor('projects:write'), str(item.card_id), write=True) + if title is not None: item.title = title.strip() + if description is not None: item.description = description + item.full_clean(); item.save(update_fields=['title', 'description']) + return attachments.attachment_data(item) + return await sync_to_async(lambda: _safe(run))() + + @server.tool(structured_output=True, description='Delete a card or progress-note attachment and its stored bytes after checking card write access.') + async def attachments_delete(attachment_id: str) -> dict[str, Any]: + def run(): + item = CardAttachment.objects.select_related('card__project').get(pk=UUID(attachment_id)) + user = _actor('projects:write'); _card(user, str(item.card_id), write=True) + identifier = str(item.pk) + attachments.delete_attachment(user, item, source='mcp') + return {'id': identifier, 'deleted': True} + return await sync_to_async(lambda: _safe(run))() + @server.tool(structured_output=True, description='List card activity and revision numbers.') async def cards_history(card_id: str, limit: int = 50) -> dict[str, Any]: def run(): diff --git a/projects/apps.py b/projects/apps.py index afae498..a94b2ce 100644 --- a/projects/apps.py +++ b/projects/apps.py @@ -4,3 +4,13 @@ from django.apps import AppConfig class ProjectsConfig(AppConfig): default_auto_field = 'django.db.models.BigAutoField' name = 'projects' + + def ready(self): + from django.db.models.signals import post_delete + from .models import CardAttachment + + def remove_stored_file(sender, instance, **kwargs): + if instance.file: + instance.file.delete(save=False) + + post_delete.connect(remove_stored_file, sender=CardAttachment, weak=False, dispatch_uid='projects.remove_attachment_file') diff --git a/projects/attachments.py b/projects/attachments.py new file mode 100644 index 0000000..bddc596 --- /dev/null +++ b/projects/attachments.py @@ -0,0 +1,102 @@ +"""Private, card-scoped attachment validation and storage.""" +import hashlib +from pathlib import PurePath +from uuid import uuid4 + +from django.conf import settings +from django.core.exceptions import ValidationError +from django.core.files.base import ContentFile +from django.db import transaction +from django.db.models import Sum +from django.utils.text import get_valid_filename + +from .models import Activity, Card, CardAttachment, CardComment + + +TEXT_EXTENSIONS = {'.txt', '.md', '.py', '.js', '.ts', '.tsx', '.jsx', '.json', '.css', '.html', '.xml', '.csv', '.yaml', '.yml', '.sh', '.diff', '.patch'} +SIGNATURES = {'.png': (b'\x89PNG\r\n\x1a\n', 'image/png'), '.jpg': (b'\xff\xd8\xff', 'image/jpeg'), '.jpeg': (b'\xff\xd8\xff', 'image/jpeg'), '.webp': (b'RIFF', 'image/webp'), '.pdf': (b'%PDF-', 'application/pdf')} +MAX_MCP_BYTES = 2 * 1024 * 1024 + + +def attachment_data(item): + return {'id': str(item.pk), 'card_id': str(item.card_id), 'comment_id': item.comment_id, + 'title': item.title, 'original_filename': item.original_filename, + 'mime_type': item.mime_type, 'byte_size': item.byte_size, 'sha256': item.sha256, + 'description': item.description, 'uploaded_by_id': item.uploaded_by_id, + 'source': item.source, 'source_path': item.source_path, 'source_commit': item.source_commit, + 'created_at': item.created_at.isoformat()} + + +def _validated_name(name): + # Reject path components rather than silently changing their meaning. + if not name or len(name) > 255 or '\\' in name or '/' in name or name in {'.', '..'}: + raise ValidationError('Use a filename without a path.') + clean = get_valid_filename(name) + if not clean or clean.startswith('.'): + raise ValidationError('Invalid filename.') + return clean + + +def _detected_type(name, data): + suffix = PurePath(name).suffix.lower() + if suffix in TEXT_EXTENSIONS: + if b'\x00' in data: + raise ValidationError('Text files must not contain binary data.') + try: + data.decode('utf-8') + except UnicodeDecodeError: + raise ValidationError('Text files must use UTF-8.') + return 'text/plain' + if suffix in SIGNATURES: + signature, mime = SIGNATURES[suffix] + if not data.startswith(signature): + raise ValidationError('File contents do not match the extension.') + if suffix == '.webp' and data[8:12] != b'WEBP': + raise ValidationError('Invalid WebP file.') + return mime + raise ValidationError('Unsupported file type.') + + +@transaction.atomic +def upload_attachment(user, card, *, filename, data, comment_id=None, title='', description='', source='web', source_path='', source_commit=''): + if len(data) > settings.PROJECTS_ATTACHMENT_MAX_BYTES: + raise ValidationError('File exceeds the per-file size limit.') + if not data: + raise ValidationError('File is empty.') + filename = _validated_name(filename) + mime = _detected_type(filename, data) + if len(title) > 255 or len(description) > 2000 or len(source_path) > 500: + raise ValidationError('Attachment metadata is too long.') + if source_commit and (len(source_commit) not in (40, 64) or any(c not in '0123456789abcdefABCDEF' for c in source_commit)): + raise ValidationError('Source commit must be a Git SHA.') + Card.objects.select_for_update().get(pk=card.pk) + qs = CardAttachment.objects.filter(card=card) + if qs.count() >= settings.PROJECTS_ATTACHMENT_MAX_FILES: + raise ValidationError('Card attachment count limit reached.') + if (qs.aggregate(total=Sum('byte_size'))['total'] or 0) + len(data) > settings.PROJECTS_ATTACHMENT_MAX_CARD_BYTES: + raise ValidationError('Card attachment storage limit reached.') + comment = None + if comment_id is not None: + comment = CardComment.objects.filter(card=card, pk=comment_id).first() + if comment is None: + raise ValidationError('Progress note does not belong to this card.') + item = CardAttachment(card=card, comment=comment, original_filename=filename, title=title.strip() or filename, + mime_type=mime, byte_size=len(data), sha256=hashlib.sha256(data).hexdigest(), + description=description, uploaded_by=user, source=source, + source_path=source_path, source_commit=source_commit) + item.file.save(f'{uuid4().hex}{PurePath(filename).suffix.lower()}', ContentFile(data), save=False) + try: + item.full_clean() + item.save() + except Exception: + item.file.delete(save=False) + raise + Activity.objects.create(project=card.project, card=card, actor=user, action='attachment.added', + detail={'attachment_id': str(item.pk), 'comment_id': comment_id}, origin=source) + return item + + +def delete_attachment(user, item, *, source='web'): + Activity.objects.create(project=item.card.project, card=item.card, actor=user, action='attachment.deleted', + detail={'attachment_id': str(item.pk), 'comment_id': item.comment_id}, origin=source) + item.delete() diff --git a/projects/migrations/0004_bulkupdatekey.py b/projects/migrations/0004_bulkupdatekey.py new file mode 100644 index 0000000..1d8ff4f --- /dev/null +++ b/projects/migrations/0004_bulkupdatekey.py @@ -0,0 +1,30 @@ +# Generated by Django 6.1.2 on 2026-10-16 13:59 + +import django.db.models.deletion +from django.conf import settings +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('projects', '0003_oauthidentity'), + migrations.swappable_dependency(settings.AUTH_USER_MODEL), + ] + + operations = [ + migrations.CreateModel( + name='BulkUpdateKey', + 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_bulk_update_key')], + }, + ), + ] diff --git a/projects/migrations/0005_cardattachment.py b/projects/migrations/0005_cardattachment.py new file mode 100644 index 0000000..e509d46 --- /dev/null +++ b/projects/migrations/0005_cardattachment.py @@ -0,0 +1,41 @@ +# Generated by Django 6.1.2 on 2026-10-16 20:15 + +import django.db.models.deletion +import uuid +from django.conf import settings +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('projects', '0004_bulkupdatekey'), + migrations.swappable_dependency(settings.AUTH_USER_MODEL), + ] + + operations = [ + migrations.CreateModel( + name='CardAttachment', + fields=[ + ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)), + ('file', models.FileField(upload_to='card-attachments/%Y/%m/')), + ('original_filename', models.CharField(max_length=255)), + ('title', models.CharField(max_length=255)), + ('mime_type', models.CharField(max_length=100)), + ('byte_size', models.PositiveIntegerField()), + ('sha256', models.CharField(max_length=64)), + ('description', models.TextField(blank=True)), + ('source', models.CharField(default='web', max_length=16)), + ('source_path', models.CharField(blank=True, max_length=500)), + ('source_commit', models.CharField(blank=True, max_length=64)), + ('created_at', models.DateTimeField(auto_now_add=True)), + ('card', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='attachments', to='projects.card')), + ('comment', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='attachments', to='projects.cardcomment')), + ('uploaded_by', models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL)), + ], + options={ + 'ordering': ['created_at', 'id'], + 'indexes': [models.Index(fields=['card', 'comment', 'created_at'], name='projects_ca_card_id_90f14b_idx')], + }, + ), + ] diff --git a/projects/models.py b/projects/models.py index 42f7750..3b0856b 100644 --- a/projects/models.py +++ b/projects/models.py @@ -1,6 +1,7 @@ import uuid from django.conf import settings from django.core.validators import RegexValidator +from django.core.exceptions import ValidationError from django.db import models from django.db.models import Q @@ -122,6 +123,32 @@ class CardComment(models.Model): created_at = models.DateTimeField(auto_now_add=True) +class CardAttachment(models.Model): + id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False) + card = models.ForeignKey(Card, on_delete=models.CASCADE, related_name='attachments') + comment = models.ForeignKey(CardComment, null=True, blank=True, on_delete=models.CASCADE, related_name='attachments') + file = models.FileField(upload_to='card-attachments/%Y/%m/') + original_filename = models.CharField(max_length=255) + title = models.CharField(max_length=255) + mime_type = models.CharField(max_length=100) + byte_size = models.PositiveIntegerField() + sha256 = models.CharField(max_length=64) + description = models.TextField(blank=True) + uploaded_by = models.ForeignKey(settings.AUTH_USER_MODEL, null=True, on_delete=models.SET_NULL) + source = models.CharField(max_length=16, default='web') + source_path = models.CharField(max_length=500, blank=True) + source_commit = models.CharField(max_length=64, blank=True) + created_at = models.DateTimeField(auto_now_add=True) + + class Meta: + ordering = ['created_at', 'id'] + indexes = [models.Index(fields=['card', 'comment', 'created_at'])] + + def clean(self): + if self.comment_id and not CardComment.objects.filter(pk=self.comment_id, card_id=self.card_id).exists(): + raise ValidationError({'comment': 'Progress note must belong to this card.'}) + + class CreationKey(models.Model): user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE) key = models.CharField(max_length=128) @@ -133,6 +160,17 @@ class CreationKey(models.Model): constraints = [models.UniqueConstraint(fields=['user', 'key'], name='unique_card_creation_key')] +class BulkUpdateKey(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_bulk_update_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') diff --git a/projects/services.py b/projects/services.py index 047d66f..df71155 100644 --- a/projects/services.py +++ b/projects/services.py @@ -1,5 +1,6 @@ import hashlib import json +from uuid import UUID from django.core.exceptions import PermissionDenied, ValidationError from django.db import transaction from django.db.models import Q, Max @@ -7,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, Card, CardRevision, Column, CreationKey, Membership, Project, Tag +from .models import Activity, Board, BulkUpdateKey, Card, CardRevision, Column, CreationKey, Membership, Project, Tag class RevisionConflict(Exception): @@ -119,12 +120,13 @@ def update_card(user, card, *, expected_revision=None, origin='web', **changes): @transaction.atomic -def move_card(user, card, column, position=None, origin='web'): +def move_card(user, card, column, position=None, origin='web', record_revision=True): card = Card.objects.select_for_update().get(pk=card.pk) project_for(user, card.project_id, write=True) if column.board.project_id != card.project_id or column.archived: raise ValidationError('Column is not available in this project.') old_column = card.column_id + old_position = card.position card.column = column card.completed_at = timezone.now() if column.is_done and not card.completed_at else (None if not column.is_done else card.completed_at) siblings = list(Card.objects.filter(column=column, archived=False).exclude(pk=card.pk).order_by('position', 'created_at')) @@ -133,7 +135,12 @@ def move_card(user, card, column, position=None, origin='web'): for i, item in enumerate(siblings): item.position = i item.save(update_fields=['position']) + moved = old_column != column.pk or old_position != card.position + if moved and record_revision: + card.revision += 1 card.save() + if moved and record_revision: + CardRevision.objects.create(card=card, revision=card.revision, markdown=card.description_markdown, actor=user) Activity.objects.create(project=card.project, card=card, actor=user, action='card.moved', detail={'from': str(old_column), 'to': str(column.pk)}, origin=origin) return card @@ -219,3 +226,96 @@ def set_tags(user, card, tags, origin='web'): card.tags.set(tags) Activity.objects.create(project=card.project, card=card, actor=user, action='card.tags_changed', origin=origin) return card + + +@transaction.atomic +def bulk_update_cards(user, project, card_ids, expected_revisions, changes, *, dry_run=False, idempotency_key=None, origin='web'): + """Validate the entire batch before writing; every mutation shares one transaction.""" + project_for(user, project.pk, write=True) + if not isinstance(card_ids, list) or not 1 <= len(card_ids) <= 100: + raise ValidationError('Select between 1 and 100 cards.') + try: + ids = [str(UUID(str(value))) for value in card_ids] + except (ValueError, TypeError, AttributeError): + raise ValidationError('Invalid card ID.') + if len(set(ids)) != len(ids): + raise ValidationError('Duplicate card IDs are not allowed.') + if not isinstance(changes, dict) or not changes or set(changes) - {'column_id', 'priority', 'assignee_id', 'tag_ids'}: + raise ValidationError('Supply supported changes: column_id, priority, assignee_id or tag_ids.') + if 'priority' in changes and changes['priority'] not in dict(Card.PRIORITY): + raise ValidationError('Invalid priority.') + payload_hash = hashlib.sha256(json.dumps({'project': str(project.pk), 'ids': ids, 'revisions': expected_revisions, 'changes': changes}, sort_keys=True).encode()).hexdigest() + if idempotency_key and not dry_run: + if len(idempotency_key) > 128: + raise ValidationError('Idempotency key is too long.') + user.__class__.objects.select_for_update().get(pk=user.pk) + existing = BulkUpdateKey.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 changes.') + return existing.result + cards = {str(card.pk): card for card in Card.objects.select_for_update().filter(pk__in=ids, project=project, archived=False).select_related('column')} + if len(cards) != len(ids): + raise ValidationError('One or more cards are unavailable in this project.') + if not isinstance(expected_revisions, dict): + raise ValidationError('Expected revisions are required for every card.') + conflicts = [{'id': identifier, 'expected': expected_revisions.get(identifier), 'current': cards[identifier].revision} + for identifier in ids if expected_revisions.get(identifier) != cards[identifier].revision] + if conflicts: + raise ValidationError({'revision_conflicts': conflicts}) + column = None + if 'column_id' in changes: + try: + column = Column.objects.get(pk=UUID(str(changes['column_id'])), board=project.board, archived=False) + except (Column.DoesNotExist, ValueError, TypeError): + raise ValidationError('Column is not available in this project.') + assignee = None + if 'assignee_id' in changes and changes['assignee_id'] is not None: + try: + assignee = user.__class__.objects.get(pk=changes['assignee_id']) + except (user.__class__.DoesNotExist, ValueError, TypeError): + raise ValidationError('Invalid assignee.') + if assignee.pk != project.owner_id and not Membership.objects.filter(project=project, user=assignee).exists(): + raise ValidationError('Assignee must have access to this project.') + tags = None + if 'tag_ids' in changes: + tag_ids = changes['tag_ids'] + if not isinstance(tag_ids, list) or any(type(value) is not int for value in tag_ids) or len(tag_ids) != len(set(tag_ids)): + raise ValidationError('Tag IDs must be a unique list.') + tags = list(Tag.objects.filter(project=project, pk__in=tag_ids)) + if len(tags) != len(tag_ids): + raise ValidationError('Tags must belong to this project.') + results = [] + for identifier in ids: + card = cards[identifier] + before = {'column_id': str(card.column_id), 'priority': card.priority, 'assignee_id': card.assignee_id, + 'tag_ids': sorted(card.tags.values_list('pk', flat=True))} + after = dict(before) + if column is not None: after['column_id'] = str(column.pk) + if 'priority' in changes: after['priority'] = changes['priority'] + if 'assignee_id' in changes: after['assignee_id'] = assignee.pk if assignee else None + if tags is not None: after['tag_ids'] = sorted(tag.pk for tag in tags) + delta = {field: {'from': before[field], 'to': after[field]} for field in changes if field in before and before[field] != after[field]} + results.append({'id': identifier, 'title': card.title, 'revision': card.revision + bool(delta), 'changes': delta, 'changed': bool(delta)}) + if not dry_run: + for result in results: + if not result['changed']: + continue + card = cards[result['id']] + delta = result['changes'] + if 'column_id' in delta: + move_card(user, card, column, origin=origin, record_revision=False) + card.refresh_from_db() + if 'priority' in delta: card.priority = changes['priority'] + if 'assignee_id' in delta: card.assignee = assignee + if 'tag_ids' in delta: card.tags.set(tags) + card.revision += 1 + card.full_clean() + card.save() + CardRevision.objects.create(card=card, revision=card.revision, markdown=card.description_markdown, actor=user) + Activity.objects.create(project=project, card=card, actor=user, action='card.bulk_updated', detail={'changes': delta}, origin=origin) + response = {'dry_run': dry_run, 'total': len(ids), 'changed_count': sum(item['changed'] for item in results), + 'unchanged_count': sum(not item['changed'] for item in results), 'items': results} + if idempotency_key and not dry_run: + BulkUpdateKey.objects.create(user=user, key=idempotency_key, payload_hash=payload_hash, result=response) + return response diff --git a/projects/static/projects/attachments.js b/projects/static/projects/attachments.js new file mode 100644 index 0000000..21ce7f0 --- /dev/null +++ b/projects/static/projects/attachments.js @@ -0,0 +1,44 @@ +(() => { + for (const form of document.querySelectorAll('[data-attachment-upload]')) { + if (form.dataset.ready) continue; + form.dataset.ready = '1'; + const input = form.querySelector('input[type="file"]'); + const progress = form.querySelector('progress'); + const status = form.querySelector('[role="status"]'); + const button = form.querySelector('button[type="submit"], button:not([type])'); + form.addEventListener('dragover', event => { event.preventDefault(); form.classList.add('border', 'border-primary'); }); + form.addEventListener('dragleave', () => form.classList.remove('border', 'border-primary')); + form.addEventListener('drop', event => { + event.preventDefault(); + form.classList.remove('border', 'border-primary'); + if (event.dataTransfer?.files?.length) { + input.files = event.dataTransfer.files; + status.textContent = `${input.files.length} file(s) selected.`; + } + }); + form.addEventListener('submit', event => { + if (!input.files.length) return; + event.preventDefault(); + const request = new XMLHttpRequest(); + button.disabled = true; + progress.hidden = false; + progress.value = 0; + status.textContent = 'Uploading…'; + request.open('POST', form.action); + request.upload.onprogress = update => { + if (update.lengthComputable) progress.value = Math.round(update.loaded / update.total * 100); + }; + request.onload = () => { + button.disabled = false; + if (request.status >= 200 && request.status < 400) { + status.textContent = 'Upload complete.'; + window.location.reload(); + } else { + status.textContent = request.responseText || 'Upload failed. Please try again.'; + } + }; + request.onerror = () => { button.disabled = false; status.textContent = 'Connection lost. Please retry.'; }; + request.send(new FormData(form)); + }); + } +})(); diff --git a/projects/templates/projects/_attachment_list.html b/projects/templates/projects/_attachment_list.html new file mode 100644 index 0000000..e52a906 --- /dev/null +++ b/projects/templates/projects/_attachment_list.html @@ -0,0 +1,8 @@ +{% if files %}{% else %}

No files attached.

{% endif %} diff --git a/projects/templates/projects/_board.html b/projects/templates/projects/_board.html index 1dab2bd..4e51de3 100644 --- a/projects/templates/projects/_board.html +++ b/projects/templates/projects/_board.html @@ -15,6 +15,7 @@ {% for card in column.visible_cards %}
+ {% if can_edit and not show_archived %}{% endif %} {{ card.title }}
{{ card.get_priority_display }} {{ card.get_card_type_display }}{% if card.is_blocked %}Blocked{% endif %}
{% if can_edit %}
diff --git a/projects/templates/projects/board.html b/projects/templates/projects/board.html index 763610d..58ffd53 100644 --- a/projects/templates/projects/board.html +++ b/projects/templates/projects/board.html @@ -17,6 +17,7 @@
Searching… +{% if can_edit and not show_archived %}
0 cards selected
{% endif %}
{% include 'projects/_board.html' %}
{% if can_edit %}Add column Add tag{% endif %} @@ -39,6 +40,16 @@ function wireBoard() { }}); } 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); {% csrf_token %} {% endif %} diff --git a/projects/templates/projects/bulk_edit.html b/projects/templates/projects/bulk_edit.html new file mode 100644 index 0000000..d17687e --- /dev/null +++ b/projects/templates/projects/bulk_edit.html @@ -0,0 +1,26 @@ +{% extends 'core/base.html' %} +{% block content %} +← Back to {{ project.name }} +

Bulk edit {{ cards|length }} card{{ cards|length|pluralize }}

+

Choose the fields to change. Preview shows each card's exact changes before you apply them.

+
Selected cards
    {% for card in cards %}
  • {{ card.title }} · revision {{ card.revision }}
  • {% endfor %}
+{% if error %}{% endif %} +{% if applied %}
Updated {{ applied.changed_count }} card{{ applied.changed_count|pluralize }}. {{ applied.unchanged_count }} were already up to date. Return to board
{% else %} +
+ {% csrf_token %} + {% for card in cards %}{% endfor %} + + +
+
+
+
+
Hold Ctrl or Command to select several; leave empty to clear tags.
+
+ + {% if preview and not applied %}{% endif %} +
+{% if preview %}

Preview: {{ preview.changed_count }} changed, {{ preview.unchanged_count }} unchanged

+
    {% for item in preview.items %}
  • {{ item.title }} (revision {{ item.revision }}){% if item.changed %}
      {% for field, delta in item.changes.items %}
    • {{ field }}: {{ delta.from }} → {{ delta.to }}
    • {% endfor %}
    {% else %} — unchanged{% endif %}
  • {% endfor %}
{% endif %} +{% endif %} +{% endblock %} diff --git a/projects/templates/projects/card.html b/projects/templates/projects/card.html index 3701a4f..b7463a8 100644 --- a/projects/templates/projects/card.html +++ b/projects/templates/projects/card.html @@ -1,12 +1,18 @@ -{% extends 'core/base.html' %}{% load project_markdown %} +{% extends 'core/base.html' %}{% load project_markdown static %} {% block content %} ← {{ card.project.name }}

{{ card.title }}

{% if can_edit %}
Edit {% if card.archived %}
{% csrf_token %}
{% else %}
{% csrf_token %}
{% endif %}
{% endif %}

{{ card.get_priority_display }} {{ card.column.name }} · {{ card.get_card_type_display }} · Revision {{ card.revision }}

{{ card.description_markdown|safe_markdown }}
Raw Markdown
{{ card.description_markdown }}
+

Card files

+{% include 'projects/_attachment_list.html' with files=card_files %} +{% if can_edit %}
{% csrf_token %}
{% endif %}

Progress notes

-{% for comment in card.comments.all %}
{{ comment.author }} · {{ comment.created_at }}

{{ comment.body|linebreaksbr }}

{% endfor %} +{% for comment in comments %}
{{ comment.author }} · {{ comment.created_at }}

{{ comment.body|linebreaksbr }}

Files on this progress note

+{% include 'projects/_attachment_list.html' with files=comment.attachments.all %} +{% if can_edit %}
{% csrf_token %}
{% endif %}
{% endfor %} {% if can_edit %}
{% csrf_token %}
{% endif %}

History

    {% for event in card.activity.all %}
  • {{ event.created_at }} · {{ event.action }} by {{ event.actor }}
  • {% endfor %}
+ {% endblock %} diff --git a/projects/test_attachments.py b/projects/test_attachments.py new file mode 100644 index 0000000..e1323f3 --- /dev/null +++ b/projects/test_attachments.py @@ -0,0 +1,112 @@ +import base64 +import hashlib +import tempfile +from pathlib import Path +from unittest.mock import patch + +from asgiref.sync import async_to_sync +from mcp.server.mcpserver.exceptions import ToolError +from django.contrib.auth import get_user_model +from django.core.exceptions import ValidationError +from django.core.files.uploadedfile import SimpleUploadedFile +from django.test import TestCase, override_settings +from django.urls import reverse + +from . import attachments +from .models import CardAttachment, CardComment, Membership +from .services import create_card, create_project + + +class AttachmentTests(TestCase): + def setUp(self): + self.temp = tempfile.TemporaryDirectory() + self.addCleanup(self.temp.cleanup) + self.settings = override_settings(MEDIA_ROOT=self.temp.name) + self.settings.enable() + self.addCleanup(self.settings.disable) + users = get_user_model() + self.owner = users.objects.create_user('attachment-owner') + self.viewer = users.objects.create_user('attachment-viewer') + self.stranger = users.objects.create_user('attachment-stranger') + self.project = create_project(self.owner, name='Attachment board') + self.card = create_card(self.owner, self.project, title='Files') + self.note = CardComment.objects.create(card=self.card, author=self.owner, body='Review these') + + def test_card_and_note_upload_download_and_permissions(self): + self.client.force_login(self.owner) + url = reverse('projects:attachment_upload', args=[self.card.pk]) + response = self.client.post(url, {'files': [SimpleUploadedFile(f'{n}.txt', f'content {n}'.encode()) for n in range(3)]}) + self.assertEqual(response.status_code, 302) + response = self.client.post(url, {'comment_id': self.note.pk, 'files': [SimpleUploadedFile(f'note{n}.md', b'# note') for n in range(2)]}) + self.assertEqual(response.status_code, 302) + self.assertEqual(self.card.attachments.filter(comment__isnull=True).count(), 3) + self.assertEqual(self.note.attachments.count(), 2) + item = self.note.attachments.first() + page = self.client.get(reverse('projects:card', args=[self.card.pk])) + self.assertContains(page, 'Card files') + self.assertContains(page, 'Files on this progress note') + self.assertContains(page, item.title) + self.assertEqual(item.sha256, hashlib.sha256(b'# note').hexdigest()) + download = reverse('projects:attachment_download', args=[item.pk]) + self.assertEqual(b''.join(self.client.get(download).streaming_content), b'# note') + self.assertIn('attachment', self.client.get(download)['Content-Disposition']) + preview = self.client.get(reverse('projects:attachment_preview', args=[item.pk])) + self.assertEqual(preview.content, b'# note') + self.assertIn('sandbox', preview['Content-Security-Policy']) + self.client.force_login(self.stranger) + self.assertEqual(self.client.get(download).status_code, 404) + self.assertEqual(self.client.post(reverse('projects:attachment_delete', args=[item.pk])).status_code, 404) + Membership.objects.create(project=self.project, user=self.viewer, role='viewer') + self.client.force_login(self.viewer) + self.assertEqual(self.client.get(download).status_code, 200) + self.assertEqual(self.client.post(reverse('projects:attachment_delete', args=[item.pk])).status_code, 403) + + def test_validation_and_cleanup(self): + for name, data in [('evil.svg', b''), ('bad.png', b'not-png'), ('bad.txt', b'\x00')]: + with self.assertRaises(ValidationError): + attachments.upload_attachment(self.owner, self.card, filename=name, data=data) + with self.assertRaises(ValidationError): + attachments.upload_attachment(self.owner, self.card, filename='safe.txt', data=b'hello', comment_id=999) + item = attachments.upload_attachment(self.owner, self.card, filename='safe.txt', data=b'hello', comment_id=self.note.pk) + path = Path(item.file.path) + self.assertTrue(path.exists()) + self.note.delete() + self.assertFalse(CardAttachment.objects.filter(pk=item.pk).exists()) + self.assertFalse(path.exists()) + + def test_batch_upload_rolls_back_on_invalid_file(self): + self.client.force_login(self.owner) + response = self.client.post(reverse('projects:attachment_upload', args=[self.card.pk]), { + 'files': [SimpleUploadedFile('good.txt', b'valid'), SimpleUploadedFile('bad.svg', b'')] + }) + self.assertEqual(response.status_code, 400) + self.assertFalse(self.card.attachments.exists()) + self.assertFalse(list(Path(self.temp.name).rglob('*.*'))) + + def test_source_snapshot_metadata_and_size_limits(self): + data = b'function jump() { return true; }\n' + item = attachments.upload_attachment(self.owner, self.card, filename='companion.js', data=data, + comment_id=self.note.pk, source='mcp', source_path='dashboard/static/dashboard/companion.js', source_commit='a' * 40) + self.assertEqual(item.sha256, hashlib.sha256(data).hexdigest()) + self.assertEqual(base64.b64encode(item.file.read()).decode(), base64.b64encode(data).decode()) + with override_settings(PROJECTS_ATTACHMENT_MAX_BYTES=3): + with self.assertRaises(ValidationError): + attachments.upload_attachment(self.owner, self.card, filename='large.txt', data=b'four') + + def test_mcp_upload_fetch_and_card_isolation(self): + from mcp_server.server import create_server + server = create_server() + payload = b'function jump() { return true; }\n' + with patch('mcp_server.server._actor', return_value=self.owner): + uploaded = async_to_sync(server.call_tool)('attachments_upload', { + 'card_id': str(self.card.pk), 'filename': 'companion.js', + 'content_base64': base64.b64encode(payload).decode(), 'comment_id': self.note.pk, + 'source_path': 'dashboard/static/dashboard/companion.js', 'source_commit': 'b' * 40, + }).structured_content + self.assertEqual(uploaded['sha256'], hashlib.sha256(payload).hexdigest()) + fetched = async_to_sync(server.call_tool)('attachments_fetch', {'attachment_id': uploaded['id']}).structured_content + self.assertEqual(base64.b64decode(fetched['content_base64']), payload) + self.assertEqual(fetched['text'], payload.decode()) + with patch('mcp_server.server._actor', return_value=self.stranger): + with self.assertRaises(ToolError): + async_to_sync(server.call_tool)('attachments_fetch', {'attachment_id': uploaded['id']}) diff --git a/projects/tests.py b/projects/tests.py index 1e8c14d..9f27eec 100644 --- a/projects/tests.py +++ b/projects/tests.py @@ -4,10 +4,11 @@ from django.core.exceptions import ValidationError from django.urls import reverse from django.http import HttpResponse from django.utils import timezone -from .models import Card, CardRevision, Membership, Profile +from unittest.mock import patch +from .models import Activity, Card, CardRevision, Membership, Profile from .forms import ProfileForm from .middleware import ProfileTimezoneMiddleware -from .services import RevisionConflict, 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, update_card, update_column class ProjectWorkflowTests(TestCase): @@ -134,3 +135,73 @@ class ProjectWorkflowTests(TestCase): self.assertNotContains(response, 'New card') response = self.client.post(reverse('projects:card_move', args=[card.pk]), {'column_id': str(card.column_id)}) self.assertEqual(response.status_code, 403) + + def test_bulk_preview_apply_and_idempotent_retry_for_twenty_cards(self): + cards = [create_card(self.owner, self.project, title=f'Card {number}') for number in range(21)] + ids = [str(card.pk) for card in cards] + revisions = {identifier: 1 for identifier in ids} + done = self.project.board.columns.get(is_done=True) + changes = {'column_id': str(done.pk), 'priority': 'high'} + preview = bulk_update_cards(self.owner, self.project, ids, revisions, changes, dry_run=True) + self.assertEqual(preview['changed_count'], 21) + self.assertEqual(CardRevision.objects.filter(card__in=cards).count(), 21) + result = bulk_update_cards(self.owner, self.project, ids, revisions, changes, idempotency_key='bulk-21') + self.assertEqual(result['changed_count'], 21) + self.assertEqual(Card.objects.filter(pk__in=ids, column=done, priority='high', revision=2).count(), 21) + self.assertEqual(CardRevision.objects.filter(card__in=cards).count(), 42) + self.assertEqual(Activity.objects.filter(card__in=cards, action='card.bulk_updated').count(), 21) + self.assertEqual(bulk_update_cards(self.owner, self.project, ids, revisions, changes, idempotency_key='bulk-21'), result) + self.assertEqual(Activity.objects.filter(card__in=cards, action='card.bulk_updated').count(), 21) + + def test_bulk_rejects_duplicates_conflicts_cross_project_and_invalid_field(self): + first = create_card(self.owner, self.project, title='First') + second = create_card(self.owner, self.project, title='Second') + another = create_project(self.owner, name='Other board') + foreign = create_card(self.owner, another, title='Foreign') + ids = [str(first.pk), str(second.pk)] + revisions = {identifier: 1 for identifier in ids} + with self.assertRaises(ValidationError): + bulk_update_cards(self.owner, self.project, ids + ids[:1], revisions, {'priority': 'high'}) + with self.assertRaises(ValidationError): + bulk_update_cards(self.owner, self.project, ids, {ids[0]: 0, ids[1]: 1}, {'priority': 'high'}) + with self.assertRaises(ValidationError): + bulk_update_cards(self.owner, self.project, ids + [str(foreign.pk)], revisions, {'priority': 'high'}) + with self.assertRaises(ValidationError): + bulk_update_cards(self.owner, self.project, ids, revisions, {'priority': 'high', 'tag_ids': [9999]}) + self.assertEqual(Card.objects.filter(pk__in=ids, priority='medium').count(), 2) + + def test_bulk_web_preview_and_apply(self): + card = create_card(self.owner, self.project, title='For bulk edit') + self.client.force_login(self.owner) + url = reverse('projects:cards_bulk_edit', args=[self.project.pk]) + self.assertContains(self.client.get(url, {'card': str(card.pk)}), 'For bulk edit') + data = {'card': [str(card.pk)], 'expected_revisions': __import__('json').dumps({str(card.pk): 1}), + 'change_priority': '1', 'priority': 'high', 'action': 'preview'} + response = self.client.post(url, data) + self.assertContains(response, 'Apply changes to 1 card') + card.refresh_from_db(); self.assertEqual(card.priority, 'medium') + data.update({'action': 'apply', 'preview_token': response.context['preview_token'], 'idempotency_key': 'web-bulk-1'}) + self.assertContains(self.client.post(url, data), 'Updated 1 card') + card.refresh_from_db(); self.assertEqual(card.priority, 'high') + + def test_bulk_rolls_back_if_a_write_fails(self): + cards = [create_card(self.owner, self.project, title=title) for title in ('A', 'B')] + ids = [str(card.pk) for card in cards] + revisions = {identifier: 1 for identifier in ids} + original = Activity.objects.create + calls = 0 + + def fail_on_second_bulk_activity(*args, **kwargs): + nonlocal calls + if kwargs.get('action') == 'card.bulk_updated': + calls += 1 + if calls == 2: + raise RuntimeError('Simulated activity storage failure') + return original(*args, **kwargs) + + with patch.object(Activity.objects, 'create', side_effect=fail_on_second_bulk_activity): + with self.assertRaises(RuntimeError): + bulk_update_cards(self.owner, self.project, ids, revisions, {'priority': 'high'}, idempotency_key='rollback-check') + self.assertEqual(Card.objects.filter(pk__in=ids, priority='medium', revision=1).count(), 2) + self.assertEqual(CardRevision.objects.filter(card__in=cards).count(), 2) + self.assertEqual(Activity.objects.filter(card__in=cards, action='card.bulk_updated').count(), 0) diff --git a/projects/urls.py b/projects/urls.py index d894ea5..5cb579f 100644 --- a/projects/urls.py +++ b/projects/urls.py @@ -13,6 +13,7 @@ urlpatterns = [ path('/archive/', views.project_archive, name='archive'), path('/restore/', views.project_restore, name='restore'), path('/cards/new/', views.card_create, name='card_create'), + path('/cards/bulk-edit/', views.cards_bulk_edit, name='cards_bulk_edit'), path('/columns/new/', views.column_create, name='column_create'), path('/tags/new/', views.tag_create, name='tag_create'), path('/columns/reorder/', views.column_reorder, name='column_reorder'), @@ -24,6 +25,11 @@ urlpatterns = [ path('cards//edit/', views.card_edit, name='card_edit'), path('cards//move/', views.card_move, name='card_move'), path('cards//comment/', views.card_comment, name='card_comment'), + path('cards//attachments/', views.attachment_upload, name='attachment_upload'), + path('attachments//download/', views.attachment_download, name='attachment_download'), + path('attachments//preview/', views.attachment_preview, name='attachment_preview'), + path('attachments//delete/', views.attachment_delete, name='attachment_delete'), + path('attachments//update/', views.attachment_update, name='attachment_update'), path('cards//archive/', views.card_archive, name='card_archive'), path('cards//restore/', views.card_restore, name='card_restore'), ] diff --git a/projects/views.py b/projects/views.py index bd27f16..455bc3e 100644 --- a/projects/views.py +++ b/projects/views.py @@ -2,11 +2,15 @@ from django.contrib.auth.decorators import login_required from django.contrib.auth import get_user_model from django.contrib.auth.views import LoginView from django.core.cache import cache -from django.http import HttpResponse +from django.core import signing +from django.http import HttpResponse, FileResponse import hashlib +import json +import uuid from urllib.parse import urlsplit from django.core.exceptions import ValidationError from django.db.models import Q, Count +from django.db import transaction from django.core.paginator import Paginator from django.http import HttpResponseBadRequest, JsonResponse from django.shortcuts import get_object_or_404, redirect, render @@ -15,8 +19,9 @@ 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, Column, Profile, Membership, Tag +from .models import Activity, Card, CardComment, CardAttachment, Column, Profile, Membership, Tag from . import services +from . import attachments from .templatetags.project_markdown import safe_markdown @@ -128,6 +133,54 @@ def board(request, project_id): return render(request, template, context) +@login_required +def cards_bulk_edit(request, project_id): + project = services.project_for(request.user, project_id, write=True) + ids = request.GET.getlist('card') if request.method == 'GET' else request.POST.getlist('card') + if not 1 <= len(ids) <= 100 or len(set(ids)) != len(ids): + return HttpResponseBadRequest('Select between 1 and 100 unique cards.') + try: + cards = list(Card.objects.filter(project=project, archived=False, pk__in=ids).select_related('column')) + except (ValueError, ValidationError): + return HttpResponseBadRequest('Invalid card selection.') + if len(cards) != len(ids): + return HttpResponseBadRequest('One or more selected cards are unavailable.') + by_id = {str(card.pk): card for card in cards} + cards = [by_id[identifier] for identifier in ids] + context = {'project': project, 'cards': cards, 'columns': project.board.columns.filter(archived=False), + 'assignable': get_user_model().objects.filter(pk__in=[project.owner_id, *project.memberships.values_list('user_id', flat=True)]).order_by('username'), + 'tags': Tag.objects.filter(project=project).order_by('name'), 'selected_tag_ids': request.POST.getlist('tag_ids'), + 'revisions_json': request.POST.get('expected_revisions', ''), 'idempotency_key': request.POST.get('idempotency_key', ''), + 'title': 'Bulk edit cards', 'section': 'projects'} + if request.method == 'POST': + try: + revisions = json.loads(request.POST['expected_revisions']) + changes = {} + for field in ('column_id', 'priority', 'assignee_id', 'tag_ids'): + if request.POST.get('change_' + field): + if field == 'tag_ids': changes[field] = [int(value) for value in request.POST.getlist('tag_ids')] + elif field == 'assignee_id': changes[field] = int(request.POST[field]) if request.POST.get(field) else None + else: changes[field] = request.POST[field] + context.update({'revisions_json': json.dumps(revisions), 'changes_json': json.dumps(changes), 'idempotency_key': request.POST.get('idempotency_key') or str(uuid.uuid4())}) + confirmation = {'user': request.user.pk, 'project': str(project.pk), 'ids': ids, 'revisions': revisions, 'changes': changes} + if request.POST.get('action') == 'apply': + try: + submitted = signing.loads(request.POST['preview_token'], salt='card-bulk-preview', max_age=1800) + except (signing.BadSignature, signing.SignatureExpired): + raise ValidationError('Preview expired or changed. Preview again.') + if submitted != confirmation: + raise ValidationError('Selection or changes differ from the preview. Preview again.') + context['applied'] = services.bulk_update_cards(request.user, project, ids, revisions, changes, idempotency_key=request.POST['idempotency_key']) + else: + context['preview'] = services.bulk_update_cards(request.user, project, ids, revisions, changes, dry_run=True) + context['preview_token'] = signing.dumps(confirmation, salt='card-bulk-preview') + except (KeyError, ValueError, TypeError, ValidationError) as exc: + context['error'] = str(exc) + else: + context['revisions_json'] = json.dumps({str(card.pk): card.revision for card in cards}) + return render(request, 'projects/bulk_edit.html', context) + + @login_required def card_create(request, project_id): project = services.project_for(request.user, project_id, write=True) @@ -146,7 +199,86 @@ 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'}) + return render(request, 'projects/card.html', {'card': card, 'can_edit': can_edit, 'title': card.title, 'section': 'projects', + '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 attachment_upload(request, card_id): + card = services.card_for(request.user, card_id, write=True) + files = request.FILES.getlist('files') + if not files: + return HttpResponseBadRequest('Select one or more files.') + if len(files) > 10: + return HttpResponseBadRequest('Upload at most 10 files at once.') + comment_id = request.POST.get('comment_id') or None + created = [] + try: + with transaction.atomic(): + for file in files: + if file.size > settings.PROJECTS_ATTACHMENT_MAX_BYTES: + raise ValidationError('File exceeds the per-file size limit.') + created.append(attachments.upload_attachment(request.user, card, filename=file.name, data=file.read(), + comment_id=comment_id, title=request.POST.get('title', ''), description=request.POST.get('description', ''))) + except Exception as exc: + for item in created: + item.file.delete(save=False) + if isinstance(exc, ValidationError): + return HttpResponseBadRequest('; '.join(exc.messages)) + raise + return redirect('projects:card', card_id=card.pk) + + +@login_required +def attachment_download(request, attachment_id): + item = get_object_or_404(CardAttachment.objects.select_related('card'), pk=attachment_id) + services.card_for(request.user, item.card_id) + response = FileResponse(item.file.open('rb'), as_attachment=True, filename=item.original_filename, + content_type='application/octet-stream') + response['X-Content-Type-Options'] = 'nosniff' + response['Cache-Control'] = 'private, no-store' + return response + + +@login_required +def attachment_preview(request, attachment_id): + item = get_object_or_404(CardAttachment.objects.select_related('card'), pk=attachment_id) + services.card_for(request.user, item.card_id) + if item.mime_type not in {'image/png', 'image/jpeg', 'image/webp', 'text/plain'} or item.byte_size > 1024 * 1024: + return HttpResponseBadRequest('Preview unavailable for this file.') + if item.mime_type == 'text/plain': + with item.file.open('rb') as stream: + response = HttpResponse(stream.read(1024 * 1024).decode('utf-8'), content_type='text/plain; charset=utf-8') + else: + response = FileResponse(item.file.open('rb'), content_type=item.mime_type) + response['X-Content-Type-Options'] = 'nosniff' + response['Content-Security-Policy'] = "default-src 'none'; sandbox" + response['Cache-Control'] = 'private, no-store' + return response + + +@login_required +@require_POST +def attachment_delete(request, attachment_id): + item = get_object_or_404(CardAttachment.objects.select_related('card__project'), pk=attachment_id) + services.card_for(request.user, item.card_id, write=True) + attachments.delete_attachment(request.user, item) + return redirect('projects:card', card_id=item.card_id) + + +@login_required +@require_POST +def attachment_update(request, attachment_id): + item = get_object_or_404(CardAttachment.objects.select_related('card'), pk=attachment_id) + services.card_for(request.user, item.card_id, write=True) + title = request.POST.get('title', '').strip() + if not title or len(title) > 255: + return HttpResponseBadRequest('Title must be between 1 and 255 characters.') + item.title = title + item.save(update_fields=['title']) + return redirect('projects:card', card_id=item.card_id) @login_required