peter
57ad58ff2d
Trashed artifacts past a ~3-day retention window are now purged automatically. - storage.purge_expired_trash(): removes trash older than TRASH_RETENTION (all users), tolerant of already-gone rows (concurrent-safe). - spawn_trash_purge(): runs it on a daemon thread (manages/closes its own DB connection), triggered by each delete so it's cron-less and off the request thread. Inline fallback when AGENTFEED_ASYNC_PURGE is off (tests). - Wired into both delete paths (API + session). Manual Empty Trash unchanged. - Tests: purge removes expired-only; delete triggers the purge. 152 passing; live delete verified with the thread enabled (204, server healthy). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
78 lines
6.8 KiB
Markdown
78 lines
6.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
## Project
|
|
|
|
AgentFeed is a self-hosted, multi-user Django + Django REST Framework web app where AI agents, scripts, or people publish artifacts and each logged-in user browses their own time-ordered, label-filterable feed.
|
|
|
|
The core product principle is: agents publish content, not files. The server owns IDs, styling, storage layout, dates, and normalization into browser-native HTML, image, or PDF outputs.
|
|
|
|
## Current MVP Decisions
|
|
|
|
- Each user has a personal ingest API token (DRF `Token` model), viewable/regenerable from Settings → Account.
|
|
- Require `source` in every artifact payload — a free-text label identifying what posted it (agent-profile, script, or person name). Ownership of the resulting artifact comes from whichever user's token authenticated the POST, not from the `source` value itself.
|
|
- `source` and `tags` together form one unified **label** system: every artifact shows all its labels next to the title, and a single `label` filter/query param matches against either.
|
|
- Require login (Django session auth) for the browser feed/UI. The JSON API accepts a per-user bearer token for both ingest (POST/PATCH/DELETE) and artifact reads (GET list/detail), owner-scoped — an agent reads back with the same token it posts with; API requests never redirect to a browser login (JSON 403 instead). `GET /api/capabilities` and `GET /api/skill` are public (no user data), so agents can bootstrap before they have a key.
|
|
- Exception to the above: an artifact can be explicitly opted into public sharing (per-artifact, owner-toggled from the feed UI) via a high-entropy `share_token`, served unauthenticated at `GET /s/{share_token}`. Not exposed via the ingest API yet — UI-only. Turning sharing off immediately invalidates the old link. Images embedded in a shared artifact are also served unauthenticated while it's shared, so inline content doesn't break for a link recipient.
|
|
- User accounts can be created from Settings → Users (superuser-only in-app page) or via Django admin. Regular users are not staff and cannot access `/admin/`. Creating a user via Settings → Users also issues their API token immediately, shown once.
|
|
- `TagColor` (label color overrides) stays global/shared across all users.
|
|
- Deleting an artifact is a **soft-delete to Trash** (`deleted_at`), not a hard removal — recoverable via the "Deleted" sidebar folder (undelete), off-quota and eviction-protected while trashed, and purged permanently via "Empty Trash". `DELETE /api/artifacts/{id}` is soft too (idempotent); trashed artifacts are hidden from all API reads. A **Keep** sidebar folder is a view over `is_kept`. Both folders hide when empty. Trash auto-purges after a ~3-day retention window via a cron-less background thread triggered by deletes (`AGENTFEED_ASYNC_PURGE`, on by default); "Empty Trash" purges immediately.
|
|
- Use random 8-character artifact IDs.
|
|
- Start as a plain Django project; add Docker after core ingest and viewer work.
|
|
- Preserve original markdown as `.md` alongside rendered `.html`.
|
|
|
|
## Architecture Notes
|
|
|
|
- Planning source: `planning/daybook_planning.md`.
|
|
- Django project: `daybook_project/`.
|
|
- Main app: `artifacts/`.
|
|
- Theme CSS: `static/themes/`.
|
|
- Feed template: `templates/artifacts/feed.html`.
|
|
- Settings templates: `templates/artifacts/settings_*.html`.
|
|
- Stored artifact files live under `artifacts_store/{source}/{YYYY-MM-DD}/`.
|
|
|
|
## Implementation Guidelines
|
|
|
|
- Prefer small, direct changes over broad abstractions.
|
|
- Keep ingest normalization server-side.
|
|
- The viewer should only need to render HTML, image, or PDF.
|
|
- Do not make agents responsible for styling, filenames, or storage paths.
|
|
- Preserve existing planning decisions unless the user explicitly changes them.
|
|
- Avoid adding backwards-compatibility code before anything has shipped.
|
|
|
|
## Development And Deployment Workflow
|
|
|
|
- Develop and test locally in this workspace by default.
|
|
- Use the local Django commands for normal iteration: `python manage.py check`, `python manage.py migrate`, and `python manage.py runserver`.
|
|
- Run the local development server on `127.0.0.1:8001`. Port `8000` may be reserved or blocked on this workstation.
|
|
- Always use this same fixed port for the dev server. Never start a second instance on a different port; if `8001` is already serving, reuse it rather than starting another.
|
|
- All artifact-posting tools (`skills/agentfeed-posting/scripts/agentfeed_post.py`, `scripts/seed_demo_artifacts.py`, and any future posting skill) must default `AGENTFEED_URL` to `http://127.0.0.1:8001` to match.
|
|
- A regular (non-superuser) user `test` / password `testpwd` must always exist in the local dev database — it's the permanent account a sibling project (`AGENT_DAYBOOK__LLM_TEST`) uses for API testing. If the local `db.sqlite3` is ever reset, recreate this exact user (e.g. via Settings → Users) before assuming that project is broken.
|
|
- Do not deploy to the Proxmox NUC during routine code iteration.
|
|
- Treat the NUC container as the local live/staging target. Deploy there only at explicit stable checkpoints, such as an end-of-day build.
|
|
- Before any NUC deployment, preserve `/opt/daybook/deploy/.env` and `/opt/daybook/deploy/data`.
|
|
- After any NUC deployment or configuration change, run the documented health checks and update the NUC ops knowledge base plus `planning/daybook-container-handoff.md` if takeover facts changed.
|
|
|
|
## Repository Notes
|
|
|
|
- `_archive_/` exists for retired or moved project docs and experiments that should not drive current implementation decisions.
|
|
- Current deployment/takeover details live in `planning/daybook-container-handoff.md`; canonical NUC infrastructure details live in the NUC ops repo.
|
|
|
|
## Commands
|
|
|
|
- Install dependencies: `pip install -r requirements.txt`
|
|
- Run migrations: `python manage.py migrate`
|
|
- Start dev server: `python manage.py runserver 127.0.0.1:8001`
|
|
- Local app URL: `http://127.0.0.1:8001/`
|
|
- Local API health check: `http://127.0.0.1:8001/api/capabilities`
|
|
- Django checks: `python manage.py check`
|
|
|
|
## API Defaults
|
|
|
|
- MVP ingest endpoint: `POST /api/artifacts`
|
|
- MVP list endpoint: `GET /api/artifacts?label=&day=&kind=&q=`
|
|
- Artifact view: `GET /a/{id}`
|
|
- Auth: personal per-user token from Settings → Account, `Authorization: Bearer <token>`. Get one by creating a superuser (`python manage.py createsuperuser`), logging in, and visiting Settings → Account.
|
|
|
|
## Claude Code / OpenCode
|
|
|
|
This project uses `CLAUDE.md` for project instructions, compatible with both Claude Code and OpenCode. OpenCode is configured to load this file via a local, untracked `opencode.json` (it contains machine-specific MCP config, so it is not committed — recreate it locally with `{"$schema": "https://opencode.ai/config.json", "instructions": ["CLAUDE.md"], "permission": "allow"}` plus whatever MCP servers you want). After changing `opencode.json`, `.opencode/`, or this file, restart your AI coding assistant so the updated instructions are loaded.
|