latest changes

This commit is contained in:
Joren de Graaf
2026-10-20 14:17:46 +02:00
parent dd1ee39afa
commit 03d7afc6a1
28 changed files with 1929 additions and 15 deletions
+1
View File
@@ -5,5 +5,6 @@ dist/
*.pyc
__pycache__/
db.sqlite3
private_media/
.DS_Store
.playwright-mcp/
+3 -1
View File
@@ -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.
+5
View File
@@ -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 = {
@@ -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); }
})();
+11
View File
@@ -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}}
+578
View File
@@ -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; }
})();
+3 -3
View File
@@ -1,6 +1,6 @@
{% extends 'core/base.html' %}{% load static %}{% block content %}<link rel="stylesheet" href="{% static 'dashboard/builder.css' %}"><link rel="stylesheet" href="{% static 'dashboard/open_meteo.css' %}"><link rel="stylesheet" href="{% static 'dashboard/buienradar.css' %}">
{% extends 'core/base.html' %}{% load static %}{% block content %}<link rel="stylesheet" href="{% static 'dashboard/builder.css' %}"><link rel="stylesheet" href="{% static 'dashboard/open_meteo.css' %}"><link rel="stylesheet" href="{% static 'dashboard/buienradar.css' %}"><link rel="stylesheet" href="{% static 'dashboard/companion.css' %}">
<div class="page-heading dashboard-heading"><div><div class="eyebrow"><span class="eyebrow-line"></span> YOUR WORKSPACE</div><h1>{{ title }}<span class="heading-period">.</span></h1><p>Make this space your own with a few useful widgets.</p></div><div class="dashboard-actions"><button class="button secondary" id="catalogue-toggle" type="button" aria-controls="widget-catalogue" aria-expanded="false" aria-label="Open widget catalogue"><i class="bi bi-gear"></i> Widgets</button><button class="button secondary" id="reset-layout" type="button" hidden>Reset</button><button class="button primary" id="edit-layout" type="button">Edit layout</button></div></div>
<div id="layout-status" class="layout-status" role="status" aria-live="polite">Layout saved</div>
<div id="layout-status" class="layout-status" role="status" aria-live="polite">Layout saved</div><button class="button secondary" id="companion-toggle" type="button" aria-pressed="false">Show companion</button>
<div class="dashboard-pages" aria-label="Dashboard pages"><a href="{% url 'dashboard:index' %}" {% if dashboard_page == 'overview' %}aria-current="page"{% endif %}>Overview</a><a href="{% url 'dashboard:page' 'personal' %}" {% if dashboard_page == 'personal' %}aria-current="page"{% endif %}>Personal</a></div>
<div id="widget-grid" class="widget-grid" data-page="{{ dashboard_page }}" data-revision="{{ layout.revision }}" data-save-url="{% url 'dashboard:layout' dashboard_page %}">
{% for instance in instances %}{% include 'dashboard/widget_card.html' %}{% endfor %}
@@ -10,5 +10,5 @@
<template id="buienradar-widget-template">{% include 'dashboard/widgets/buienradar.html' %}</template>
<aside id="widget-catalogue" class="widget-catalogue" aria-label="Widget catalogue" aria-hidden="true" inert><div class="catalogue-head"><div><span class="eyebrow">BUILD YOUR PAGE</span><h2>Widgets</h2></div><button type="button" id="catalogue-close" class="button ghost" aria-label="Close widget catalogue"><i class="bi bi-x-lg"></i></button></div><label for="widget-search">Search widgets</label><input id="widget-search" type="search" placeholder="Search by name or description"><div class="catalogue-list">{% for widget in catalogue %}<div class="catalogue-entry" draggable="true" data-widget-type="{{ widget.id }}" data-title="{{ widget.title|lower }}" data-description="{{ widget.description|lower }}"><i class="bi {{ widget.icon }}" aria-hidden="true"></i><div><strong>{{ widget.title }}</strong><small>{{ widget.description }}</small></div><button type="button" class="button secondary" data-add="{{ widget.id }}">Add</button></div>{% endfor %}</div><p class="catalogue-hint">Drag onto a dashed slot, or use Add and the Move controls. Changes save when you select Done.</p></aside><div id="catalogue-backdrop" class="catalogue-backdrop" hidden></div>
{{ catalogue|length|json_script:"widget-count" }}
<script src="{% static 'dashboard/location.js' %}" defer></script><script src="{% static 'dashboard/open_meteo.js' %}" defer></script><script src="{% static 'dashboard/buienradar.js' %}" defer></script><script src="{% static 'dashboard/builder.js' %}" defer></script>
<script src="{% static 'dashboard/location.js' %}" defer></script><script src="{% static 'dashboard/open_meteo.js' %}" defer></script><script src="{% static 'dashboard/buienradar.js' %}" defer></script><script src="{% static 'dashboard/builder.js' %}" defer></script><script src="{% static 'dashboard/companion.js' %}" defer></script><script src="{% static 'dashboard/companion-dashboard.js' %}" defer></script>
{% endblock %}
+305
View File
@@ -0,0 +1,305 @@
<!doctype html>
<html lang="en"><meta charset="utf-8"><title>Companion movement checks</title>
<body><pre id="results">Running…</pre>
<script src="../static/dashboard/companion.js?test=followup-4"></script>
<script>
(() => {
const movement = window.BrowserCompanionMovement;
const config = movement.configure();
const results = [];
function check(label, value) { results.push({ label, passed: !!value }); }
function scenario(specification) {
const host = document.createElement('div'); document.body.append(host);
const entries = specification.map(([x, y, width, height, border = '1px solid black', edge = 'top']) => {
const element = document.createElement('div');
element.style.cssText = `position:absolute;left:${x}px;top:${y}px;width:${width}px;height:${height}px;border:${border}`;
host.append(element); return { element, edge };
});
const geometry = movement.discover(entries, document.body, config);
const graph = movement.graphFor(geometry.surfaces, geometry.edges, config);
host.remove(); return { geometry, graph };
}
const short = scenario([[10, 200, 100, 20], [130, 187, 100, 20]]);
check('short jump up', short.graph.get('0:top').some(step => step.to === '1:top' && step.kind === 'jump'));
const long = scenario([[10, 200, 100, 20], [240, 187, 100, 20]]);
check('long jump rejected', long.graph.get('0:top').length === 0);
const tall = scenario([[10, 200, 100, 20], [10, 50, 100, 150]]);
check('tall visible side offers climb', tall.graph.get('0:top').some(step => step.kind === 'climb'));
check('tall side is not jumped', !tall.graph.get('0:top').some(step => step.kind === 'jump'));
{
const host = document.createElement('div'); document.body.append(host);
const make = top => {
const element = document.createElement('div');
element.style.cssText = `position:absolute;left:20px;top:${top}px;width:280px;height:180px;border:1px solid black`;
host.append(element); return element;
};
const upper = make(20), lower = make(216);
const entries = [{ element: upper, edge: 'bottom', explicit: true },
{ element: upper, edge: 'top', explicit: true },
{ element: lower, edge: 'top', explicit: true },
{ element: lower, edge: 'bottom', explicit: true }];
const geometry = movement.discover(entries, document.body, config);
const graph = movement.graphFor(geometry.surfaces, geometry.edges, config);
check('first drop has reachable return climb across grid gap',
graph.get('0:bottom').some(step => step.kind === 'drop' && step.to === '2:top') &&
graph.get('2:top').some(step => step.kind === 'climb' && step.to === '1:top' &&
step.attachRise <= config.maxJumpRiseS * config.bodySize));
host.remove();
}
{
const host = document.createElement('div'); document.body.append(host);
const make = top => {
const element = document.createElement('div');
element.style.cssText = `position:absolute;left:20px;top:${top}px;width:280px;height:180px;border:1px solid black`;
host.append(element); return element;
};
const upper = make(20), lower = make(216);
const entries = [{ element: upper, edge: 'bottom', explicit: true },
{ element: upper, edge: 'top', explicit: true },
{ element: lower, edge: 'top', explicit: true },
{ element: lower, edge: 'bottom', explicit: true }];
const companion = new window.BrowserCompanion({ surfaces: () => entries,
config: { activeMinTransitions: 2, activeMaxTransitions: 2 }, reducedMotion: () => false });
companion.mode = 'active'; companion.activeRemaining = 2;
const originalRandom = Math.random;
Math.random = () => .1;
try {
const finishMotion = () => {
for (let i = 0; i < 7 && companion.motion; i++)
companion.advance(companion.motion.start + companion.motion.duration + 1);
};
companion.choose(100);
finishMotion();
const dropped = companion.state === 'landing' && companion.platform?.element === lower;
companion.tick(companion.deadline + 1); cancelAnimationFrame(companion.frame);
const climbing = !!companion.motion && companion.motion.step?.kind === 'climb';
const beforeShift = companion.position.y;
upper.style.top = '0px'; lower.style.top = '196px';
companion.refresh();
const attachedAfterShift = !!companion.motion && Math.abs(companion.position.y - beforeShift + 20) < 1;
finishMotion();
check('first drop continues into return climb', dropped && climbing &&
attachedAfterShift &&
companion.platform?.element === upper && companion.platform.edge === 'top' &&
companion.activeRemaining === 0);
} finally { Math.random = originalRandom; companion.destroy(); host.remove(); }
}
{
const element = document.createElement('div');
element.style.cssText = 'position:absolute;left:10px;top:50px;width:100px;height:150px;border:1px solid black';
document.body.append(element);
const geometry = movement.discover([{ element, edge: 'bottom' }, { element, edge: 'top' }], document.body, config);
const graph = movement.graphFor(geometry.surfaces, geometry.edges, config);
check('radar bottom can climb to its top', graph.get('0:bottom').some(step =>
step.to === '1:top' && step.kind === 'climb'));
element.remove();
}
const descent = scenario([[10, 50, 100, 20], [10, 80, 100, 20],
[10, 110, 100, 20], [10, 140, 100, 20]]);
const downRoute = movement.routes(descent.graph, '0:top', 16).find(route => route.id === '3:top');
check('descent uses three safe stops', downRoute?.steps.length === 3 && downRoute.steps.every(step => step.kind === 'drop'));
const stranded = scenario([[10, 50, 100, 20], [10, 200, 100, 20]]);
check('unsafe fall has no route', movement.routes(stranded.graph, '0:top', 16).length === 0);
const borderless = scenario([[10, 50, 100, 20], [10, 80, 100, 20, '0']]);
check('invisible border rejected', borderless.geometry.surfaces.length === 1 &&
borderless.geometry.rejected[0]?.reason === 'borderless');
const transparent = scenario([[10, 50, 100, 20, '1px solid rgba(0, 0, 0, 0)']]);
check('transparent border rejected', transparent.geometry.surfaces.length === 0);
check('config is bounded', movement.configure({ maxJumpHorizontalS: 100, bodySize: -1 }).maxJumpHorizontalS === 6 &&
movement.configure({ bodySize: -1 }).bodySize === 8);
const button = document.createElement('button'); button.style.cssText =
'position:absolute;left:10px;top:250px;width:100px;height:25px;border:0';
document.body.append(button);
check('borderless button is not a platform', movement.discover([{ element: button }], document.body, config).surfaces.length === 0);
button.remove();
function climbSequence(hopChance) {
const host = document.createElement('div'); document.body.append(host);
const make = (y, height) => {
const element = document.createElement('div');
element.style.cssText = `position:absolute;left:10px;top:${y}px;width:100px;height:${height}px;border:1px solid black`;
host.append(element); return { element, edge: 'top' };
};
const entries = [make(200, 20), make(50, 150)];
const companion = new window.BrowserCompanion({ surfaces: () => entries,
config: { climbHopChance: hopChance }, reducedMotion: () => false });
const climb = companion.graph.get('0:top').find(step => step.kind === 'climb');
companion.startTransition(climb, companion.surfaces[1], 100);
const sequence = [companion.state];
for (let i = 0; i < 5 && companion.motion; i++) {
companion.advance(companion.motion.start + companion.motion.duration + 1);
sequence.push(companion.state);
}
companion.destroy(); host.remove(); return sequence;
}
const pull = climbSequence(0).join(',');
const hop = climbSequence(1).join(',');
check(`climb pull-up settles without landing (${pull})`, pull ===
'climbing,climbing,pulling-up,idle');
check(`short climb hop reaches landing (${hop})`, hop ===
'climbing,climbing,climb-hopping,landing');
{
const host = document.createElement('div'); document.body.append(host);
const make = (x, y) => {
const element = document.createElement('div');
element.style.cssText = `position:absolute;left:${x}px;top:${y}px;width:100px;height:20px;border:1px solid black`;
host.append(element); return { element, edge: 'top' };
};
const first = make(10, 200), second = make(130, 187);
const companion = new window.BrowserCompanion({ surfaces: () => [first, second],
name: () => 'Pixel', reducedMotion: () => false });
const before = companion.position.y;
first.element.style.top = '180px'; second.element.style.top = '167px';
companion.refresh();
check('position follows moving source element', Math.abs(companion.position.y - before + 20) < 1);
const jump = companion.graph.get('0:top').find(step => step.kind === 'jump');
companion.startTransition(jump, companion.surfaces[1], 100);
second.element.remove(); companion.refresh();
check('removed landing cancels motion safely', companion.motion === null &&
companion.platform?.element === first.element);
companion.setReducedMotion(true);
check('reduced motion stops autonomous state', companion.state === 'idle' && companion.motion === null);
companion.setName('Dahlia');
check('theme name updates without restarting', companion.renderer.label.textContent.startsWith('Dahlia'));
companion.destroy(); host.remove();
}
{
const host = document.createElement('div'); document.body.append(host);
const make = (x, y, height) => {
const element = document.createElement('div');
element.style.cssText = `position:absolute;left:${x}px;top:${y}px;width:100px;height:${height}px;border:1px solid black`;
host.append(element); return { element, edge: 'top' };
};
const entries = [make(10, 220, 20), make(130, 220, 20), make(-100, 70, 150)];
const companion = new window.BrowserCompanion({ surfaces: () => entries, reducedMotion: () => false });
const available = companion.graph.get(companion.platform.id);
companion.mode = 'active'; companion.activeRemaining = 2;
const originalRandom = Math.random;
const values = [.1, .5, .5];
Math.random = () => values.shift() ?? .5;
try {
companion.choose(100);
check(`safe jump gets selected when climb also exists (${available.map(e=>e.kind).join(',')}; selected ${companion.motion?.step?.kind})`, available.some(edge => edge.kind === 'jump') &&
available.some(edge => edge.kind === 'climb') &&
(companion.motion?.step?.kind === 'jump'));
} finally { Math.random = originalRandom; companion.destroy(); host.remove(); }
}
{
const host = document.createElement('div'); document.body.append(host);
const make = x => {
const element = document.createElement('div');
element.style.cssText = `position:absolute;left:${x}px;top:250px;width:100px;height:20px;border:1px solid black`;
host.append(element); return { element, edge: 'top' };
};
const entries = [make(10), make(130)];
const companion = new window.BrowserCompanion({ surfaces: () => entries, reducedMotion: () => false });
companion.mode = 'active'; companion.activeRemaining = 3;
const originalRandom = Math.random;
Math.random = () => .9;
try {
const sequence = [];
companion.choose(1000);
for (let count = 0; count < 3; count++) {
while (companion.motion?.phase === 'approach')
companion.advance(companion.motion.start + companion.motion.duration + 1);
sequence.push(companion.state);
companion.advance(companion.motion.start + companion.motion.duration + 1);
sequence.push(companion.state);
const done = companion.deadline + 1;
companion.tick(done); cancelAnimationFrame(companion.frame);
sequence.push(companion.state);
}
check(`three successive legitimate jumps (${sequence.join(',')})`,
[0, 3, 6].every(index => sequence[index] === 'jumping' &&
sequence[index + 1] === 'landing') && sequence[2] === 'jumping' &&
sequence[5] === 'jumping' && sequence[8] === 'idle');
check('landing exits once and allows another route', companion.trace.filter(event =>
event.reason === 'landing interval complete').length === 3);
} finally { Math.random = originalRandom; companion.destroy(); host.remove(); }
}
{
const host = document.createElement('div'); document.body.append(host);
const element = document.createElement('div');
element.style.cssText = 'position:absolute;left:10px;top:300px;width:120px;height:20px;border:1px solid black';
host.append(element);
const companion = new window.BrowserCompanion({ surfaces: () => [{ element, edge: 'top' }],
reducedMotion: () => false });
companion.beginNext(100);
check('empty route finishes idle', companion.state === 'idle');
companion.choose(200);
if (companion.motion?.phase === 'patrol')
companion.advance(companion.motion.start + companion.motion.duration + 1);
check('grounded walking never lands', companion.state !== 'landing');
const groundedStates = [];
for (const now of [1000, 2000, 3000, 4000, 5000]) {
companion.tick(now); cancelAnimationFrame(companion.frame);
groundedStates.push(companion.state);
}
check('grounded frames do not retrigger landing', !groundedStates.includes('landing'));
companion.destroy(); host.remove();
}
{
const host = document.createElement('div'); document.body.append(host);
const element = document.createElement('div');
element.style.cssText = 'position:absolute;left:10px;top:400px;width:120px;height:20px;border:1px solid black';
host.append(element);
const companion = new window.BrowserCompanion({ surfaces: () => [{ element, edge: 'top' }],
config: { idleMinMs: 12000, idleMaxMs: 12000, sleepMinMs: 20000, sleepMaxMs: 20000 },
reducedMotion: () => false });
const firstIdle = companion.deadline - performance.now();
companion.lastSleepAt = -Infinity; companion.burstsSinceRest = 2;
const originalRandom = Math.random;
Math.random = () => 0;
try {
const afterIdle = companion.deadline + 1;
companion.tick(afterIdle); cancelAnimationFrame(companion.frame);
const slept = companion.state === 'sleeping' && companion.deadline - afterIdle >= 20000;
const afterSleep = companion.deadline + 1;
companion.tick(afterSleep); cancelAnimationFrame(companion.frame);
check('normal idle and sleep dwell without flicker', firstIdle >= 11900 && slept &&
companion.state === 'idle' && companion.deadline - afterSleep >= 12000);
companion.lastSleepAt = companion.deadline;
const afterSecondIdle = companion.deadline + 1;
companion.tick(afterSecondIdle); cancelAnimationFrame(companion.frame);
const emoted = ['purring', 'batting'].includes(companion.state) &&
companion.deadline - afterSecondIdle >= companion.config.emoteMinMs;
const afterEmote = companion.deadline + 1;
companion.tick(afterEmote); cancelAnimationFrame(companion.frame);
check('emote completes into calm idle', emoted && companion.state === 'idle' &&
companion.deadline - afterEmote >= 12000);
} finally { Math.random = originalRandom; companion.destroy(); host.remove(); }
}
{
const host = document.createElement('div'); document.body.append(host);
const entries = [10, 130].map(x => {
const element = document.createElement('div');
element.style.cssText = `position:absolute;left:${x}px;top:550px;width:100px;height:20px;border:1px solid black`;
host.append(element); return { element, edge: 'top' };
});
const originalRandom = Math.random;
let seed = 42;
Math.random = () => ((seed = (seed * 1664525 + 1013904223) >>> 0) / 4294967296);
const companion = new window.BrowserCompanion({ surfaces: () => entries, reducedMotion: () => false });
const events = [];
const originalSetState = companion.setState.bind(companion);
companion.setState = (state, reason, now) => {
if (companion.state !== state) events.push({ state, reason, at: now });
originalSetState(state, reason, now);
};
try {
let now = performance.now(), start = now;
for (let i = 0; i < 500 && now - start < 300000; i++) {
const next = companion.motion ? companion.motion.start + companion.motion.duration + 1 : companion.deadline + 1;
now = Math.max(now + 1, next);
companion.tick(now); cancelAnimationFrame(companion.frame);
}
const states = new Set(events.map(event => event.state));
check('five-minute schedule includes exploration, play and rest', now - start >= 300000 &&
['jumping', 'landing', 'idle', 'purring', 'batting', 'sleeping'].every(state => states.has(state)));
} finally { Math.random = originalRandom; companion.destroy(); host.remove(); }
}
const failed = results.filter(result => !result.passed);
document.getElementById('results').textContent = results.map(result =>
`${result.passed ? 'PASS' : 'FAIL'} ${result.label}`).join('\n');
document.documentElement.dataset.testsPassed = String(failed.length === 0);
})();
</script></body></html>
+23
View File
@@ -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.
+17
View File
@@ -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`.
@@ -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.
+79 -2
View File
@@ -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():
+10
View File
@@ -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')
+102
View File
@@ -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()
+30
View File
@@ -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')],
},
),
]
@@ -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')],
},
),
]
+38
View File
@@ -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')
+102 -2
View File
@@ -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
+44
View File
@@ -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));
});
}
})();
@@ -0,0 +1,8 @@
{% if files %}<ul class="list-unstyled mb-2">
{% for file in files %}<li class="d-flex flex-wrap align-items-center gap-2 border rounded p-2 mb-2">
<a href="{% url 'projects:attachment_download' file.id %}">{{ file.title }}</a>
{% if file.byte_size <= 1048576 and file.mime_type == 'image/png' or file.byte_size <= 1048576 and file.mime_type == 'image/jpeg' or file.byte_size <= 1048576 and file.mime_type == 'image/webp' %}<a href="{% url 'projects:attachment_preview' file.id %}" target="_blank" rel="noopener" aria-label="Preview {{ file.title }}"><img src="{% url 'projects:attachment_preview' file.id %}" alt="" style="max-width:5rem;max-height:5rem;object-fit:contain"></a>{% elif file.mime_type == 'text/plain' and file.byte_size <= 1048576 %}<a href="{% url 'projects:attachment_preview' file.id %}" target="_blank" rel="noopener">Preview text</a>{% endif %}
<small class="text-muted">{{ file.byte_size|filesizeformat }} · {{ file.created_at|date:'SHORT_DATETIME_FORMAT' }}{% if file.uploaded_by %} · {{ file.uploaded_by }}{% endif %}</small>
{% if file.source_path %}<small class="text-muted">Snapshot: {{ file.source_path }}{% if file.source_commit %} @ {{ file.source_commit|slice:':12' }}{% endif %}</small>{% endif %}
{% if can_edit %}<details><summary>Rename</summary><form method="post" action="{% url 'projects:attachment_update' file.id %}">{% csrf_token %}<label for="attachment-title-{{ file.id }}">Display title</label><input id="attachment-title-{{ file.id }}" name="title" maxlength="255" required value="{{ file.title }}"><button type="submit" class="btn btn-outline-secondary btn-sm">Save</button></form></details><form method="post" action="{% url 'projects:attachment_delete' file.id %}" onsubmit="return confirm('Delete this attachment?')">{% csrf_token %}<button type="submit" class="btn btn-outline-danger btn-sm" aria-label="Delete {{ file.title }}">Delete</button></form>{% endif %}
</li>{% endfor %}</ul>{% else %}<p class="text-muted">No files attached.</p>{% endif %}
+1
View File
@@ -15,6 +15,7 @@
{% for card in column.visible_cards %}
<article class="card mb-2" data-move="{% url 'projects:card_move' card.id %}">
<div class="card-body">
{% if can_edit and not show_archived %}<label class="d-block mb-1"><input type="checkbox" class="bulk-card-choice" value="{{ card.id }}" aria-label="Select {{ card.title }} for bulk edit"> Select</label>{% endif %}
<a href="{% url 'projects:card' card.id %}"><strong>{{ card.title }}</strong></a>
<div><span class="badge text-bg-secondary">{{ card.get_priority_display }}</span> <small>{{ card.get_card_type_display }}</small>{% if card.is_blocked %}<span class="badge text-bg-danger">Blocked</span>{% endif %}</div>
{% if can_edit %}<form method="post" action="{% url 'projects:card_move' card.id %}" class="mt-2">
+11
View File
@@ -17,6 +17,7 @@
<div class="col-auto"><a class="btn btn-outline-secondary" href="{% url 'projects:board' project.id %}">Clear</a></div>
</form>
<span id="board-search-loading" class="htmx-indicator" role="status">Searching…</span>
{% if can_edit and not show_archived %}<div class="d-flex align-items-center gap-2 mb-2" id="bulk-toolbar"><span id="bulk-count" role="status" aria-live="polite">0 cards selected</span><button type="button" class="btn btn-outline-primary btn-sm" id="bulk-edit-button" disabled>Bulk edit</button><button type="button" class="btn btn-outline-secondary btn-sm" id="bulk-clear-button">Clear selection</button></div>{% endif %}
<div id="board-results">{% include 'projects/_board.html' %}</div>
{% if can_edit %}<a class="btn btn-outline-secondary mt-3" href="{% url 'projects:column_create' project.id %}">Add column</a>
<a class="btn btn-outline-secondary mt-3" href="{% url 'projects:tag_create' project.id %}">Add tag</a>{% endif %}
@@ -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);
</script>
{% csrf_token %}
{% endif %}
@@ -0,0 +1,26 @@
{% extends 'core/base.html' %}
{% block content %}
<a href="{% url 'projects:board' project.id %}">← Back to {{ project.name }}</a>
<h1 class="mt-2">Bulk edit {{ cards|length }} card{{ cards|length|pluralize }}</h1>
<p>Choose the fields to change. Preview shows each card's exact changes before you apply them.</p>
<details><summary>Selected cards</summary><ul>{% for card in cards %}<li>{{ card.title }} · revision {{ card.revision }}</li>{% endfor %}</ul></details>
{% if error %}<div class="alert alert-danger" role="alert">{{ error }}</div>{% endif %}
{% if applied %}<div class="alert alert-success" role="status">Updated {{ applied.changed_count }} card{{ applied.changed_count|pluralize }}. {{ applied.unchanged_count }} were already up to date. <a href="{% url 'projects:board' project.id %}">Return to board</a></div>{% else %}
<form method="post">
{% csrf_token %}
{% for card in cards %}<input type="hidden" name="card" value="{{ card.id }}">{% endfor %}
<input type="hidden" name="expected_revisions" value="{{ revisions_json }}">
<input type="hidden" name="idempotency_key" value="{{ idempotency_key }}">
<div class="row g-3 mb-3">
<div class="col-md-6"><label><input type="checkbox" name="change_column_id" value="1" {% if request.POST.change_column_id %}checked{% endif %}> Change column</label><select class="form-select" name="column_id" aria-label="New column">{% for column in columns %}<option value="{{ column.id }}" {% if request.POST.column_id == column.id|stringformat:'s' %}selected{% endif %}>{{ column.name }}</option>{% endfor %}</select></div>
<div class="col-md-6"><label><input type="checkbox" name="change_priority" value="1" {% if request.POST.change_priority %}checked{% endif %}> Change priority</label><select class="form-select" name="priority" aria-label="New priority"><option value="low" {% if request.POST.priority == 'low' %}selected{% endif %}>Low</option><option value="medium" {% if request.POST.priority == 'medium' %}selected{% endif %}>Medium</option><option value="high" {% if request.POST.priority == 'high' %}selected{% endif %}>High</option></select></div>
<div class="col-md-6"><label><input type="checkbox" name="change_assignee_id" value="1" {% if request.POST.change_assignee_id %}checked{% endif %}> Change assignee</label><select class="form-select" name="assignee_id" aria-label="New assignee"><option value="">Unassigned</option>{% for person in assignable %}<option value="{{ person.id }}" {% if request.POST.assignee_id == person.id|stringformat:'s' %}selected{% endif %}>{{ person.username }}</option>{% endfor %}</select></div>
<div class="col-md-6"><label><input type="checkbox" name="change_tag_ids" value="1" {% if request.POST.change_tag_ids %}checked{% endif %}> Replace tags</label><select class="form-select" name="tag_ids" multiple size="4" aria-label="New tags">{% for tag in tags %}<option value="{{ tag.id }}" {% if tag.id|stringformat:'s' in selected_tag_ids %}selected{% endif %}>{{ tag.name }}</option>{% endfor %}</select><small>Hold Ctrl or Command to select several; leave empty to clear tags.</small></div>
</div>
<button class="btn btn-outline-primary" type="submit" name="action" value="preview">Preview changes</button>
{% if preview and not applied %}<input type="hidden" name="preview_token" value="{{ preview_token }}"><button class="btn btn-primary" type="submit" name="action" value="apply">Apply changes to {{ preview.changed_count }} card{{ preview.changed_count|pluralize }}</button>{% endif %}
</form>
{% if preview %}<h2 class="h5 mt-4">Preview: {{ preview.changed_count }} changed, {{ preview.unchanged_count }} unchanged</h2>
<ul>{% for item in preview.items %}<li><strong>{{ item.title }}</strong> (revision {{ item.revision }}){% if item.changed %}<ul>{% for field, delta in item.changes.items %}<li>{{ field }}: {{ delta.from }} → {{ delta.to }}</li>{% endfor %}</ul>{% else %} — unchanged{% endif %}</li>{% endfor %}</ul>{% endif %}
{% endif %}
{% endblock %}
+8 -2
View File
@@ -1,12 +1,18 @@
{% extends 'core/base.html' %}{% load project_markdown %}
{% extends 'core/base.html' %}{% load project_markdown static %}
{% block content %}
<a href="{% url 'projects:board' card.project_id %}">← {{ card.project.name }}</a>
<div class="d-flex justify-content-between mt-3"><h1>{{ card.title }}</h1>{% if can_edit %}<div><a class="btn btn-outline-secondary" href="{% url 'projects:card_edit' card.id %}">Edit</a> {% if card.archived %}<form method="post" action="{% url 'projects:card_restore' card.id %}" class="d-inline">{% csrf_token %}<button class="btn btn-outline-success">Restore</button></form>{% else %}<form method="post" action="{% url 'projects:card_archive' card.id %}" class="d-inline">{% csrf_token %}<button class="btn btn-outline-danger">Archive</button></form>{% endif %}</div>{% endif %}</div>
<p><span class="badge text-bg-secondary">{{ card.get_priority_display }}</span> {{ card.column.name }} · {{ card.get_card_type_display }} · Revision {{ card.revision }}</p>
<div class="card card-body mb-4 markdown-body">{{ card.description_markdown|safe_markdown }}</div>
<details><summary>Raw Markdown</summary><pre>{{ card.description_markdown }}</pre></details>
<section aria-labelledby="card-files-heading" class="mt-4"><h2 id="card-files-heading" class="h4">Card files</h2>
{% include 'projects/_attachment_list.html' with files=card_files %}
{% if can_edit %}<form method="post" enctype="multipart/form-data" action="{% url 'projects:attachment_upload' card.id %}" class="mb-3" data-attachment-upload>{% csrf_token %}<label for="card-files-input" class="form-label">Add card files</label><input id="card-files-input" class="form-control" type="file" name="files" multiple required><button class="btn btn-outline-primary mt-2">Upload files</button><progress hidden max="100" value="0" aria-label="Upload progress"></progress><span role="status" aria-live="polite"></span></form>{% endif %}</section>
<h2 class="h4 mt-4">Progress notes</h2>
{% for comment in card.comments.all %}<div class="card card-body mb-2"><small>{{ comment.author }} · {{ comment.created_at }}</small><p>{{ comment.body|linebreaksbr }}</p></div>{% endfor %}
{% for comment in comments %}<div class="card card-body mb-2"><small>{{ comment.author }} · {{ comment.created_at }}</small><p>{{ comment.body|linebreaksbr }}</p><h3 class="h6">Files on this progress note</h3>
{% include 'projects/_attachment_list.html' with files=comment.attachments.all %}
{% if can_edit %}<form method="post" enctype="multipart/form-data" action="{% url 'projects:attachment_upload' card.id %}" data-attachment-upload>{% csrf_token %}<input type="hidden" name="comment_id" value="{{ comment.id }}"><label for="note-files-{{ comment.id }}" class="form-label">Add files to this note</label><input id="note-files-{{ comment.id }}" class="form-control" type="file" name="files" multiple required><button class="btn btn-outline-primary mt-2">Upload files</button><progress hidden max="100" value="0" aria-label="Upload progress"></progress><span role="status" aria-live="polite"></span></form>{% endif %}</div>{% endfor %}
{% if can_edit %}<form method="post" action="{% url 'projects:card_comment' card.id %}">{% csrf_token %}<label for="comment">Add note</label><textarea class="form-control" id="comment" name="body" required></textarea><button class="btn btn-success mt-2">Add note</button></form>{% endif %}
<h2 class="h4 mt-4">History</h2><ul>{% for event in card.activity.all %}<li>{{ event.created_at }} · {{ event.action }} by {{ event.actor }}</li>{% endfor %}</ul>
<script defer src="{% static 'projects/attachments.js' %}"></script>
{% endblock %}
+112
View File
@@ -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'<svg/>'), ('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'<svg/>')]
})
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']})
+73 -2
View File
@@ -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)
+6
View File
@@ -13,6 +13,7 @@ urlpatterns = [
path('<uuid:project_id>/archive/', views.project_archive, name='archive'),
path('<uuid:project_id>/restore/', views.project_restore, name='restore'),
path('<uuid:project_id>/cards/new/', views.card_create, name='card_create'),
path('<uuid:project_id>/cards/bulk-edit/', views.cards_bulk_edit, name='cards_bulk_edit'),
path('<uuid:project_id>/columns/new/', views.column_create, name='column_create'),
path('<uuid:project_id>/tags/new/', views.tag_create, name='tag_create'),
path('<uuid:project_id>/columns/reorder/', views.column_reorder, name='column_reorder'),
@@ -24,6 +25,11 @@ urlpatterns = [
path('cards/<uuid:card_id>/edit/', views.card_edit, name='card_edit'),
path('cards/<uuid:card_id>/move/', views.card_move, name='card_move'),
path('cards/<uuid:card_id>/comment/', views.card_comment, name='card_comment'),
path('cards/<uuid:card_id>/attachments/', views.attachment_upload, name='attachment_upload'),
path('attachments/<uuid:attachment_id>/download/', views.attachment_download, name='attachment_download'),
path('attachments/<uuid:attachment_id>/preview/', views.attachment_preview, name='attachment_preview'),
path('attachments/<uuid:attachment_id>/delete/', views.attachment_delete, name='attachment_delete'),
path('attachments/<uuid:attachment_id>/update/', views.attachment_update, name='attachment_update'),
path('cards/<uuid:card_id>/archive/', views.card_archive, name='card_archive'),
path('cards/<uuid:card_id>/restore/', views.card_restore, name='card_restore'),
]
+135 -3
View File
@@ -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