Compare commits

..
34 Commits
Author SHA1 Message Date
bvandeusenandClaude Opus 5.5 61873b184b feat(7728): one delivery order for rules, and each delivery recorded with whether it was opened
CI & Build / integration (push) Waiting to run
CI & Build / Build & push image (push) Blocked by required conditions
CI & Build / TypeScript typecheck (push) Successful in 41s
CI & Build / Plugin hooks (push) Successful in 17s
CI & Build / Python lint (push) Successful in 3s
CI & Build / Python tests (push) In progress
Every rule arm now ranks what it delivers with one function
(services/rule_order.py): enforcement, then salience, then how narrowly
the rule was reached, then first mention before reminder, then the
rule's own open rate at that moment, then similarity. A crowded moment
drops the same rules whichever arm brought them, and a rule that holds
is never cut for a line beside it.

The open rate comes from a new table, rule_deliveries (migration 0129):
one row per rule line a plugin session is shown, full or repeat, with the
open stamped on the latest delivery it followed. The plugin routes bind
the session per request; the prompt, pre-tool and write-path hooks now
send it, and the opened hook reports every open, with its acts only when
no hook had just named the rule. Rows are pruned daily after 180 days.

Also fixes the TypeScript check: the store's list row now carries the
new enforcement field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 18:13:16 -05:00
bvandeusenandClaude Opus 5.5 61077752b9 feat(7728): a rule declares its enforcement and salience
CI & Build / Plugin hooks (push) Successful in 14s
CI & Build / Python lint (push) Successful in 2s
CI & Build / TypeScript typecheck (push) Failing after 21s
CI & Build / Python tests (push) Successful in 1m55s
CI & Build / integration (push) Successful in 2m2s
CI & Build / Build & push image (push) Skipped
A rule now carries what it does when it arrives, declared by its author
rather than guessed from a score: enforce (the act is checked), hold (the
reply or act waits for one read) or inform (a line beside the work, the
default). And a salience, high, normal or low, for ranking among rules of
the same enforcement at a crowded moment. A preference is always inform.

Migration 0128 adds both with CHECKs. Every door carries them: the
service, the MCP create and update tools, REST, backup and restore, and
the rule editor, which also marks holding and enforced rules in the list.
Unknown values are refused rather than mapped. Nothing reads them yet
beyond the record; the ordering function and the lifecycle come next in
this step, and step 5 decides who holds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 18:05:45 -05:00
bvandeusenandClaude Opus 5.5 da7c43aa8a feat(7741): a record reference shows the title of what it cites, before its number
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python tests (push) Successful in 1m48s
CI & Build / integration (push) Successful in 2m7s
CI & Build / Build & push image (push) Successful in 36s
A cited #N, milestone N or rule N in a rendered body now reads as the
record's title followed by its number, muted, so a reader knows what is
cited without hovering. The stored text stays #N and the title is read at
render: every existing record benefits and an edited title shows wherever
it is cited. Titles past 60 characters are shortened at a word, with the
full kind, title and status in the tooltip. A reference whose paragraph
already names the record (a batch writes #9 "Step two") keeps the bare
number, as does one the reader cannot open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 17:49:30 -05:00
bvandeusenandClaude Opus 5.5 08fdabd5e9 test(7736): the range case no longer puts "steps" before the first id
CI & Build / Plugin hooks (push) Successful in 13s
CI & Build / Python lint (push) Successful in 2s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python tests (push) Successful in 1m50s
CI & Build / integration (push) Successful in 1m58s
CI & Build / Build & push image (push) Successful in 43s
"step" is in the other-numbering word list ("step #3" is a position in
a plan), so "steps #5110" correctly stays plain. The case now tests the
range alone, and a second case pins the "step #3" reading.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 14:18:40 -05:00
bvandeusenandClaude Opus 5.5 38bc25a2b7 fix(7736): #N in a body links to the record it names, not to a tag
CI & Build / TypeScript typecheck (push) Successful in 35s
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 14s
CI & Build / Python tests (push) Failing after 1m37s
CI & Build / integration (push) Successful in 2m11s
CI & Build / Build & push image (push) Skipped
A purely numeric #N is a record reference everywhere now. The tag
patterns (frontend utils/tags.ts, the editor decoration, the first-line
tag strip, tag autocomplete, backend utils/tags.py) leave digits alone,
so #3127 is no longer drawn as a tag chip linking to /notes?tag=3127.

- utils/recordRefs.ts links #N, milestone N and rule N in rendered
  markdown, with the same patterns and other-numbering word list as
  services/record_refs.py. A drift test reads the TS source and fails
  when the two differ.
- v-record-refs (directives/recordRefs.ts) asks POST
  /api/notes/resolve-refs once per body for what each id is. A link
  gets the route for its kind (task, lesson, snippet, note, milestone,
  rule) and its kind and title on hover. One the reader cannot open is
  drawn as a dead reference, and missing vs not shared read the same.
  Applied on every surface that renders markdown.
- /milestones/:id finds the project and opens its board at that
  milestone (?milestone= expands it, scrolls to it and focuses it).
- Backlinks include records that cite #N in a body or a work log,
  through readable_notes_clause instead of an owner-only filter, and
  route by kind. The graph draws #N citations as dashed reference edges.
- create_note, create_task and add_task_log say which forms link.

There were no numeric tags to clean up: tags are stored only from the
explicit field, and none of the 200 most used is numeric.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 14:15:15 -05:00
bvandeusenandClaude Opus 5.5 6be44013bb fix(6872): a verdict or write-path stamp on a vanished shape revives its row instead of inserting a duplicate
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 14s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python tests (push) Successful in 1m46s
CI & Build / integration (push) Successful in 1m42s
CI & Build / Build & push image (push) Successful in 18s
classify_shapes(repo=...) and the write-path hook looked only at live rows,
so a shape whose row had vanished got a second provisional row under the
same (project, repo, path, symbol, kind). The unique constraint refused it,
and the whole classify batch was lost as a tool error.

provisional_row() now finds the row under that identity, vanished or not.
A vanished row is revived with a reappeared event and keeps its judgment.
A new row is inserted inside a savepoint, so a concurrent insert of the
same identity falls back to that row instead of failing the transaction.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 12:02:13 -05:00
bvandeusenandClaude Opus 5.5 219bfeac42 docs(6868): the proxy count is set in Settings, with the env var as the starting value
Configuration, the README env table and the features page say Settings
-> Config -> Reverse proxy is where the count is checked and set,
that a saved count wins over TRUSTED_PROXY_HOPS, that Cloudflare in
front of your own proxy is 2, and what a too-low count does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 10:03:22 -05:00
bvandeusenandClaude Opus 5.5 d2267b615f feat(6867): Settings → Config has a Reverse proxy section that shows which count is right
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python tests (push) Successful in 1m46s
CI & Build / integration (push) Successful in 2m8s
CI & Build / Build & push image (push) Successful in 33s
The section opens with a verdict on the admin's own request: the
address Grimoire reads them as, or, through Cloudflare, the count to set
with a button that sets it. Below it are the count with where it came
from, a table of what counts 0-3 would read, and the raw forwarding
chain. A saved count can be cleared back to the environment's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 09:59:05 -05:00
bvandeusenandClaude Opus 5.5 753a6ccb31 feat(6866): the proxy hop count is an admin setting, and the server shows what each count reads
CI & Build / Python lint (push) Successful in 2s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / integration (push) Successful in 2m1s
CI & Build / Build & push image (push) Successful in 20s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / Python tests (push) Successful in 1m47s
An admin can save how many reverse proxies stand in front of Grimoire.
A saved count wins over TRUSTED_PROXY_HOPS, which stays the starting
value. Each worker loads it at startup (under a deadline) and re-reads
it every 30s; the worker that saves applies it at once.

GET/PUT /api/admin/proxy returns the count, where it came from, and a
readout of the admin's own request: the socket peer, the forwarding
chains, what counts 0-3 would read, and the count that reads
Cloudflare's visitor when Cloudflare's headers are present. Saves are
audit-logged. A "too many attempts" reply now says where to look when
everyone is being blocked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 09:55:42 -05:00
bvandeusenandClaude Opus 5.5 49b5ceee41 docs(6856): the scope section says the cross-project rule in fewer lines, so using-grimoire fits its 350-line budget
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 17s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python tests (push) Successful in 1m52s
CI & Build / integration (push) Successful in 2m26s
CI & Build / Build & push image (push) Successful in 17s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 22:01:22 -05:00
bvandeusenandClaude Opus 5.5 8f8263b347 docs(6856): the plugin's guidance and the docs say what a session may do in another project
CI & Build / TypeScript typecheck (push) Successful in 31s
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 11s
CI & Build / Python tests (push) Failing after 1m29s
CI & Build / integration (push) Successful in 2m21s
CI & Build / Build & push image (push) Skipped
using-grimoire, which owns cross-project conduct, now says the one change
to make toward another project is filing an issue with how it was found
and the evidence, and that the plugin asks before anything more. The
features page describes the fence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 21:52:09 -05:00
bvandeusenandClaude Opus 5.5 ddcac96542 fix(6855): the fence keeps its files where no compaction sweeps them, and builds id lists under mawk
CI & Build / Python lint (push) Successful in 2s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / Python tests (push) Successful in 1m52s
CI & Build / integration (push) Successful in 2m21s
CI & Build / Build & push image (push) Successful in 22s
The project a session entered now lives in grimoire-fence, which the
compaction clear never visits, and session end removes it. Arrays of ids
in a tool's input were sent as [,"3","4"] under mawk, which creates an
array element as soon as it is assigned to.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 21:51:34 -05:00
bvandeusenandClaude Opus 5.5 805fda5cb1 feat(6855): the plugin asks before a session writes to a project other than its own
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python tests (push) Failing after 1m27s
CI & Build / Build & push image (push) Skipped
CI & Build / integration (push) Successful in 2m1s
plugin/hooks/grimoire_project_fence.sh runs as PreToolUse on editor writes,
Bash and Grimoire's tools. A session belongs to the project its starting
directory resolves to (CLAUDE_PROJECT_DIR: a .grimoire marker, else the git
remote's binding). A session that starts outside any project belongs to the
first one it enters, which PostToolUse on enter_project records.

These acts stop on permissionDecision "ask", with the server's reason naming
the other project:
- an edit in another project's repo or a worktree of it;
- a git commit, push, merge, rebase, pull, cherry-pick, revert, tag, am, reset
  or worktree add there, found through git -C, a cd before it, or the shell's
  current directory;
- a Grimoire write that lands in another project.

A live probe showed "ask" holds in bypassPermissions. Filing an issue and
every read go ahead. An edit or git command in the session's own repo, and any
tool named like a read, never calls the server. Grimoire writes send only
their short arguments, so the URL stays small.

When the instance doesn't answer, the act goes ahead and the hook says once
per outage that it couldn't check. check_plugin.py now holds one outage line
per hook and has a smoke event for the fence.

GET /api/plugin/write-scope takes fallback_project_id for the entered project.

tests/test_project_fence.py drives the hook against real git repos and a
stand-in server. tests/test_write_scope.py holds the hook's
FENCE_READ_PREFIXES equal to services/write_scope.READ_PREFIXES. The plugin
README and PACKAGING describe the fence, and the plugin is minted to
2026.11.05.0245.

Milestone 583, step 3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 21:45:37 -05:00
bvandeusenandClaude Opus 5.5 16b1d68ebd fix(6854): the locating arguments that only point are declared as references, and the plugin version is minted
CI & Build / Python lint (push) Successful in 2s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Plugin hooks (push) Successful in 13s
CI & Build / Python tests (push) Successful in 1m43s
CI & Build / integration (push) Successful in 2m2s
CI & Build / Build & push image (push) Successful in 22s
The guard caught seven write-tool arguments with a locating name that are not
where the write lands:
- snippet_id on classify_shapes_by_rule and confirm_shape_proposals names the
  canon, not the rows written;
- rule_outcome, rule_misfired and judge_lesson_link record judgments.

REFERENCES lists each one with its reason, and the guard reads it.
READ_PREFIXES names the tool prefixes the fence answers without the server,
and a test holds every write tool to a name outside them.

plugin.json is minted to 2026.11.05.0242 for the PACKAGING.md row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 21:42:14 -05:00
bvandeusenandClaude Opus 5.5 55f0f96016 feat(6854): the server says which project a pending act would change, and whether this session may do it
CI & Build / Python lint (push) Successful in 2s
CI & Build / Python tests (push) Failing after 1m23s
CI & Build / Build & push image (push) Skipped
CI & Build / Plugin hooks (push) Failing after 11s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / integration (push) Successful in 1m53s
GET /api/plugin/write-scope answers the plugin's fence. The session's project
comes from repo / project_id, as every plugin endpoint reads it. The act is
either:
- a directory (target_repo / target_project_id), for a file edit or a git
  command; or
- an MCP call (tool, plus input: the call's short arguments).

It returns allowed, the other projects the act would change, and the reason
the operator is asked. It is a GET so a read-scoped key still fences file
edits and git.

services/write_scope.WRITE_TARGETS lists every write tool with the arguments
that locate its write: a project id, or a task, note, milestone, System, rule,
relation, trash batch, repo or family decision, each traced to its project. A
write that lands in no project (install settings, user-level records, the
judgments a session is asked for anywhere) has an empty entry. The one
cross-project write allowed is create_task(kind="issue") as a new, unplanned,
open issue. A project the caller cannot read is never named.

tests/test_write_scope.py:
- requires an entry for every write tool;
- requires every declared argument to exist on the tool;
- refuses a locating argument (project_id, task_id, milestone_id and the
  rest) that a write tool takes without declaring it.

The integration test traces each locator from real rows.

Milestone 583, step 2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 21:39:03 -05:00
bvandeusenandClaude Opus 5.5 373f5bd454 feat(6839): the decision log and the knowledge feed load as you scroll, through one ScrollSentinel
CI & Build / Python lint (push) Successful in 2s
CI & Build / Python tests (push) Successful in 1m38s
CI & Build / integration (push) Successful in 2m9s
CI & Build / Build & push image (push) Successful in 36s
CI & Build / Plugin hooks (push) Successful in 17s
CI & Build / TypeScript typecheck (push) Successful in 33s
ScrollSentinel sits at the foot of a server-paged list and asks for the
next page a screen before the reader reaches it. It asks once per cursor,
forgets the cursor when its element goes, and shows Try again on a failed
page instead of retrying in a loop.

FamilyView's decision log loses its "Older decisions" button. A failed
page shows in place rather than as a toast, and rows already shown are
skipped when a new decision shifts the offset.

KnowledgeView drops its inline IntersectionObserver for the component.
The cursor is the ids consumed, not the items rendered, so a batch that
returns fewer records than it asked for still moves the feed on. A failed
batch puts its ids back and offers Try again, where it used to fail
silently and stop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 20:14:41 -05:00
bvandeusenandClaude Opus 5.5 846c87629f test(6849): the restore command previews without --yes and rolls back from the tar with it
CI & Build / Python lint (push) Successful in 1s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 33s
CI & Build / Python tests (push) Successful in 1m39s
CI & Build / integration (push) Successful in 1m51s
CI & Build / Build & push image (push) Successful in 16s
Two integration tests in test_integration_backup_rollback.py drive
grimoire.restore.run on the scheduled backup's tar, written from a full
export of this instance:
- without --yes it exits 4 and nothing changes;
- with --yes it takes the safety backup, then puts back the edited and the
  deleted task and removes the new one.

The file-restore test that expected a refusal "because the database has
accounts" now names the reason it actually refuses: on a live instance, a
backup that records no instance id can't be rolled back to.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 20:12:30 -05:00
bvandeusenandClaude Opus 5.5 37be3b0bff feat(6849): the command-line restore uses the same rollback, and the docs say how restore works now
CI & Build / Plugin hooks (push) Successful in 11s
CI & Build / Python lint (push) Successful in 2s
CI & Build / TypeScript typecheck (push) Successful in 31s
CI & Build / Python tests (push) Successful in 1m39s
CI & Build / integration (push) Successful in 1m49s
CI & Build / Build & push image (push) Successful in 31s
python -m grimoire.restore <file> prints what the restore would change (the
same preview as Settings) and stops. With --yes it runs
backup_job.rollback_to_backup: the current state is saved first, then the
whole instance goes back to the backup. An empty instance takes any full
backup. A live one only takes a backup of its own, and otherwise exits 3 with
the reason. A v1 backup keeps the copy-in path into an empty instance.

docs/backups.md Restoring is rewritten:
- what a restore puts back and removes;
- the same-instance rule;
- the safety backup;
- what survives;
- the web and command-line ways in.

Its S3 key advice now asks for read as well as write when restoring from the
bucket. README, features, architecture and the API reference follow.

Milestone 582, step 5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 20:08:31 -05:00
bvandeusenandClaude Opus 5.5 1f5e963c35 feat(6848): Settings restore rolls back, from the destination or a file, after a preview
CI & Build / Plugin hooks (push) Successful in 10s
CI & Build / Python lint (push) Successful in 1s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python tests (push) Successful in 1m42s
CI & Build / integration (push) Successful in 1m48s
CI & Build / Build & push image (push) Canceled after 22s
The web restore no longer copies a backup in beside the live data.

- GET /api/admin/restore/sources lists the backups at the backup destination,
  newest first.
- POST /api/admin/restore/preview says what a restore would do, changing
  nothing: fresh or rollback, when the backup was taken, and counts now and
  after per kind. A backup that cannot apply here gets a 409 with the reason.
- POST /api/admin/restore?confirm=rollback runs backup_job.rollback_to_backup:
  safety backup, replace, then search rebuilt in the background.

Each takes ?source=<name> (a backup at the destination) or an upload. The
destination path exists because uploads are held to the request-size limit,
and a real instance's backup is far over it. backup_s3.get_file downloads
from a bucket. backup_destination.list_backups/open_backup only accept names
the scheduled backup writes, so a request cannot reach any other file.

Settings -> Data -> Restore from Backup opens RestoreBackupDialog. The dialog:
1. Pick a backup at the destination or a file.
2. Read the preview.
3. Type "roll back".
4. Run it. The dialog then says where the replaced state was saved, and sends
   the user to sign in again.

Closes #6840. Milestone 582, step 4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 20:06:07 -05:00
bvandeusenandClaude Opus 5.5 34f8d7060b feat(6847): a rollback first backs up the state it replaces
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 35s
CI & Build / integration (push) Successful in 1m49s
CI & Build / Python tests (push) Successful in 1m40s
CI & Build / Build & push image (push) Successful in 24s
backup_job.rollback_to_backup:
1. Checks the backup can apply here (backup.check_replace, which shares
   _replace_mode with replace_from_backup), refusing before anything is written.
2. Takes the backup lock, so no scheduled backup runs during the rollback.
3. Saves the current store with save_state_before_restore.
4. Replaces the store.

The safety file goes to the backup destination when backups are on and it
takes it. Otherwise it goes to DATA_DIR/pre-restore, with a note when the
destination refused. If neither takes it the rollback does not run. The
result names where the file went.

Milestone 582, step 3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 20:02:26 -05:00
bvandeusenandClaude Opus 5.5 8806ab85b4 feat(6846): replace_from_backup rolls the store back to a full backup by id
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 33s
CI & Build / Python tests (push) Successful in 1m38s
CI & Build / integration (push) Successful in 2m1s
CI & Build / Build & push image (push) Successful in 20s
One transaction:
- Refuse unless the backup is a full one and, on a live instance, carries
  this instance's id. A fresh instance (no records, at most the restoring
  account) takes any full backup and adopts its id.
- Clear first: search vectors and the CSS consumer map (derived); every
  backed-up table nothing outside the backup points at, whole; the settings
  the backup carries; and the identity-table rows the backup lacks. A share
  granted by a removed user goes before the user.
- Write the backup through the same _build_* helpers as the copy-in restore,
  now _load_v2(keep_ids=...). Identity tables (users, projects, milestones,
  notes, rulebooks, topics, rules, systems, design systems, code shapes,
  family decisions) go through _place. That keeps the backup's id and
  merges, so API keys, shares and forge connections of a surviving row stay.
- Reset id sequences past the restored max, and sign every session out.

reindex_after_restore runs the four embedding backfills afterwards. A unit
guard checks that no row kept for outside references cascades from a table
replaced whole. Integration tests cover edits, deletions and new rows put
back, a surviving API key, sessions ending, fresh ids afterwards, foreign or
id-less backups refused, a user export refused, a failure part-way changing
nothing, and a fresh instance adopting the id.

Milestone 582, step 2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 19:59:48 -05:00
bvandeusenandClaude Opus 5.5 6d8db0bb65 feat(6845): every instance has an id lineage, and every full backup carries it
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / Python tests (push) Successful in 1m37s
CI & Build / integration (push) Successful in 2m7s
CI & Build / Build & push image (push) Successful in 22s
instance_identity is one row made by migration 0127 with a random id, so an
instance has it before its first account. A full backup carries it in its
header as instance_id (the tar manifest header and the JSON top level);
BACKUP_VERSION is 28. The table rides in _NOT_INCLUDED: a restore decides from
the header value rather than copying a row.

Two stores with the same id number their rows the same way. That is what lets
a later step roll a live instance back by original id, refuse a backup whose
ids would land on unrelated rows, and have a fresh-instance restore adopt the
backup's id (adopt_instance_id).

Milestone 582, step 1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 19:53:45 -05:00
bvandeusenandClaude Opus 5.5 3c01e17559 test(6838): give the test request its socket peer the way Quart reads it
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python tests (push) Successful in 1m38s
CI & Build / integration (push) Successful in 2m16s
CI & Build / Build & push image (push) Successful in 38s
Quart takes remote_addr from a Remote-Addr header its ASGI layer writes from
the scope (replacing any the client sent). A test request context does not
read scope_base for it, so the two socket-peer tests saw an empty address.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 19:37:28 -05:00
bvandeusenandClaude Opus 5.5 dbd6d5b8b5 feat(6838): read the client address and HTTPS from the trusted proxy hop
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 11s
CI & Build / TypeScript typecheck (push) Successful in 37s
CI & Build / Python tests (push) Failing after 1m20s
CI & Build / integration (push) Successful in 2m27s
CI & Build / Build & push image (push) Skipped
grimoire/proxy.py is the one reader of X-Forwarded-For and X-Forwarded-Proto.
It takes the entry TRUSTED_PROXY_HOPS in from the right (default 1; a shorter
header reads its leftmost entry; 0 trusts no proxy), so an entry a client puts
left of the proxy's is never believed. Before this, with TRUST_PROXY_HEADERS
on, the leftmost X-Forwarded-For entry keyed the login, register, forgot and
reset rate limits and the audit log, and a client could choose it.

The session cookie is Secure, and HSTS (max-age=31536000) is sent, exactly
when the request is HTTPS by the trusted proxy's word. Plain HTTP is
untouched and nothing redirects. SECURE_COOKIES is gone (a startup warning says
so when it is still set); TRUST_PROXY_HEADERS=false still maps to 0 hops, with
a warning to move to TRUSTED_PROXY_HOPS. Admin audit lines now use the same
client address instead of the socket peer.

The placeholder-key refusal keyed on SECURE_COOKIES, so it now refuses either
placeholder key outright; the instance makes its own key when none is set.

Family idea #5004 (IsHTTPS, trusted-hop X-Forwarded-Proto), canon v2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 19:32:20 -05:00
bvandeusenandClaude Opus 5.5 b87178d261 fix(6495): a name defined in two packages counts only in the canon's own
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 14s
CI & Build / integration (push) Successful in 1m22s
CI & Build / TypeScript typecheck (push) Successful in 37s
CI & Build / Python tests (push) Successful in 1m59s
CI & Build / Build & push image (push) Successful in 43s
A by-name reference edge could not tell two definitions of one name apart:
in a Go repo that defines `file` as importRun.file (internal/files, the
canon) and as sftpRun.file (internal/replication), a mirror test calling
`m.file(` was recorded as a use of the canon.

names_canon now takes defined_at, every repo path that defines each name,
in place of the shape file's own names. The own-file rule is unchanged.
When the repo also defines the canon's name somewhere the canon is not
recorded, a mention counts only from the canon's own package: the
directory of a file location exactly, or under a directory location.
A name defined once resolves as before. Proposer version 8 -> 9, so the
next coverage refresh re-reads every row and replaces its reference edges.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 20:05:09 -04:00
bvandeusenandClaude Opus 5.5 2a6d9080ba fix(6477): a plain-word call needs the parenthesis right after the word
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 33s
CI & Build / integration (push) Successful in 59s
CI & Build / Python tests (push) Successful in 1m37s
CI & Build / Build & push image (push) Successful in 26s
Read against Fabled Archives after the cleanup: of the 9 rows still linked
to snippet #5448 (symbol `file`), all but one matched prose in a comment,
"a file (not a directory)", "the file (ScanWaiting". The only real call
was `r.file(ctx, ...)`. Formatted code never puts a space before a call's
parenthesis and prose does, so the plain-word test is now `word(` with no
whitespace. _PROPOSER_VERSION 8 re-reads every row once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 19:07:03 -04:00
bvandeusenandClaude Opus 5.5 3e2227e8c5 fix(6483): drop the cross-project uses edges the write path wrote
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 11s
CI & Build / TypeScript typecheck (push) Successful in 34s
CI & Build / integration (push) Successful in 1m0s
CI & Build / Python tests (push) Successful in 1m41s
CI & Build / Build & push image (push) Successful in 19s
Migration 0125 removed the proposer's cross-project `reference` edges, but
the write path records its by-name evidence with basis `hook`, so those
survived it. A hook edge across projects is impossible for the same reason a
reference edge is, and the write path now applies the same by-name test
(names_canon), so 0126 removes the ones written before. Judged edges keep
their own basis and are untouched.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 18:29:54 -04:00
bvandeusenandClaude Opus 5.5 cdb71e64c4 fix(6477): a body uses a canon by name only when the name can resolve to it
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 13s
CI & Build / TypeScript typecheck (push) Successful in 43s
CI & Build / integration (push) Successful in 1m36s
CI & Build / Python tests (push) Successful in 2m7s
CI & Build / Build & push image (push) Successful in 42s
The proposer's reference basis, and every uses edge it writes, counted any
word-bounded mention of a canon's symbol. Three holes made that wrong at
scale (snippet #5448, symbol `file`, held 2,161 uses edges):

- Go, Rust, Kotlin, Swift, Dart, C, C#, Ruby and PHP were outside the
  language-family maps, so their canons read as "unknown, no gate" and were
  matched in every Python, TS and CSS body.
- Canons in other projects were matched by name, though one repo never
  calls a function defined in another's.
- A plain word (`file`, `seen`) or a module's own helper (`_run`) matched
  wherever it appeared.

names_canon is now the one by-name test, used by match_canon,
reference_canons and the write-path hint: same project, not a name the file
defines itself (unless the canon is recorded there), no generic verb with or
without a leading underscore, and a bare lowercase word only where it is
called. The write path keeps the payload's own names in play, since a
redefinition of a pulled canon is the copy it exists to flag.

Repair: record_uses only adds, so replace_reference_uses now makes a row's
machine-written reference edges exactly what the current rule finds,
leaving judged and hook edges alone. _PROPOSER_VERSION 7 re-reads every row
on its project's next refresh. Migration 0125 deletes the cross-project
reference edges already stored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 17:41:21 -04:00
bvandeusenandClaude Opus 5.5 0b98a3a5cd chore(6480): remove five Vue components nothing imports
HistoryPanel, InlineAssistPanel, NoteCard, WorkspaceNoteEditor and
WorkspaceTaskPanel had no importer, lazy import or global registration
anywhere in frontend/src. The features they served were replaced; token
sweeps kept restyling them because they match a glob. The two doc comments
that named HistoryPanel.vue now name VersionHistorySection.vue, the note
history that is live.

SearchBar.vue stays: it is the recorded home of snippet #2961 "SearchBar -
the search input recipe", and the two live search boxes are judged variants
of it. Deleting it would leave the recipe pointing at nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 17:36:03 -04:00
bvandeusenandClaude Opus 5.5 7faaa311d7 fix(6470): a moment proposal counts only opens no hook explained, and asks the reader to judge it
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 35s
CI & Build / integration (push) Successful in 1m4s
CI & Build / Python tests (push) Successful in 1m46s
CI & Build / Build & push image (push) Successful in 37s
The signal counted every get_rule open against every moment from the
previous three minutes, so a rule a search arm had just shown was
proposed for whatever moment happened to fire. All nine pending signal
proposals were wrong.

- The hook skips an open of a rule a hook named this session, and sends
  the last three acts from 90 seconds instead of 30 from 180.
- A rule already mounted anywhere gathers no signal evidence.
- A signal pair keeps the actions that reached its moment and shows them
  as its why.
- The proposal line says it is co-occurrence, not a recommendation, and
  asks the reader to check the rule against the moment before offering
  it; moments.md says the same.

Plugin 2026.10.26.2029.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 16:29:40 -04:00
bvandeusenandClaude Opus 5.5 83cb6420e2 fix(6471): the end-of-turn shape check hears every definition a write made
The write hooks recorded at most 12 definitions per write (alphabetical,
so test functions were the ones dropped) and the post-Bash hook stopped
after 4 files, so the Stop hook never asked about the rest. The caps
bound the prior-art query; the written ledger now gets the full list,
up to 40 files per Bash call, while the query stays at 4 files x 12 names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 16:26:15 -04:00
bvandeusenandClaude Opus 5.5 db2427a3dc feat(6249): the write-path hint asks whether a new definition copies a close snippet
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 55s
CI & Build / integration (push) Successful in 1m2s
CI & Build / Python tests (push) Successful in 1m56s
CI & Build / Build & push image (push) Successful in 22s
The derive check matches by name, so a renamed copy of a recorded snippet
passed it and showed only as "similar" prior art. When a write introduces a
definition the file does not hold (shape_ledger.new_shapes_at) and an unseen
snippet on the menu clears the write-path floor by WRITEPATH_COPY_MARGIN (0.80
at the default floor), the hint now says to reuse it or extract the shared
shape before another copy. Names the derive check or the stamping feed already
spoke for are left to them. Covers recorded snippets only: the ledger keeps no
bodies to compare an unrecorded sibling against.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 20:14:41 -04:00
bvandeusenandClaude Opus 5.5 0a4eb313fe fix(6255): Test destination names an address that did not answer as S3
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 13s
CI & Build / TypeScript typecheck (push) Successful in 55s
CI & Build / integration (push) Successful in 1m5s
CI & Build / Python tests (push) Successful in 1m55s
CI & Build / Build & push image (push) Successful in 23s
A 4xx with no S3 error body came from something else at that address, most
often a web server on the default port. The message now says so and to check
the scheme and port, beside the raw status. A 5xx without a body keeps its
own reason, since a busy S3 service can answer that way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 20:03:52 -04:00
bvandeusenandClaude Opus 5.5 d51ccd9b69 fix(6253): the moment-proposal queue lists a signal pair only once it has proposed
pending() listed every suggested signal row, including pairs still gathering
evidence below the three-situation bar, so the queue held 200 "proposals"
where about 25 had crossed it. A signal pair now needs proposed_at in its
evidence, the same test the misfire half already applies; proposals from a
pass are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 20:03:52 -04:00
125 changed files with 7683 additions and 3076 deletions
+6 -7
View File
@@ -28,10 +28,10 @@ services:
environment:
DATABASE_URL: "postgresql+asyncpg://${POSTGRES_USER:-grimoire}:${POSTGRES_PASSWORD:-grimoire}@db:5432/${POSTGRES_DB:-grimoire}"
LOG_LEVEL: "${LOG_LEVEL:-INFO}"
# Behind an HTTPS reverse proxy:
# Port 5000 is published straight to clients, so no proxy is trusted.
# Behind a reverse proxy, set 1 (one per proxy) and BASE_URL:
TRUSTED_PROXY_HOPS: "0"
# BASE_URL: "https://grimoire.example.com"
# SECURE_COOKIES: "true"
# TRUST_PROXY_HEADERS: "true"
volumes:
- app_data:/data
depends_on:
@@ -75,8 +75,7 @@ Everything is optional. Set these in the environment or in a `.env` file beside
| Variable | When | What it does |
|----------|------|--------------|
| `BASE_URL` | Behind a proxy | The public URL, used in email links and SSO redirects |
| `SECURE_COOKIES` | Over HTTPS | `true` when Grimoire is served over HTTPS |
| `TRUST_PROXY_HEADERS` | Behind a proxy | `true` to read the client address from the proxy's headers |
| `TRUSTED_PROXY_HOPS` | Rarely | The starting count of reverse proxies in front of Grimoire (default `1`; the compose file above sets `0` because it publishes the port directly). Check and change it in **Settings → Config → Reverse proxy**, which shows what each count reads for your own request; behind Cloudflare it is usually `2` |
| `POSTGRES_PASSWORD` | Before the first start | The database password (defaults to `grimoire`; the database is reachable only inside the compose network). Postgres takes it once, when the volume is created |
| `SECRET_KEY` | Rarely | A key you manage yourself, instead of the one Grimoire keeps. It wins over the kept key; remove it to go back |
@@ -97,7 +96,7 @@ docker compose up -d
Database migrations run when the app starts, and the key stays in its volume. Claude Code updates the plugin from its marketplace; run `/reload-plugins` after an update.
**Settings → Data → Scheduled backups** writes a daily backup of the database to a folder or an S3-compatible bucket, and `python -m grimoire.restore` brings a fresh instance back from one. See [Backups](docs/backups.md).
**Settings → Data → Scheduled backups** writes a daily backup of the database to a folder or an S3-compatible bucket, and Settings → Data → Restore from Backup rolls the instance back to one, or brings a new instance back from it. See [Backups](docs/backups.md).
## Features
@@ -132,7 +131,7 @@ The full list is in [Features](docs/features.md).
| What you see | Why | Fix |
|--------------|-----|-----|
| `SECRET_KEY is set to the public placeholder` at startup | `SECURE_COOKIES=true` while `SECRET_KEY` is `dev-secret-change-me` | Remove `SECRET_KEY`, or set a real one |
| `SECRET_KEY is set to the public placeholder` at startup | `SECRET_KEY` is `dev-secret-change-me` or `change-me-in-production` | Remove `SECRET_KEY`, or set a real one |
| Settings asks for forge tokens or the backup secret again | The instance's key changed: the `app_data` volume was replaced, or `SECRET_KEY` was set or removed | Enter them again, or restore the previous key |
| `Can't locate revision identified by '…'` at startup | An older image is running against a database a newer one has already migrated | Run the newer image; migrations only move forward |
| The plugin's tools are missing in Claude Code | The plugin isn't installed, or Claude Code hasn't reloaded it | `/plugin` to install or update it, then `/reload-plugins` |
@@ -0,0 +1,35 @@
"""drop machine-written uses edges that cross projects
Revision ID: 0125
Revises: 0124
Create Date: 2026-10-26
A `uses` edge with basis `reference` is the proposer's by-name reading: the
shape's body names a canon's symbol. A body never calls a function defined in
another project's repository, so such an edge across projects is a common
word matched, not a call. The proposer no longer writes them, and this removes
the ones it wrote before. Edges a person or an audit judged keep their own
basis and are left alone. Rows within one project are re-read on the next
coverage refresh, which replaces their reference edges under the same rule.
Downgrade restores nothing: the removed edges were never facts.
"""
from alembic import op
revision = "0125"
down_revision = "0124"
branch_labels = None
depends_on = None
def upgrade() -> None:
op.execute(
"DELETE FROM code_shape_uses u USING code_shapes s, notes n "
"WHERE u.shape_id = s.id AND u.snippet_id = n.id "
"AND u.basis = 'reference' "
"AND n.project_id IS NOT NULL AND n.project_id <> s.project_id"
)
def downgrade() -> None:
pass
@@ -0,0 +1,34 @@
"""drop write-path uses edges that cross projects
Revision ID: 0126
Revises: 0125
Create Date: 2026-10-26
The write path records a `uses` edge with basis `hook` when a session pulled a
snippet and then wrote code naming its symbol. That is by-name evidence, like
the proposer's `reference` edges 0125 removed, and a body never calls a
function defined in another project's repository. The write path now applies
the same by-name test, so it writes no such edge; this removes the ones it
wrote before. Judged edges keep their own basis and are left alone.
Downgrade restores nothing: the removed edges were never facts.
"""
from alembic import op
revision = "0126"
down_revision = "0125"
branch_labels = None
depends_on = None
def upgrade() -> None:
op.execute(
"DELETE FROM code_shape_uses u USING code_shapes s, notes n "
"WHERE u.shape_id = s.id AND u.snippet_id = n.id "
"AND u.basis = 'hook' "
"AND n.project_id IS NOT NULL AND n.project_id <> s.project_id"
)
def downgrade() -> None:
pass
@@ -0,0 +1,39 @@
"""instance identity — the id lineage a backup carries
Revision ID: 0127
Revises: 0126
Create Date: 2026-11-05
One row naming this database's id lineage. Every full backup carries it, a
restore into a fresh instance adopts it (the restore keeps the original ids),
and rolling a live instance back requires the backup's to match, so a backup's
ids never land on unrelated rows. Made here with a random value, so every
instance has one before its first account exists.
"""
import sqlalchemy as sa
from alembic import op
revision = "0127"
down_revision = "0126"
branch_labels = None
depends_on = None
def upgrade() -> None:
op.create_table(
"instance_identity",
sa.Column("id", sa.Integer(), primary_key=True),
sa.Column("instance_id", sa.Text(), nullable=False),
sa.Column(
"created_at", sa.DateTime(timezone=True), nullable=False,
server_default=sa.func.now(),
),
sa.CheckConstraint("id = 1", name="ck_instance_identity_single_row"),
)
op.execute(
"INSERT INTO instance_identity (id, instance_id) VALUES (1, gen_random_uuid()::text)"
)
def downgrade() -> None:
op.drop_table("instance_identity")
+48
View File
@@ -0,0 +1,48 @@
"""rule enforcement and salience — what a rule does when it arrives, and how much it outranks
Revision ID: 0128
Revises: 0127
Create Date: 2026-11-22
Two declared columns on a rule, read by the one function that orders what
reaches a moment:
- `enforcement`: `enforce` (the act itself is checked), `hold` (the reply or act
waits for one read), `inform` (a line beside the work). Every existing rule
starts as `inform`; declaring which ones hold is the author's call.
- `salience`: `high`, `normal`, `low` — the author's ranking among rules of
the same enforcement.
"""
import sqlalchemy as sa
from alembic import op
revision = "0128"
down_revision = "0127"
branch_labels = None
depends_on = None
_ENFORCEMENTS = ("enforce", "hold", "inform")
_SALIENCES = ("high", "normal", "low")
def _in_list(column: str, values: tuple[str, ...]) -> str:
return f"{column} IN ({', '.join(repr(v) for v in values)})"
def upgrade() -> None:
op.add_column("rules", sa.Column("enforcement", sa.Text(), nullable=False, server_default="inform"))
op.add_column("rules", sa.Column("salience", sa.Text(), nullable=False, server_default="normal"))
op.create_check_constraint("ck_rules_enforcement", "rules", _in_list("enforcement", _ENFORCEMENTS))
op.create_check_constraint("ck_rules_salience", "rules", _in_list("salience", _SALIENCES))
# A preference claims no force: it is how work is liked done, not a bar.
op.create_check_constraint(
"ck_rules_preference_informs", "rules", "kind <> 'preference' OR enforcement = 'inform'",
)
def downgrade() -> None:
op.drop_constraint("ck_rules_preference_informs", "rules", type_="check")
op.drop_constraint("ck_rules_salience", "rules", type_="check")
op.drop_constraint("ck_rules_enforcement", "rules", type_="check")
op.drop_column("rules", "salience")
op.drop_column("rules", "enforcement")
+42
View File
@@ -0,0 +1,42 @@
"""rule deliveries — each rule line a session was shown, and whether it was opened after
Revision ID: 0129
Revises: 0128
Create Date: 2026-11-22
One row per rule line delivered to a session, with the open stamped on the
delivery it followed. The open rate per rule and moment is read from it, both
for the ordering of what reaches a moment and for the adherence readout.
"""
import sqlalchemy as sa
from alembic import op
revision = "0129"
down_revision = "0128"
branch_labels = None
depends_on = None
def upgrade() -> None:
op.create_table(
"rule_deliveries",
sa.Column("id", sa.BigInteger(), primary_key=True),
sa.Column("user_id", sa.BigInteger(), nullable=False),
sa.Column("session_id", sa.Text(), nullable=False),
sa.Column("rule_id", sa.BigInteger(), nullable=False),
sa.Column("source", sa.Text(), nullable=False),
sa.Column("at", sa.Text(), nullable=False),
sa.Column("form", sa.Text(), nullable=False),
sa.Column("delivered_at", sa.DateTime(timezone=True), nullable=False,
server_default=sa.func.now()),
sa.Column("opened_at", sa.DateTime(timezone=True), nullable=True),
sa.CheckConstraint("form IN ('full', 'repeat')", name="ck_rule_deliveries_form"),
)
op.create_index("ix_rule_deliveries_session_rule", "rule_deliveries",
["user_id", "session_id", "rule_id", "delivered_at"])
op.create_index("ix_rule_deliveries_rule_at", "rule_deliveries", ["rule_id", "at"])
op.create_index("ix_rule_deliveries_delivered_at", "rule_deliveries", ["delivered_at"])
def downgrade() -> None:
op.drop_table("rule_deliveries")
+3 -2
View File
@@ -8,8 +8,9 @@ services:
# a Docker secret and sets SECRET_KEY_FILE to its path).
SECRET_KEY: "${SECRET_KEY}"
LOG_LEVEL: "${LOG_LEVEL:-INFO}"
TRUST_PROXY_HEADERS: "true"
SECURE_COOKIES: "true"
# Proxies in front of the app (Traefik = 1). The client address and
# HTTPS are read from that far in from the right of X-Forwarded-*.
TRUSTED_PROXY_HOPS: "1"
volumes:
- app_data:/data
networks:
+3 -3
View File
@@ -13,10 +13,10 @@ services:
environment:
DATABASE_URL: "postgresql+asyncpg://${POSTGRES_USER:-grimoire}:${POSTGRES_PASSWORD:-grimoire}@db:5432/${POSTGRES_DB:-grimoire}"
LOG_LEVEL: "${LOG_LEVEL:-INFO}"
# Behind an HTTPS reverse proxy:
# Port 5000 is published straight to clients, so no proxy is trusted.
# Behind a reverse proxy, set 1 (one per proxy) and BASE_URL:
TRUSTED_PROXY_HOPS: "0"
# BASE_URL: "https://grimoire.example.com"
# SECURE_COOKIES: "true"
# TRUST_PROXY_HEADERS: "true"
volumes:
- app_data:/data
depends_on:
+5 -1
View File
@@ -251,6 +251,7 @@ These serve the plugin's hooks.
| POST | `/api/plugin/rule-opened` | Records that a session opened a rule it was shown |
| GET | `/api/plugin/shape-check` | The end-of-turn question about what this turn wrote |
| GET | `/api/plugin/claim-session` · `/release-session` | Bind a session to its task claims / release them at session end |
| GET | `/api/plugin/write-scope` | Which projects a pending act would change (a directory, or an MCP call's `tool` and `input`), and whether a session in its own project may do it. Filing an issue elsewhere is allowed; every other cross-project write is answered `allowed: false` with the reason the operator is asked |
| GET | `/api/plugin/processes` | Stored Processes for skill-stub sync |
| GET | `/api/plugin/prior-art` | Write-path hint for the plugin hooks (params: `path`, `code`, `repo`, `shapes`, `exclude_ids`, `exclude_sync_ids`, `exclude_derive`); returns `context`, `note_ids`, `sync_note_ids`, `stamped`, `divergence`, `derive`, `derive_keys` |
| GET / POST | `/api/projects/<id>/coverage`, `…/coverage/refresh` | Shape-ledger accounting (`pattern_coverage` line, counts, `derive_groups` — css groups carry `consumers`, `derive_new`, `unused_css`, `divergence`, `recheck`) |
@@ -272,12 +273,15 @@ These serve the plugin's hooks.
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/admin/backup` | Export backup (format v4; `?scope=user` for own data) |
| POST | `/api/admin/restore` | Restore from a backup |
| GET | `/api/admin/restore/sources` | The backups at the backup destination, newest first |
| POST | `/api/admin/restore/preview` | What restoring a backup (`?source=<name>` or an uploaded file) would change; 409 with the reason when it can't apply here |
| POST | `/api/admin/restore?confirm=rollback` | Put the whole instance back to that backup, after saving the current state |
| GET / DELETE | `/api/admin/users` · `/api/admin/users/:id` | List / delete users |
| GET / PUT | `/api/admin/registration` | Get / toggle registration |
| GET / PUT | `/api/admin/smtp` · POST `/api/admin/smtp/test` | SMTP config + test email |
| GET | `/api/admin/logs` · `/api/admin/logs/stats` | Log entries + category counts |
| GET / PUT | `/api/admin/base-url` | Get / set the public base URL |
| GET / PUT | `/api/admin/proxy` | Get / set how many reverse proxies stand in front of Grimoire (`{"hops": n}`, or `null` for the environment's count), with what each count would read for this request |
| GET / PUT | `/api/admin/db-maintenance` (+ `/health`, POST `/run`) | VACUUM schedule, health, manual run |
| POST / GET / DELETE | `/api/admin/invitations` (+ `/:id`) | Create / list / revoke invite links |
| GET / PUT | `/api/admin/backups` | Scheduled backups: destination, schedule and recent runs |
+3 -3
View File
@@ -69,10 +69,10 @@ Every database wait on startup has a deadline. Migrations wait for the database
## Authentication
- **Sessions**: `HttpOnly`, `SameSite=Lax` cookies, `Secure` when `SECURE_COOKIES=true`. Changing a password bumps the user's session version and signs out their other sessions.
- **Sessions**: `HttpOnly`, `SameSite=Lax` cookies, `Secure` on a request the trusted proxy reports as HTTPS, which also gets HSTS (`grimoire/proxy.py`). Changing a password bumps the user's session version and signs out their other sessions.
- **API keys**: `Authorization: Bearer fmcp_...`, stored hashed. A `read` key may only call read endpoints and read MCP tools.
- **OIDC** single sign-on with PKCE, optionally replacing local logins ([SSO / OAuth](sso-oauth.md)).
- **Rate limits** on register, login and forgot-password, per client IP (`TRUST_PROXY_HEADERS` reads the IP from the proxy's headers).
- **Rate limits** on register, login and forgot-password, per client IP, read from `X-Forwarded-For` by `TRUSTED_PROXY_HOPS`.
Credentials Grimoire stores for outside services (forge tokens, the backup destination's S3 secret) are sealed under a key derived from `SECRET_KEY`, which the instance makes on first start and keeps in `/data/secret_key` unless one is set.
@@ -87,7 +87,7 @@ Credentials Grimoire stores for outside services (forge tokens, the backup desti
│ ├── routes/ REST blueprints
│ ├── mcp/ MCP server and its tool modules
│ ├── services/ shared logic
│ └── restore.py `python -m grimoire.restore` for a fresh instance
│ └── restore.py `python -m grimoire.restore`: the restore, from the command line
├── frontend/src/ views, components, stores, composables, api client
├── plugin/ Claude Code hooks, skills and commands
├── scripts/ CI checks and the plugin version minter
+52 -21
View File
@@ -88,9 +88,12 @@ You need four things:
- **Access key.**
- **Secret key.**
Grimoire uploads and lists; it never deletes. A key that may **only add
objects** is therefore enough, and it is the safer key to hand out: a stolen
one cannot wipe the history.
Grimoire uploads and lists, and reads a backup back when you restore from the
bucket; it never deletes. A key that may **add and read objects but not
delete them** is therefore enough, and it is the safer key to hand out: a
stolen one cannot wipe the history. A key that may only add objects still
takes backups; restore then works by uploading a file or from the command
line.
The secret is stored encrypted, under a key derived from `SECRET_KEY`. It is
never shown again, and never included in a backup. If an instance's
@@ -122,8 +125,10 @@ keeps service backups as "backup targets". Either destination works with it.
1. On Archives' **Backups** page, make a target for Grimoire, named `grimoire`
for example.
2. Choose how Grimoire's files arrive:
- **S3**: turn on the S3 way in for the target and make an **append-only**
S3 key. In Grimoire, choose **An S3 bucket**:
- **S3**: turn on the S3 way in for the target and make an S3 key that
may add and read objects but not delete them (an **append-only** key
takes backups too, but then Grimoire can't restore from the bucket). In
Grimoire, choose **An S3 bucket**:
- address: Archives' backup address (`http://<archives>:8081`);
- bucket: the target's name;
- access key and secret key: the key you just made.
@@ -139,26 +144,52 @@ keeps service backups as "backup targets". Either destination works with it.
## Restoring
### Into a fresh instance
A restore puts the **whole instance** back to the moment a backup was taken,
for every user:
Start Grimoire on an empty database, copy the backup file into the container,
and run:
- records edited since go back to how they were;
- records deleted since come back;
- anything made since is removed.
It matches records by their ids, so a live instance only restores a backup **of
its own**. Each instance has an id, and every backup records the one it came
from. A backup from another instance, or one made before backups recorded it,
only goes into a new, empty instance, which takes it as it is.
Before changing anything, the restore saves the current state as one more
backup. It goes to the backup destination when scheduled backups are on, and
otherwise to `/data/pre-restore`. The result says which file it is, so a
restore can itself be undone.
What a backup doesn't carry stays as it is wherever its owner survives the
restore: API keys, forge connections, sharing, logs, and the destination's S3
secret. The trash isn't in backups, so anything in the trash when the backup
was taken is gone afterwards. Everyone is signed out, and search is rebuilt.
### From the web
**Settings → Data → Restore from Backup** lists the backups at the backup
destination. You can pick one of those, or upload a `.tar` or the JSON
**Full Backup** download (uploads are held to the server's request-size
limit). The restore then shows what would change: when the backup was taken,
and how many accounts, projects, plans, notes and rules there are now and will
be afterwards. Type `roll back` to run it. Then sign in again.
To read backups back from an S3 bucket, the key needs read access as well as
write. Grimoire never deletes from the bucket.
### From the command line
For a file with no size limit, or a new instance with no backup destination
yet, copy the file into the container and run:
```sh
docker exec -it grimoire python -m grimoire.restore /backups/grimoire-20261015T020000Z.tar
```
- The command refuses a database that already has an account. A restore
re-creates everything with new ids, so on a live instance it would add a
second copy instead of replacing anything.
- Nothing limits the file's size.
- It also reads the JSON from the admin **Full Backup** download.
It prints what would change and stops. Add `--yes` to restore. It reads the
JSON download too. Afterwards, **restart Grimoire** so the search indexes are
rebuilt.
Afterwards, **restart Grimoire** so the search indexes are rebuilt. Then issue
new API keys, add forge connections again, and set up any sharing.
### From the web
**Settings → Data → Restore from Backup** takes the `.tar` as well as the
JSON download. The upload is held to the server's request-size limit. For a
bigger file, use the command above.
After restoring into a new instance, issue new API keys, add forge connections
again, and set up any sharing: none of them travel in a backup.
+14 -8
View File
@@ -14,8 +14,7 @@ Any variable marked *secret* can also be read from a file: set `<NAME>_FILE` to
| `SECRET_KEY` *(secret)* | kept in `DATA_DIR` | Signs sessions and seals stored credentials. Unset, the instance makes its own on first start and keeps it in `DATA_DIR/secret_key`. Set it only to manage the key yourself; it wins over the kept one (see below) |
| `DATA_DIR` | `/data` | Where the instance keeps its own `SECRET_KEY`. Mount a volume here |
| `BASE_URL` | `http://localhost:5000` | Public URL, used in email links and OIDC redirects |
| `SECURE_COOKIES` | `false` | `true` when Grimoire is served over HTTPS |
| `TRUST_PROXY_HEADERS` | `false` | `true` behind a reverse proxy, to read the client IP from `X-Forwarded-For` / `X-Real-IP` |
| `TRUSTED_PROXY_HOPS` | `1` | The starting count of reverse proxies in front of Grimoire. **Settings → Config → Reverse proxy** is where the count is checked and set, and a count saved there wins over this. The client address and the scheme are read that many entries in from the right of `X-Forwarded-For` and `X-Forwarded-Proto`; `0` ignores both headers. See [Behind a reverse proxy](#behind-a-reverse-proxy) |
| `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING` or `ERROR` |
| `LOG_RETENTION_DAYS` | `90` | Days of app logs to keep |
| `FASTEMBED_CACHE_DIR` | `/data/fastembed-cache` | Where the embedding model is stored after its first download |
@@ -77,7 +76,7 @@ docker compose -f docker-compose.dev.yml up --build
### Docker Swarm
[`docker-compose.prod.yml`](../docker-compose.prod.yml) is a stack file: the app and database on a private overlay network, with `SECURE_COOKIES` and `TRUST_PROXY_HEADERS` on. A Swarm can move the app to another node, away from a node-local `/data` volume, so the stack sets its own key: provide `DB_PASSWORD` and `SECRET_KEY` in the environment (or mount a Docker secret and set `SECRET_KEY_FILE`):
[`docker-compose.prod.yml`](../docker-compose.prod.yml) is a stack file: the app and database on a private overlay network, trusting one proxy (`TRUSTED_PROXY_HOPS: "1"`). A Swarm can move the app to another node, away from a node-local `/data` volume, so the stack sets its own key: provide `DB_PASSWORD` and `SECRET_KEY` in the environment (or mount a Docker secret and set `SECRET_KEY_FILE`):
```bash
DB_PASSWORD=... SECRET_KEY=... docker stack deploy -c docker-compose.prod.yml grimoire
@@ -96,13 +95,16 @@ Back up the database with **Settings → Data → Scheduled backups** ([Backups]
## Behind a reverse proxy
Grimoire doesn't terminate TLS. Put it behind Nginx, Traefik or Caddy, forward to port 5000, and keep port 5000 off the internet. Set `SECURE_COOKIES=true`, `TRUST_PROXY_HEADERS=true` and `BASE_URL`.
Grimoire doesn't terminate TLS. Put it behind Nginx, Traefik or Caddy, forward to port 5000, and keep port 5000 off the internet. Set `BASE_URL`, then set the proxy count to the number of proxies a request passes through: one proxy is `1`, the default; Cloudflare's proxied DNS in front of your own proxy is `2`.
**Settings → Config → Reverse proxy** sets the count and checks it against your own request. It shows the address Grimoire reads you as, and what each count from 0 to 3 would read. Pick the count that shows your own address. When a request comes through Cloudflare, the section names the count that reads the address Cloudflare reports, with a button that sets it. `TRUSTED_PROXY_HOPS` in the environment is only the starting value: a count saved in Settings wins, and **Use the environment's** goes back to it.
A count that is too low makes every visitor read as the proxy, so they share one sign-in rate limit and a few bad sign-ins block everyone. The "too many attempts" message says so and points here. The block on sign-ins lifts after a minute; an admin who is already signed in can fix the count at once.
```nginx
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
@@ -112,12 +114,16 @@ location / {
}
```
With `TRUST_PROXY_HEADERS=true`, make sure the proxy replaces any `X-Forwarded-For` the client sends.
Each proxy appends its entry to `X-Forwarded-For` and `X-Forwarded-Proto`, so Grimoire reads the entry that many in from the right: the one your own proxy wrote. Whatever a client puts to the left of it is ignored. A header with fewer entries than that (a LAN road with one proxy beside a Cloudflare road with two) is read at its leftmost entry, the one the first proxy wrote.
When that entry says `https`, the session cookie is marked `Secure` and the response carries `Strict-Transport-Security: max-age=31536000`. Over plain HTTP neither is sent, and Grimoire never redirects to HTTPS, so a LAN install keeps working.
A hop count higher than the real number of proxies lets a client choose its own address, so count them. With `0`, the headers are ignored and the socket peer is the client: use it when clients reach port 5000 directly.
## Security checklist
- **Keep the key.** Forge tokens and the backup destination's S3 secret are sealed under a key derived from `SECRET_KEY`, so a copy of the database alone can't read them. Unset, the instance makes a random key and keeps it in `/data/secret_key`, readable by its owner only; keep that volume. If the key changes (say, a restore onto an instance with a different key), Settings marks those credentials and asks for them again; nothing else breaks. The app warns at startup when `SECRET_KEY` is a public placeholder or `/data` is not a mounted volume, and refuses to start with `dev-secret-change-me` when `SECURE_COOKIES=true`.
- **`SECURE_COOKIES=true`** whenever Grimoire is served over HTTPS.
- **Keep the key.** Forge tokens and the backup destination's S3 secret are sealed under a key derived from `SECRET_KEY`, so a copy of the database alone can't read them. Unset, the instance makes a random key and keeps it in `/data/secret_key`, readable by its owner only; keep that volume. If the key changes (say, a restore onto an instance with a different key), Settings marks those credentials and asks for them again; nothing else breaks. The app warns at startup when `SECRET_KEY` is a public placeholder or `/data` is not a mounted volume, and refuses to start with a placeholder key (`dev-secret-change-me`, `change-me-in-production`).
- **The proxy count** (Settings → Config → Reverse proxy) matches the number of proxies in front of Grimoire, so rate limits and the audit log see the real client and the cookie is `Secure` over HTTPS. The section shows whether it does.
- **Registration** is open only for the first account. Invite people, or open it briefly from Settings.
- **Signing everyone else out**: changing a password ends that user's other sessions; Settings → Account has a button for it too.
- **API keys** are per user, shown once, and can be read-only. Revoke any you no longer use under Settings → MCP Access.
+4 -3
View File
@@ -66,6 +66,7 @@ Saved procedures, such as a drift audit or a DRY pass. The plugin syncs each one
The whole store is reachable through the MCP endpoint at `/mcp`, authenticated with an API key. The Claude Code plugin in this repo adds:
- hooks for session start, each prompt, before and after tool calls, the end of a turn, compaction and session end, all failing open if Grimoire is unreachable;
- a project fence: a session belongs to the project its starting directory is bound to. Toward any other project it can read anything and file an issue. Editing that project's files, committing or pushing in its repo, or changing its records first asks you, in every permission mode;
- skills for the working practices: using Grimoire, writing plans, systematic debugging, verification, brainstorming, reporting back, reusing code, shape accounting and family canon;
- your stored processes as skills.
@@ -85,8 +86,8 @@ Share a project, note or task with users or groups, as viewer, editor or admin.
## Export and backup
- **Personal export**: your notes and tasks as a Markdown ZIP (with YAML frontmatter) or JSON.
- **Admin backup and restore**, with ids remapped so a backup restores onto another instance.
- **Scheduled backups**: a daily, dated, uncompressed tar to a folder or an S3-compatible bucket, laid out so a deduplicating tool such as restic stores only what changed. `python -m grimoire.restore` brings a fresh instance back from one. See [Backups](backups.md).
- **Admin backup and restore**: a restore rolls the whole instance back to one of its own backups, after saving the current state, or brings a new instance back from any backup.
- **Scheduled backups**: a daily, dated, uncompressed tar to a folder or an S3-compatible bucket, laid out so a deduplicating tool such as restic stores only what changed. Restoring is in Settings, or `python -m grimoire.restore`. See [Backups](backups.md).
## Sign-in
@@ -102,7 +103,7 @@ Email and password, plus optional OIDC single sign-on (Authentik, Keycloak, ...)
| Integrations | SearXNG, git forge connections |
| Data | Export, backup and restore, scheduled backups (admin) |
| MCP Access | API keys and the command to connect Claude |
| Config (admin) | What's running, application URL, plugin marketplace, database maintenance, SMTP, forge webhook |
| Config (admin) | What's running, reverse proxy count (checked against your own request), application URL, plugin marketplace, database maintenance, SMTP, forge webhook |
| Shared areas (admin) | The canonical areas systems map to |
| Platforms (admin) | The platform catalogue family canon is grouped by |
| Users (admin) | Registration, invites, users |
+70 -1
View File
@@ -1,4 +1,4 @@
import { apiGet, apiPost, apiPut } from "@/api/client";
import { apiGet, apiPost, apiPostRaw, apiPut } from "@/api/client";
/**
* Scheduled backups — `/api/admin/backups`. One dated,
@@ -71,3 +71,72 @@ export function checkBackupDestination(
export function runBackupNow(): Promise<{ status: string }> {
return apiPost<{ status: string }>("/api/admin/backups/run", {});
}
// ── Restore: put the whole instance back to a full backup ─────────────────
export interface StoredBackup {
name: string;
size_bytes: number;
}
export interface RestoreCount {
kind: string;
now: number;
after: number;
}
export interface RestorePreview {
/** "fresh": an empty instance takes the backup. "rollback": this instance
* goes back to its own earlier backup. */
mode: "fresh" | "rollback";
exported_at: string | null;
counts: RestoreCount[];
}
export interface RestoreResult extends RestorePreview {
status: "ok";
restored: Record<string, number>;
safety_backup: { file: string; size_bytes: number; where: string; note?: string };
}
/** A backup at the destination, by name, or a file picked from this computer. */
export type RestoreFrom = { source: string } | { file: File };
// Reading, checking and writing the whole store is slow by design; bounded,
// but in minutes.
const RESTORE_TIMEOUT_MS = 10 * 60 * 1000;
export function listRestoreSources(): Promise<{ backups: StoredBackup[]; error?: string }> {
return apiGet("/api/admin/restore/sources", { timeoutMs: 60_000 });
}
async function restoreCall<T>(path: string, from: RestoreFrom, query: Record<string, string> = {}): Promise<T> {
const params = new URLSearchParams(query);
if ("source" in from) {
params.set("source", from.source);
return apiPostRaw<T>(`${path}?${params}`, null, null, { timeoutMs: RESTORE_TIMEOUT_MS });
}
const qs = params.toString() ? `?${params}` : "";
const isTar = from.file.name.toLowerCase().endsWith(".tar");
// The JSON download is parsed first, so a damaged file fails here, before
// the upload.
const body = isTar ? from.file : JSON.stringify(JSON.parse(await from.file.text()));
return apiPostRaw<T>(`${path}${qs}`, body, isTar ? "application/x-tar" : "application/json",
{ timeoutMs: RESTORE_TIMEOUT_MS });
}
export function previewRestore(from: RestoreFrom): Promise<RestorePreview> {
return restoreCall<RestorePreview>("/api/admin/restore/preview", from);
}
export function restoreBackup(from: RestoreFrom): Promise<RestoreResult> {
return restoreCall<RestoreResult>("/api/admin/restore", from, { confirm: "rollback" });
}
/** When a backup named `grimoire-20261015T020000Z.tar` was taken. */
export function backupTakenAt(name: string): Date | null {
const m = /(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z/.exec(name);
if (!m) return null;
return new Date(Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]));
}
+9
View File
@@ -156,6 +156,15 @@ export function apiPost<T>(path: string, body: unknown, opts?: RequestOpts): Pro
return request<T>(path, { method: "POST", headers: JSON_HEADERS, body: JSON.stringify(body) }, opts);
}
/** A POST whose body is sent as it is (a file, or text already serialised),
* under the same deadline and error handling as every other call. */
export function apiPostRaw<T>(
path: string, body: BodyInit | null, contentType: string | null, opts?: RequestOpts,
): Promise<T> {
const headers = contentType ? { "Content-Type": contentType } : undefined;
return request<T>(path, { method: "POST", headers, body }, opts);
}
export function apiPut<T>(path: string, body: unknown, opts?: RequestOpts): Promise<T> {
return request<T>(path, { method: "PUT", headers: JSON_HEADERS, body: JSON.stringify(body) }, opts);
}
+17
View File
@@ -54,6 +54,15 @@ export interface RulebookTopic {
*/
export type RuleKind = "rule" | "preference";
/**
* What a rule does when it arrives, declared by its author. `inform` puts a
* line beside the work; `hold` makes the reply or act it governs wait for one
* read; `enforce` checks the act itself. A preference is always `inform`.
*/
export type RuleEnforcement = "enforce" | "hold" | "inform";
/** How a rule ranks among rules of the same enforcement at a crowded moment. */
export type RuleSalience = "high" | "normal" | "low";
/** A new record opened from somewhere that already knows what it is for —
* "Adjust this" on a reply shape opens a preference mounted on that shape's
* moment. The editor applies it once, when creating. */
@@ -70,6 +79,8 @@ export interface Rule {
title: string;
statement: string;
kind: RuleKind;
enforcement: RuleEnforcement;
salience: RuleSalience;
/** WHEN this rule fires — the trigger, not the instruction. */
when_to_apply: string;
why: string;
@@ -113,6 +124,10 @@ export interface RuleHeader {
topic_id: number | null;
/** Unconditional on the wire (services.rulebooks.rule_brief). */
kind: RuleKind;
/** Unconditional on the wire, like `kind`. */
enforcement: RuleEnforcement;
/** Present only when raised or lowered from `normal`. */
salience?: RuleSalience;
/** A date (YYYY-MM-DD), not a timestamp. */
updated_at: string | null;
when_to_apply?: string;
@@ -217,6 +232,8 @@ export interface RuleWrite {
/** Writable from the editor: a preference is not a lesser rule, it is a
* different force, and the person writing it is the one who knows which. */
kind: RuleKind;
enforcement: RuleEnforcement;
salience: RuleSalience;
when_to_apply: string;
why: string;
how_to_apply: string;
+39
View File
@@ -147,6 +147,45 @@
text-decoration: none;
}
/* A record reference — `#4286`, `milestone 639`, `rule 34`. Reads as a link in
running text rather than a chip: a work log cites a dozen of them, and a row
of pills would drown the sentence they sit in. */
.record-ref {
color: var(--fs-wikilink);
text-decoration: underline;
text-decoration-color: color-mix(in srgb, var(--fs-wikilink) 40%, transparent);
text-underline-offset: 0.15em;
font-variant-numeric: tabular-nums;
border-radius: var(--fs-radius-sm);
cursor: pointer;
}
.record-ref:hover {
text-decoration-color: currentColor;
}
/* Drawn with its title: the title reads as the link, the number after it is
the citation, quieter and never split across lines. */
.record-ref__id {
color: var(--fs-text-secondary);
font-size: 0.85em;
white-space: nowrap;
}
.record-ref:focus-visible {
outline: none;
box-shadow: var(--fs-focus-ring);
}
/* One the reader cannot open: missing, trashed or not shared. Still legible —
the number is part of the sentence — but plainly not a way through. */
.record-ref--missing {
color: var(--fs-text-tertiary-fg);
text-decoration-style: dashed;
text-decoration-color: var(--fs-text-tertiary);
cursor: default;
}
/* Task list */
.prose ul[data-type="taskList"] {
list-style: none;
-466
View File
@@ -1,466 +0,0 @@
<script setup lang="ts">
import { ref, computed, onMounted } from "vue";
import { apiGet, pinNoteVersion, unpinNoteVersion } from "@/api/client";
import DiffView from "@/components/DiffView.vue";
import { computeDiff, type DiffLine } from "@/utils/diff";
import { fmtStamp } from "@/utils/dateFormat";
interface NoteVersion {
id: number;
note_id: number;
title: string;
tags: string[];
body?: string;
pin_kind: "auto" | "manual" | null;
pin_label: string | null;
created_at: string;
}
const props = defineProps<{
noteId: number;
currentBody: string;
}>();
const emit = defineEmits<{
(e: 'restore', body: string, tags: string[]): void;
(e: 'close'): void;
}>();
const versions = ref<NoteVersion[]>([]);
const selectedVersion = ref<NoteVersion | null>(null);
const loading = ref(false);
const loadingDetail = ref(false);
const diff = computed<DiffLine[]>(() => {
if (!selectedVersion.value?.body) return [];
return computeDiff(props.currentBody, selectedVersion.value.body);
});
async function loadVersions() {
loading.value = true;
try {
const data = await apiGet<{ versions: NoteVersion[] }>(
`/api/notes/${props.noteId}/versions`
);
versions.value = data.versions;
if (versions.value.length > 0) {
await selectVersionItem(versions.value[0]);
}
} catch {
// silent
} finally {
loading.value = false;
}
}
async function selectVersionItem(v: NoteVersion) {
if (v.body !== undefined) {
selectedVersion.value = v;
return;
}
loadingDetail.value = true;
try {
const full = await apiGet<NoteVersion>(
`/api/notes/${props.noteId}/versions/${v.id}`
);
// Cache body back onto list item
const listItem = versions.value.find(x => x.id === v.id);
if (listItem) listItem.body = full.body;
selectedVersion.value = full;
} catch {
// silent
} finally {
loadingDetail.value = false;
}
}
function restore() {
if (!selectedVersion.value?.body) return;
emit('restore', selectedVersion.value.body, selectedVersion.value.tags ?? []);
}
// ── Pin / unpin / edit-label state ──────────────────────────────────────────
const editingLabel = ref(false);
const draftLabel = ref("");
const pinSaving = ref(false);
function startEditLabel() {
if (!selectedVersion.value) return;
draftLabel.value = selectedVersion.value.pin_label ?? "";
editingLabel.value = true;
}
function cancelEditLabel() {
editingLabel.value = false;
draftLabel.value = "";
}
async function savePin() {
if (!selectedVersion.value || pinSaving.value) return;
pinSaving.value = true;
try {
const updated = await pinNoteVersion(
props.noteId, selectedVersion.value.id, draftLabel.value || null,
);
// Reflect server state in the local list + selected version.
const idx = versions.value.findIndex(v => v.id === updated.id);
if (idx >= 0) {
versions.value[idx].pin_kind = updated.pin_kind;
versions.value[idx].pin_label = updated.pin_label;
}
if (selectedVersion.value) {
selectedVersion.value.pin_kind = updated.pin_kind;
selectedVersion.value.pin_label = updated.pin_label;
}
editingLabel.value = false;
} catch {
// silent — leaving the form open lets the user retry
} finally {
pinSaving.value = false;
}
}
async function unpinSelected() {
if (!selectedVersion.value || pinSaving.value) return;
pinSaving.value = true;
try {
await unpinNoteVersion(props.noteId, selectedVersion.value.id);
const idx = versions.value.findIndex(v => v.id === selectedVersion.value!.id);
if (idx >= 0) {
versions.value[idx].pin_kind = null;
versions.value[idx].pin_label = null;
}
if (selectedVersion.value) {
selectedVersion.value.pin_kind = null;
selectedVersion.value.pin_label = null;
}
} catch {
// silent
} finally {
pinSaving.value = false;
}
}
onMounted(loadVersions);
</script>
<template>
<teleport to="body">
<div class="modal-overlay" @click.self="emit('close')">
<div class="modal-card history-modal">
<div class="history-header">
<h3 class="history-title">Version History</h3>
<button class="history-close" aria-label="Close version history" @click="emit('close')">&times;</button>
</div>
<div class="history-body">
<!-- Left: version list -->
<div class="history-list">
<div v-if="loading" class="history-empty">Loading...</div>
<div v-else-if="!versions.length" class="history-empty">No versions yet.</div>
<div
v-for="v in versions"
:key="v.id"
:class="['history-item', { selected: selectedVersion?.id === v.id }]"
@click="selectVersionItem(v)"
>
<div class="history-item-title">
<span
v-if="v.pin_kind === 'manual'"
class="pin-badge pin-badge-manual"
:title="v.pin_label || 'Pinned'"
aria-label="manually pinned"
>●</span>
<span
v-else-if="v.pin_kind === 'auto'"
class="pin-badge pin-badge-auto"
:title="v.pin_label || 'Auto-pinned (stable)'"
aria-label="auto-pinned"
>◐</span>
{{ v.title || 'Untitled' }}
</div>
<div
v-if="v.pin_kind === 'manual' && v.pin_label"
class="history-item-label"
>{{ v.pin_label }}</div>
<div class="history-item-date">{{ fmtStamp(v.created_at) }}</div>
</div>
</div>
<!-- Right: diff -->
<div class="history-diff">
<div v-if="loadingDetail" class="history-empty">Loading version...</div>
<div v-else-if="!selectedVersion" class="history-empty">Select a version to compare.</div>
<template v-else>
<div class="version-pin-controls">
<!-- Label editor -->
<div v-if="editingLabel" class="pin-label-form">
<input
v-model="draftLabel"
maxlength="500"
type="text"
class="pin-label-input"
placeholder="Optional label (e.g. 'post-network-refresh runbook')"
/>
<button class="btn-pin-save" :disabled="pinSaving" @click="savePin">
{{ pinSaving ? "Saving…" : "Save" }}
</button>
<button class="btn-pin-cancel" @click="cancelEditLabel">Cancel</button>
</div>
<!-- Default: kind-aware action row -->
<div v-else class="pin-actions">
<span v-if="selectedVersion.pin_kind === 'manual'" class="pin-state">
<span class="pin-badge pin-badge-manual">●</span>
Manually pinned{{ selectedVersion.pin_label ? `: ${selectedVersion.pin_label}` : '' }}
</span>
<span v-else-if="selectedVersion.pin_kind === 'auto'" class="pin-state">
<span class="pin-badge pin-badge-auto">◐</span>
Auto-pinned{{ selectedVersion.pin_label ? `: ${selectedVersion.pin_label}` : '' }}
</span>
<button
v-if="selectedVersion.pin_kind === null"
class="btn-pin"
:disabled="pinSaving"
@click="startEditLabel"
>Pin version</button>
<button
v-else-if="selectedVersion.pin_kind === 'manual'"
class="btn-pin-edit"
:disabled="pinSaving"
@click="startEditLabel"
>Edit label</button>
<button
v-else
class="btn-pin"
:disabled="pinSaving"
@click="startEditLabel"
>Pin permanently</button>
<button
v-if="selectedVersion.pin_kind === 'manual'"
class="btn-unpin"
:disabled="pinSaving"
@click="unpinSelected"
>Unpin</button>
</div>
</div>
<DiffView :diff="diff" />
</template>
</div>
</div>
<div class="history-footer">
<button
class="btn-primary"
:disabled="!selectedVersion?.body"
@click="restore"
>Restore this version</button>
<button class="modal-btn" @click="emit('close')">Close</button>
</div>
</div>
</div>
</teleport>
</template>
<style scoped>
.history-modal {
max-width: 900px;
width: 95%;
height: 80vh;
max-height: 700px;
display: flex;
flex-direction: column;
padding: 0;
}
.history-header {
flex-shrink: 0;
display: flex;
align-items: center;
justify-content: space-between;
padding: 0.9rem 1.25rem;
border-bottom: 1px solid var(--fs-border-color);
}
.history-title {
margin: 0;
font-size: 1rem;
}
.history-close {
background: none;
border: none;
font-size: 1.25rem;
cursor: pointer;
color: var(--fs-text-tertiary);
line-height: 1;
padding: 0.1rem 0.3rem;
}
.history-close:hover { color: var(--fs-text-primary); }
.history-body {
flex: 1;
min-height: 0;
display: flex;
overflow: hidden;
}
.history-list {
width: 220px;
flex-shrink: 0;
border-right: 1px solid var(--fs-border-color);
overflow-y: auto;
}
.history-item {
padding: 0.6rem 0.9rem;
cursor: pointer;
border-left: 3px solid transparent;
border-bottom: 1px solid var(--fs-border-color);
}
.history-item:hover { background: var(--fs-surface-raised); }
.history-item.selected {
border-left-color: var(--fs-accent);
background: var(--fs-surface-raised);
}
.history-item-title {
font-size: 0.85rem;
font-weight: 500;
color: var(--fs-text-primary);
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.history-item-date {
font-size: 0.75rem;
color: var(--fs-text-tertiary);
margin-top: 0.15rem;
}
.history-diff {
flex: 1;
min-width: 0;
overflow: hidden;
display: flex;
flex-direction: column;
padding: 0.5rem;
}
.history-empty {
padding: 1rem;
font-size: 0.85rem;
color: var(--fs-text-tertiary);
}
.history-footer {
flex-shrink: 0;
display: flex;
gap: 0.5rem;
justify-content: flex-end;
padding: 0.75rem 1.25rem;
border-top: 1px solid var(--fs-border-color);
}
/* ── Pin badges + label rendering ───────────────────────────────────────── */
.pin-badge {
display: inline-block;
width: 0.7rem;
text-align: center;
margin-right: 0.35rem;
font-size: 0.85em;
line-height: 1;
}
.pin-badge-manual { color: var(--fs-accent); }
.pin-badge-auto { color: var(--fs-text-tertiary); }
.history-item-label {
font-size: 0.72rem;
color: var(--fs-accent);
font-style: italic;
margin-top: 0.15rem;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
/* ── Pin controls above the diff ────────────────────────────────────────── */
.version-pin-controls {
padding: 0.4rem 0.5rem 0.5rem;
border-bottom: 1px solid var(--fs-border-color);
font-size: 0.82rem;
}
.pin-actions {
display: flex;
align-items: center;
gap: 0.5rem;
flex-wrap: wrap;
}
.pin-state {
font-style: italic;
color: var(--fs-text-tertiary);
flex: 1;
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.btn-pin, .btn-pin-edit, .btn-unpin {
padding: 0.25rem 0.7rem;
font-size: 0.78rem;
background: transparent;
color: inherit;
border: 1px solid var(--fs-border-color);
border-radius: 999px;
cursor: pointer;
}
.btn-pin:hover:not(:disabled), .btn-pin-edit:hover:not(:disabled) {
background: rgba(99, 102, 241, 0.12);
border-color: var(--fs-accent);
}
.btn-unpin:hover:not(:disabled) {
background: rgba(239, 68, 68, 0.10);
border-color: rgba(239, 68, 68, 0.5);
}
.pin-label-form {
display: flex;
gap: 0.4rem;
align-items: center;
}
.pin-label-input {
flex: 1;
padding: 0.3rem 0.5rem;
font-size: 0.85rem;
background: var(--fs-surface-page);
border: 1px solid var(--fs-border-color);
border-radius: var(--fs-radius-sm);
color: inherit;
}
.pin-label-input:focus {
outline: none;
border-color: var(--fs-accent);
}
.btn-pin-save, .btn-pin-cancel {
padding: 0.3rem 0.7rem;
font-size: 0.78rem;
background: transparent;
color: inherit;
border: 1px solid var(--fs-border-color);
border-radius: var(--fs-radius-sm);
cursor: pointer;
}
.btn-pin-save:hover:not(:disabled) {
background: rgba(99, 102, 241, 0.12);
border-color: var(--fs-accent);
}
.btn-pin-save:disabled, .btn-pin-cancel:disabled,
.btn-pin:disabled, .btn-pin-edit:disabled, .btn-unpin:disabled {
opacity: 0.5;
cursor: progress;
}
</style>
@@ -1,258 +0,0 @@
<script setup lang="ts">
import { ref, computed } from "vue";
import { renderMarkdown } from "@/utils/markdown";
import type { DiffLine } from "@/composables/useAssist";
const props = defineProps<{
phase: "streaming" | "review";
label: string;
streamingText: string;
diff: DiffLine[];
proposedText: string;
}>();
const emit = defineEmits<{
accept: [];
reject: [];
cancel: [];
}>();
const showFullText = ref(false);
const renderedStreaming = computed(() => renderMarkdown(props.streamingText));
const renderedProposed = computed(() => renderMarkdown(props.proposedText));
const markers: Record<DiffLine["type"], string> = {
equal: " ",
delete: "−",
insert: "+",
};
</script>
<template>
<!-- ── Streaming ───────────────────────────────────────────────── -->
<div v-if="phase === 'streaming'" class="iap iap-streaming">
<div class="iap-header">
<span class="iap-pulse"></span>
<span class="iap-label">{{ label }}</span>
<button class="iap-btn-cancel" @click="emit('cancel')">Cancel</button>
</div>
<div class="iap-stream-preview prose" v-html="renderedStreaming"></div>
<div v-if="!streamingText" class="iap-waiting">Waiting for model…</div>
</div>
<!-- ── Review ─────────────────────────────────────────────────── -->
<div v-else-if="phase === 'review'" class="iap iap-review">
<div class="iap-header">
<span class="iap-review-title">Proposed changes</span>
<button class="iap-btn-toggle" @click="showFullText = !showFullText">
{{ showFullText ? "Show diff" : "Show full text" }}
</button>
<div class="iap-actions">
<button class="iap-btn-accept" @click="emit('accept')">✓ Accept</button>
<button class="iap-btn-reject" @click="emit('reject')">✗ Reject</button>
</div>
</div>
<!-- Diff view -->
<div v-if="!showFullText" class="iap-diff">
<div
v-for="(line, i) in diff"
:key="i"
:class="['iap-diff-line', `iap-diff-${line.type}`]"
>
<span class="iap-diff-marker">{{ markers[line.type] }}</span>
<span class="iap-diff-text">{{ line.text }}</span>
</div>
<div v-if="!diff.length" class="iap-diff-empty">No changes.</div>
</div>
<!-- Full text view -->
<div v-else class="iap-full-text prose" v-html="renderedProposed"></div>
</div>
</template>
<style scoped>
.iap {
border-radius: var(--fs-radius-sm);
margin-bottom: 0.75rem;
overflow: hidden;
border: 1px solid var(--fs-border-color);
background: var(--fs-surface-page);
}
/* ── Header ── */
.iap-header {
display: flex;
align-items: center;
gap: 0.5rem;
padding: 0.45rem 0.75rem;
font-size: 0.85rem;
border-bottom: 1px solid var(--fs-border-color);
background: var(--fs-surface-raised);
}
/* ── Streaming ── */
.iap-streaming {
border-color: var(--fs-accent);
}
.iap-streaming .iap-header {
background: color-mix(in srgb, var(--fs-accent) 8%, var(--fs-surface-raised));
}
.iap-pulse {
display: inline-block;
width: 8px;
height: 8px;
border-radius: 50%;
background: var(--fs-accent);
flex-shrink: 0;
animation: iap-pulse 1.2s ease-in-out infinite;
}
@keyframes iap-pulse {
0%, 100% { opacity: 1; transform: scale(1); }
50% { opacity: 0.4; transform: scale(0.8); }
}
.iap-label {
flex: 1;
font-weight: 500;
color: var(--fs-text-primary);
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.iap-btn-cancel {
background: none;
border: 1px solid var(--fs-border-color);
color: var(--fs-text-secondary);
border-radius: var(--fs-radius-sm);
padding: 0.15rem 0.5rem;
cursor: pointer;
font-size: 0.8rem;
font-family: inherit;
flex-shrink: 0;
}
.iap-btn-cancel:hover {
border-color: var(--fs-error);
color: var(--fs-error);
}
.iap-stream-preview {
padding: 0.75rem;
font-size: 0.9rem;
min-height: 2.5rem;
max-height: 320px;
overflow-y: auto;
}
.iap-waiting {
padding: 0.75rem;
font-size: 0.85rem;
color: var(--fs-text-tertiary);
}
/* ── Review ── */
.iap-review-title {
flex: 1;
font-weight: 600;
color: var(--fs-text-primary);
}
.iap-btn-toggle {
background: none;
border: 1px solid var(--fs-border-color);
color: var(--fs-text-secondary);
border-radius: var(--fs-radius-sm);
padding: 0.15rem 0.5rem;
cursor: pointer;
font-size: 0.78rem;
font-family: inherit;
}
.iap-btn-toggle:hover {
border-color: var(--fs-accent);
color: var(--fs-accent);
}
.iap-actions {
display: flex;
gap: 0.35rem;
}
.iap-btn-accept,
.iap-btn-reject {
border: none;
border-radius: var(--fs-radius-sm);
padding: 0.2rem 0.65rem;
cursor: pointer;
font-size: 0.8rem;
font-family: inherit;
font-weight: var(--fs-weight-medium);
}
.iap-btn-accept {
background: var(--fs-success);
color: var(--fs-text-on-action);
}
.iap-btn-accept:hover { opacity: 0.85; }
.iap-btn-reject {
background: var(--fs-surface-raised);
color: var(--fs-text-secondary);
border: 1px solid var(--fs-border-color);
}
.iap-btn-reject:hover {
border-color: var(--fs-error);
color: var(--fs-error);
}
/* ── Diff ── */
.iap-diff {
font-family: ui-monospace, "Cascadia Code", "Fira Mono", monospace;
font-size: 0.82rem;
line-height: 1.6;
max-height: 440px;
overflow-y: auto;
padding: 0.4rem 0;
}
.iap-diff-line {
display: flex;
gap: 0.5rem;
padding: 0 0.75rem;
white-space: pre-wrap;
word-break: break-word;
}
.iap-diff-equal { color: var(--fs-text-tertiary); }
.iap-diff-delete {
background: color-mix(in srgb, var(--fs-error) 10%, transparent);
color: var(--fs-error-fg);
}
.iap-diff-insert {
background: color-mix(in srgb, var(--fs-success) 10%, transparent);
color: var(--fs-success-fg);
}
.iap-diff-marker {
width: 1ch;
flex-shrink: 0;
font-weight: 700;
user-select: none;
}
.iap-diff-empty {
padding: 0.75rem;
color: var(--fs-text-tertiary);
font-size: 0.85rem;
font-family: inherit;
}
/* ── Full text ── */
.iap-full-text {
padding: 0.75rem;
font-size: 0.9rem;
max-height: 440px;
overflow-y: auto;
}
</style>
-168
View File
@@ -1,168 +0,0 @@
<script setup lang="ts">
import { useRouter } from "vue-router";
import type { Note } from "@/types/note";
import TagPill from "@/components/TagPill.vue";
import { relativeTime } from "@/composables/useRelativeTime";
import { renderPreview } from "@/utils/markdown";
const props = defineProps<{ note: Note; compact?: boolean }>();
const emit = defineEmits<{ "tag-click": [tag: string] }>();
const router = useRouter();
function onTagClick(tag: string) {
emit("tag-click", tag);
}
function goEdit() {
router.push(`/notes/${props.note.id}/edit`);
}
</script>
<template>
<router-link :to="`/notes/${note.id}`" :class="['note-card', { compact }]">
<!-- Compact: single row -->
<template v-if="compact">
<span class="note-title-compact">{{ note.title || "Untitled" }}</span>
<div class="note-tags-compact">
<TagPill
v-for="tag in note.tags.slice(0, 3)"
:key="tag"
:tag="tag"
@click.stop="onTagClick(tag)"
/>
</div>
<span class="timestamp-compact">{{ relativeTime(note.updated_at) }}</span>
</template>
<!-- Full: original layout -->
<template v-else>
<div class="note-top">
<h3 class="note-title">{{ note.title || "Untitled" }}</h3>
<button class="btn-edit" title="Edit" @click.prevent.stop="goEdit">Edit</button>
</div>
<div v-if="note.body" class="note-preview prose" v-html="renderPreview(note.body)"></div>
<div class="note-meta">
<TagPill
v-for="tag in note.tags"
:key="tag"
:tag="tag"
@click.stop="onTagClick(tag)"
/>
<span class="timestamp">{{ relativeTime(note.updated_at) }}</span>
</div>
</template>
</router-link>
</template>
<style scoped>
.note-card {
display: block;
padding: 1rem;
border-radius: var(--fs-radius-lg);
text-decoration: none;
color: inherit;
background: var(--fs-surface-raised);
box-shadow: 0 1px 4px rgba(0, 0, 0, 0.06), 0 0 0 1px color-mix(in srgb, var(--fs-accent) 6%, transparent);
transition: box-shadow 0.2s, transform 0.18s ease;
}
.note-card:hover {
box-shadow: 0 4px 16px rgba(0, 0, 0, 0.10), 0 0 0 1px color-mix(in srgb, var(--fs-accent) 14.0%, transparent);
transform: translateY(-2px);
}
/* Compact single-row layout */
.note-card.compact {
display: flex;
align-items: center;
gap: 0.6rem;
padding: 0.45rem 0.75rem;
background: var(--fs-surface-raised);
box-shadow: none;
border-radius: 0;
border-bottom: 1px solid var(--fs-border-color);
transform: none !important;
}
.note-card.compact:first-child {
border-top: 1px solid var(--fs-border-color);
}
.note-card.compact:hover {
box-shadow: none;
background: color-mix(in srgb, var(--fs-accent) 4%, transparent);
transform: none;
}
.note-title-compact {
font-size: 0.9rem;
font-weight: 500;
flex: 1;
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.note-tags-compact {
display: flex;
gap: 0.3rem;
flex-shrink: 0;
}
.timestamp-compact {
font-size: 0.72rem;
color: var(--fs-text-tertiary);
flex-shrink: 0;
white-space: nowrap;
}
/* Full layout */
.note-top {
display: flex;
align-items: center;
justify-content: space-between;
gap: 0.5rem;
margin-bottom: 0.25rem;
}
.note-title {
margin: 0;
font-size: 1.1rem;
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.btn-edit {
flex-shrink: 0;
padding: 0.25rem 0.6rem;
font-size: 0.8rem;
background: var(--fs-surface-raised);
color: var(--fs-text-secondary);
border: 1px solid var(--fs-border-color);
border-radius: var(--fs-radius-sm);
cursor: pointer;
transition: color 0.15s, border-color 0.15s;
}
.btn-edit:hover {
color: var(--fs-accent);
border-color: var(--fs-accent);
}
.note-preview {
margin: 0 0 0.5rem;
color: var(--fs-text-secondary);
font-size: 0.9rem;
max-height: 7.5em;
overflow: hidden;
position: relative;
-webkit-mask-image: linear-gradient(to bottom, black 60%, transparent 100%);
mask-image: linear-gradient(to bottom, black 60%, transparent 100%);
}
.note-meta {
display: flex;
align-items: center;
gap: 0.5rem;
flex-wrap: wrap;
}
.timestamp {
margin-left: auto;
font-size: 0.75rem;
color: var(--fs-text-tertiary);
}
</style>
@@ -0,0 +1,278 @@
<script setup lang="ts">
/**
* Restore: put the whole instance back to a full backup.
*
* Choose a backup (one at the backup destination, or a file from this
* computer), see what it would change, type the confirmation, run it. On a
* live instance this is a rollback to the instance's own earlier backup; on a
* new, empty one it takes the backup in. Either way the server backs up the
* current state first and signs everyone out afterwards.
*/
import { computed, onMounted, ref } from "vue";
import { apiErrorMessage } from "@/api/client";
import {
backupTakenAt, listRestoreSources, previewRestore, restoreBackup,
type RestoreFrom, type RestorePreview, type RestoreResult, type StoredBackup,
} from "@/api/backups";
import { formatBytes } from "@/utils/bytes";
const emit = defineEmits<{ close: [] }>();
const CONFIRM_WORDS = "roll back";
type Step = "choose" | "checking" | "preview" | "running" | "done";
const step = ref<Step>("choose");
const sources = ref<StoredBackup[]>([]);
const sourcesError = ref("");
const sourcesLoading = ref(true);
const chosen = ref<RestoreFrom | null>(null);
const chosenLabel = ref("");
const preview = ref<RestorePreview | null>(null);
const result = ref<RestoreResult | null>(null);
const error = ref("");
const typed = ref("");
const fileInput = ref<HTMLInputElement | null>(null);
const confirmed = computed(() => typed.value.trim().toLowerCase() === CONFIRM_WORDS);
function when(value: Date | string | null | undefined): string {
if (!value) return "an unknown date";
const date = typeof value === "string" ? new Date(value) : value;
return Number.isNaN(date.getTime()) ? "an unknown date" : date.toLocaleString();
}
onMounted(async () => {
try {
const answer = await listRestoreSources();
sources.value = answer.backups;
sourcesError.value = answer.error ?? "";
} catch (e) {
sourcesError.value = apiErrorMessage(e, "Could not list the backups at the destination.");
} finally {
sourcesLoading.value = false;
}
});
async function check(from: RestoreFrom, label: string) {
chosen.value = from;
chosenLabel.value = label;
error.value = "";
typed.value = "";
step.value = "checking";
try {
preview.value = await previewRestore(from);
step.value = "preview";
} catch (e) {
error.value = apiErrorMessage(e, "That backup could not be read.");
step.value = "choose";
}
}
function pickFile(event: Event) {
const file = (event.target as HTMLInputElement).files?.[0];
if (fileInput.value) fileInput.value.value = "";
if (file) check({ file }, file.name);
}
async function run() {
if (!chosen.value || !confirmed.value) return;
error.value = "";
step.value = "running";
try {
result.value = await restoreBackup(chosen.value);
step.value = "done";
} catch (e) {
error.value = apiErrorMessage(e, "The restore failed. Nothing was changed.");
step.value = "preview";
}
}
function finish() {
// Every session ended with the restore, this one included.
window.location.assign("/login");
}
</script>
<template>
<teleport to="body">
<div class="modal-overlay" @click="step === 'running' || step === 'done' ? null : emit('close')">
<div class="modal-card restore-card" @click.stop>
<template v-if="step === 'choose' || step === 'checking'">
<h3 class="modal-title">Restore from a backup</h3>
<p class="modal-message">
Puts the whole instance back to the moment the backup was taken, for every user.
You'll see what changes before anything happens.
</p>
<p v-if="error" class="restore-error" role="alert">{{ error }}</p>
<h4 class="restore-subhead">At the backup destination</h4>
<p v-if="sourcesLoading" class="restore-muted">Looking for backups…</p>
<p v-else-if="sourcesError" class="restore-muted">{{ sourcesError }}</p>
<p v-else-if="!sources.length" class="restore-muted">No backups there yet.</p>
<ul v-else class="restore-sources">
<li v-for="b in sources" :key="b.name">
<button
class="restore-source"
:disabled="step === 'checking'"
@click="check({ source: b.name }, when(backupTakenAt(b.name)))"
>
<span>{{ when(backupTakenAt(b.name)) }}</span>
<span class="restore-muted">{{ formatBytes(b.size_bytes) }}</span>
</button>
</li>
</ul>
<h4 class="restore-subhead">From this computer</h4>
<p class="restore-muted">
A backup file (.tar) or the Full Backup download (.json). Uploads are size-limited;
a large file restores from the destination above, or with
<code>python -m grimoire.restore</code>.
</p>
<div class="modal-actions restore-actions-left">
<button class="modal-btn" :disabled="step === 'checking'" @click="fileInput?.click()">
Choose a file…
</button>
<input ref="fileInput" type="file" accept=".json,.tar" class="hidden-file-input" @change="pickFile" />
</div>
<p v-if="step === 'checking'" class="restore-muted">Reading {{ chosenLabel }}…</p>
<div class="modal-actions">
<button class="modal-btn" @click="emit('close')">Cancel</button>
</div>
</template>
<template v-else-if="(step === 'preview' || step === 'running') && preview">
<h3 class="modal-title">
{{ preview.mode === "rollback" ? "Roll back to this backup?" : "Restore this backup?" }}
</h3>
<p class="modal-message">
<template v-if="preview.mode === 'rollback'">
Everything goes back to {{ when(preview.exported_at) }}, for every user. Anything made
since is removed, edits since are undone, and records deleted since come back.
</template>
<template v-else>
This instance has no records yet, so it takes the backup from {{ when(preview.exported_at) }} as it is.
</template>
The current state is backed up first, and everyone is signed out afterwards.
</p>
<table class="restore-counts">
<thead><tr><th></th><th>Now</th><th>After</th></tr></thead>
<tbody>
<tr v-for="c in preview.counts" :key="c.kind">
<td>{{ c.kind }}</td><td>{{ c.now }}</td><td>{{ c.after }}</td>
</tr>
</tbody>
</table>
<p v-if="error" class="restore-error" role="alert">{{ error }}</p>
<label class="restore-confirm">
Type <strong>{{ CONFIRM_WORDS }}</strong> to continue
<input v-model="typed" class="fs-input input" :disabled="step === 'running'" autocomplete="off" />
</label>
<div class="modal-actions">
<button class="modal-btn" :disabled="step === 'running'" @click="step = 'choose'">Back</button>
<button
class="modal-btn modal-btn-danger"
:disabled="!confirmed || step === 'running'"
@click="run"
>{{ step === "running" ? "Restoring…" : preview.mode === "rollback" ? "Roll back" : "Restore" }}</button>
</div>
</template>
<template v-else-if="step === 'done' && result">
<h3 class="modal-title">Restored</h3>
<p class="modal-message">
The instance is back to {{ when(result.exported_at) }}.
The state it replaced was saved as <code>{{ result.safety_backup.file }}</code>
in {{ result.safety_backup.where }}.
<template v-if="result.safety_backup.note"> {{ result.safety_backup.note }}</template>
Search is being rebuilt in the background. Everyone has been signed out, so sign in again.
</p>
<div class="modal-actions">
<button class="modal-btn modal-btn-primary" @click="finish">Sign in again</button>
</div>
</template>
</div>
</div>
</teleport>
</template>
<style scoped>
.restore-card {
max-width: 34rem;
max-height: 85vh;
overflow-y: auto;
}
.restore-subhead {
margin: 1rem 0 0.4rem;
font-size: 0.9rem;
}
.restore-muted {
font-size: 0.85rem;
color: var(--fs-text-secondary);
margin: 0 0 0.5rem;
}
.restore-error {
font-size: 0.85rem;
color: var(--fs-action-destructive);
margin: 0 0 0.75rem;
}
.restore-sources {
list-style: none;
margin: 0 0 0.5rem;
padding: 0;
max-height: 14rem;
overflow-y: auto;
border: 1px solid var(--fs-border-color);
border-radius: var(--fs-radius-sm);
}
.restore-source {
display: flex;
justify-content: space-between;
width: 100%;
padding: 0.45rem 0.7rem;
border: none;
border-bottom: 1px solid var(--fs-border-color);
background: none;
color: var(--fs-text-primary);
font: inherit;
font-size: 0.875rem;
text-align: left;
cursor: pointer;
}
.restore-sources li:last-child .restore-source {
border-bottom: none;
}
.restore-source:hover:not(:disabled) {
background: var(--fs-surface-hover);
}
.restore-actions-left {
justify-content: flex-start;
margin-bottom: 1rem;
}
.restore-counts {
width: 100%;
border-collapse: collapse;
font-size: 0.875rem;
margin: 0 0 1rem;
}
.restore-counts th,
.restore-counts td {
text-align: right;
padding: 0.25rem 0.5rem;
border-bottom: 1px solid var(--fs-border-color);
}
.restore-counts th:first-child,
.restore-counts td:first-child {
text-align: left;
}
.hidden-file-input {
display: none;
}
.restore-confirm {
display: flex;
flex-direction: column;
gap: 0.35rem;
font-size: 0.875rem;
margin: 0 0 1rem;
}
</style>
@@ -0,0 +1,309 @@
<script setup lang="ts">
import { computed, onMounted, ref } from "vue";
import { apiGet, apiPut, apiErrorMessage } from "@/api/client";
import { useToastStore } from "@/stores/toast";
/**
* How many reverse proxies stand in front of Grimoire, checked against the
* admin's own request.
*
* Each proxy appends to X-Forwarded-For, and Grimoire reads the entry this many
* in from the right as the visitor's address. Every sign-in rate limit and
* audit line keys on that address, and the scheme read the same way decides
* whether the session cookie is Secure. Too low a count makes every visitor
* read as the proxy, so they share one rate limit and one bad sign-in run
* blocks everyone. Behind Cloudflare's proxied DNS the usual count is 2.
*/
interface ReadoutRow { hops: number; client: string; https: boolean }
interface Readout {
peer: string;
forwarded_for: string[];
forwarded_proto: string[];
cloudflare: boolean;
cloudflare_client: string | null;
rows: ReadoutRow[];
suggested: number | null;
}
interface ProxyConfig {
hops: number;
source: "setting" | "env" | "default";
env_hops: number;
max_hops: number;
readout: Readout;
}
const toast = useToastStore();
const config = ref<ProxyConfig | null>(null);
const loadError = ref("");
const draft = ref<number>(1);
const saving = ref(false);
const saved = ref(false);
async function load() {
loadError.value = "";
try {
config.value = await apiGet<ProxyConfig>("/api/admin/proxy");
draft.value = config.value.hops;
} catch (e) {
loadError.value = apiErrorMessage(e, "The proxy settings could not be loaded.");
}
}
async function save(hops: number | null) {
saving.value = true;
saved.value = false;
try {
config.value = await apiPut<ProxyConfig>("/api/admin/proxy", { hops });
draft.value = config.value.hops;
saved.value = true;
setTimeout(() => (saved.value = false), 2000);
} catch (e) {
toast.show(apiErrorMessage(e, "Failed to save the proxy count"), "error");
} finally {
saving.value = false;
}
}
const readout = computed(() => config.value?.readout ?? null);
const inForce = computed(() => readout.value?.rows.find((r) => r.hops === config.value?.hops) ?? null);
// The verdict that leads the section. A Cloudflare request names the count to
// set, since Cloudflare reports the visitor's address; any other road can only
// show the address read and let the admin judge whether it is theirs.
const verdict = computed<"set-suggested" | "cloudflare-unmatched" | "check" | null>(() => {
const r = readout.value;
if (!r || !config.value) return null;
if (r.cloudflare && r.suggested !== null && r.suggested !== config.value.hops) return "set-suggested";
if (r.cloudflare && r.suggested === null) return "cloudflare-unmatched";
return "check";
});
const sourceLabel = computed(() => {
const c = config.value;
if (!c) return "";
if (c.source === "setting") return "Saved here.";
if (c.source === "env") return `From TRUSTED_PROXY_HOPS in the environment (${c.env_hops}).`;
return "The default.";
});
const draftValid = computed(() =>
Number.isInteger(draft.value) && draft.value >= 0 && draft.value <= (config.value?.max_hops ?? 5),
);
onMounted(load);
</script>
<template>
<div class="proxy-settings">
<p v-if="loadError" class="error-msg">
{{ loadError }}
<button type="button" class="btn-ghost btn-compact" @click="load">Try again</button>
</p>
<p v-else-if="!config" class="state-msg">Reading this request&hellip;</p>
<template v-else-if="readout">
<div v-if="verdict === 'set-suggested'" class="proxy-warning" role="alert">
<p class="proxy-warning-title">Set the proxy count to {{ readout.suggested }}</p>
<p class="proxy-warning-body">
This request came through Cloudflare, which reports your address as
<code>{{ readout.cloudflare_client }}</code>. At {{ config.hops }}, Grimoire reads
<code>{{ inForce?.client }}</code> instead, so visitors share Cloudflare's addresses
and one sign-in limit.
</p>
<button type="button" class="btn-primary" :disabled="saving" @click="save(readout.suggested)">
Use {{ readout.suggested }}
</button>
</div>
<div v-else-if="verdict === 'cloudflare-unmatched'" class="proxy-warning" role="alert">
<p class="proxy-warning-title">This request came through Cloudflare</p>
<p class="proxy-warning-body">
No count reads the address Cloudflare reports for you. Check the forwarding chain below,
and that your own proxy passes Cloudflare's <code>X-Forwarded-For</code> on.
</p>
</div>
<p v-else class="proxy-verdict">
Grimoire reads this request as coming from <code>{{ inForce?.client || "an unknown address" }}</code>
<template v-if="inForce?.https"> over HTTPS</template>. If that is your address, the count
is right. If it is your proxy's, raise the count.
</p>
<div class="field proxy-field">
<label for="proxy-hops">Proxies in front of Grimoire</label>
<div class="proxy-input-row">
<input
id="proxy-hops"
v-model.number="draft"
type="number"
min="0"
:max="config.max_hops"
step="1"
class="fs-input input proxy-hops-input"
/>
<button
type="button"
class="btn-primary"
:disabled="saving || !draftValid || draft === config.hops"
@click="save(draft)"
>
{{ saving ? "Saving..." : "Save" }}
</button>
<button
v-if="config.source === 'setting'"
type="button"
class="btn-ghost"
:disabled="saving"
@click="save(null)"
>
Use the environment's ({{ config.env_hops }})
</button>
<span v-if="saved" class="saved-msg">Saved. It applies to the next request.</span>
</div>
<p class="field-hint">
{{ sourceLabel }} One proxy (Traefik, Nginx, Caddy) is 1. Cloudflare in front of your own
proxy is 2. 0 ignores the forwarding headers and uses the connecting address.
</p>
</div>
<table class="proxy-table">
<caption>What each count makes of this request</caption>
<thead>
<tr><th class="num">Count</th><th>Reads you as</th><th>HTTPS</th><th></th></tr>
</thead>
<tbody>
<tr
v-for="row in readout.rows"
:key="row.hops"
:class="{ 'proxy-row-current': row.hops === config.hops }"
>
<td class="num">{{ row.hops }}</td>
<td><code>{{ row.client || "unknown" }}</code></td>
<td>{{ row.https ? "yes" : "no" }}</td>
<td class="proxy-row-tags">
<span v-if="row.hops === config.hops" class="proxy-tag">in force</span>
<span v-if="row.hops === readout.suggested && row.hops !== config.hops" class="proxy-tag proxy-tag-suggested">
suggested
</span>
</td>
</tr>
</tbody>
</table>
<dl class="proxy-chain">
<dt>Connecting address</dt>
<dd><code>{{ readout.peer || "unknown" }}</code></dd>
<dt>X-Forwarded-For</dt>
<dd v-if="readout.forwarded_for.length"><code>{{ readout.forwarded_for.join(", ") }}</code></dd>
<dd v-else class="proxy-absent">not sent</dd>
<dt>X-Forwarded-Proto</dt>
<dd v-if="readout.forwarded_proto.length"><code>{{ readout.forwarded_proto.join(", ") }}</code></dd>
<dd v-else class="proxy-absent">not sent</dd>
</dl>
</template>
</div>
</template>
<style scoped>
.proxy-warning {
margin-bottom: var(--fs-space-4);
padding: var(--fs-space-3);
border: 1px solid var(--fs-warning);
border-radius: var(--fs-radius-md);
background: color-mix(in srgb, var(--fs-warning) 12%, var(--fs-surface-raised));
}
.proxy-warning-title {
margin: 0 0 var(--fs-space-2);
font-weight: 600;
color: var(--fs-warning-fg);
}
.proxy-warning-body {
margin: 0 0 var(--fs-space-3);
font-size: var(--fs-size-body-sm);
color: var(--fs-text-primary);
}
.proxy-verdict {
margin: 0 0 var(--fs-space-4);
font-size: var(--fs-size-body-sm);
color: var(--fs-text-primary);
}
.proxy-field {
margin-bottom: var(--fs-space-4);
}
.proxy-input-row {
display: flex;
align-items: center;
gap: var(--fs-space-3);
flex-wrap: wrap;
}
.proxy-hops-input {
width: 5rem;
}
.proxy-table {
width: 100%;
max-width: 560px;
border-collapse: collapse;
font-size: var(--fs-size-body-sm);
margin-bottom: var(--fs-space-4);
}
.proxy-table caption {
text-align: left;
font-size: var(--fs-size-label);
color: var(--fs-text-secondary);
margin-bottom: var(--fs-space-2);
}
.proxy-table th,
.proxy-table td {
text-align: left;
padding: var(--fs-space-1) var(--fs-space-3);
border-bottom: 1px solid var(--fs-border-color);
}
.proxy-table th {
font-size: var(--fs-size-tiny);
text-transform: uppercase;
letter-spacing: 0.04em;
color: var(--fs-text-tertiary);
font-weight: 500;
}
.proxy-table .num {
text-align: right;
font-variant-numeric: tabular-nums;
width: 4rem;
}
.proxy-row-current td {
background: var(--fs-surface-hover);
font-weight: 600;
}
.proxy-row-tags {
white-space: nowrap;
}
.proxy-tag {
display: inline-block;
padding: 0 var(--fs-space-2);
border-radius: var(--fs-radius-pill);
font-size: var(--fs-size-tiny);
font-weight: 500;
color: var(--fs-text-secondary);
border: 1px solid var(--fs-border-active);
}
.proxy-tag-suggested {
color: var(--fs-warning-fg);
border-color: var(--fs-warning);
}
.proxy-chain {
display: grid;
grid-template-columns: max-content 1fr;
gap: var(--fs-space-1) var(--fs-space-4);
margin: 0;
font-size: var(--fs-size-body-sm);
}
.proxy-chain dt {
color: var(--fs-text-secondary);
}
.proxy-chain dd {
margin: 0;
overflow-wrap: anywhere;
}
.proxy-absent {
font-style: italic;
color: var(--fs-text-tertiary);
}
</style>
@@ -0,0 +1,96 @@
<script setup lang="ts">
/**
* The end of a server-paged list: asks for the next page as the reader nears
* it, in place of a "Load more" button. The parent keeps the paging — what the
* next page is keyed on, whether one is in flight, whether the last one
* failed — and this owns the observing.
*
* <ScrollSentinel :cursor="more ? String(rows.length) : ''"
* :loading="loadingMore" :failed="moreFailed" @more="loadMore" />
*
* An empty cursor means the list is complete, and nothing renders.
*/
import { onBeforeUnmount, ref, watch } from "vue";
const props = defineProps<{ cursor: string; loading: boolean; failed?: boolean }>();
const emit = defineEmits<{ more: [] }>();
const sentinel = ref<HTMLElement | null>(null);
const visible = ref(false);
// One request per page. The observer reports every crossing, and a short last
// page leaves the sentinel on screen for good, so the cursor last asked for is
// remembered: a page is asked for once, and a failed one is not retried on
// every scroll, because a failure leaves the cursor where it was. Only
// Try again asks for it again.
let asked = "";
function pump() {
if (!visible.value || props.loading || props.failed || !props.cursor) return;
if (props.cursor === asked) return;
asked = props.cursor;
emit("more");
}
function retry() {
asked = props.cursor;
emit("more");
}
let observer: IntersectionObserver | undefined;
function observe(el: HTMLElement | null) {
observer?.disconnect();
observer = undefined;
if (!el) {
// Visibility and the cursor asked for go with the element. A list that
// starts over must not inherit "the end is on screen" from the one it
// replaced, and an offset cursor repeats from list to list, so "50" asked
// of the old list must not stop the new one asking for its own "50".
visible.value = false;
asked = "";
return;
}
observer = new IntersectionObserver(
(entries) => {
visible.value = entries.some((e) => e.isIntersecting);
pump();
},
// Extends the watched area a screen below the viewport, so the next page is
// asked for before the reader reaches the end rather than when they do.
{ rootMargin: "0px 0px 100% 0px" },
);
observer.observe(el);
}
// flush: "post": the template ref is only set once the DOM is patched.
watch(sentinel, observe, { flush: "post" });
// A page that lands without pushing the end off screen gives the observer
// nothing new to report, so carry on from the props, or the list stops early.
watch([() => props.cursor, () => props.loading, () => props.failed], pump);
onBeforeUnmount(() => observer?.disconnect());
</script>
<template>
<div v-if="cursor" class="sentinel">
<!-- The one case with a button: an observer re-firing on a failure would be
a request loop. -->
<p v-if="failed" class="sentinel-note sentinel-failed" role="alert">
Couldn’t load more.
<button type="button" class="btn-secondary btn-sm" @click="retry">Try again</button>
</p>
<template v-else>
<div ref="sentinel" class="sentinel-mark" aria-hidden="true"></div>
<p v-if="loading" class="sentinel-note" role="status">Loading more…</p>
</template>
</div>
</template>
<style scoped>
.sentinel { grid-column: 1 / -1; padding: 0.75rem 0; text-align: center; }
.sentinel-mark { height: 1px; }
.sentinel-note { margin: 0; font-size: 0.8rem; color: var(--fs-text-tertiary); }
.sentinel-failed { display: flex; align-items: center; justify-content: center; gap: 0.75rem; }
</style>
+2 -1
View File
@@ -2,6 +2,7 @@
import { ref, onMounted } from "vue";
import { apiGet, apiPost, apiPatch, apiDelete } from "@/api/client";
import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import type { TaskLog } from "@/types/task";
import { fmtStamp } from "@/utils/dateFormat";
@@ -131,7 +132,7 @@ onMounted(loadLogs);
<button class="btn-text" aria-label="Delete log entry" @click="deleteLog(log)">&times;</button>
</div>
</div>
<div class="log-content prose" v-html="renderMarkdown(log.content)"></div>
<div class="log-content prose" v-html="renderMarkdown(log.content)" v-record-refs></div>
</template>
</div>
@@ -1,683 +0,0 @@
<script setup lang="ts">
import { ref, computed, watch, onMounted, onUnmounted, nextTick } from "vue";
import type { Editor } from "@tiptap/vue-3";
import { apiGet, apiPatch, apiPost, apiDelete } from "@/api/client";
import { useToastStore } from "@/stores/toast";
import { useAutoSave } from "@/composables/useAutoSave";
import { useTagSuggestions } from "@/composables/useTagSuggestions";
import { useNotesStore } from "@/stores/notes";
import TiptapEditor from "@/components/TiptapEditor.vue";
import TagInput from "@/components/TagInput.vue";
import MarkdownToolbar from "@/components/MarkdownToolbar.vue";
import WordCount from "@/components/WordCount.vue";
import { Trash2, X } from "lucide-vue-next";
import { relativeTimeOrDate } from "@/composables/useRelativeTime";
const props = defineProps<{
projectId: number;
activeNoteId: number | null;
}>();
const emit = defineEmits<{ "note-loaded": [id: number] }>();
interface NoteItem {
id: number;
title: string;
tags: string[];
updated_at: string;
}
const toast = useToastStore();
const notesStore = useNotesStore();
// List state
const projectNotes = ref<NoteItem[]>([]);
const listLoading = ref(false);
const deletingId = ref<number | null>(null);
const pendingDelete = ref<number | null>(null);
const searchQuery = ref("");
const filteredNotes = computed(() => {
const q = searchQuery.value.trim().toLowerCase();
if (!q) return projectNotes.value;
return projectNotes.value.filter(
(n) => n.title.toLowerCase().includes(q) || n.tags?.some((t) => t.toLowerCase().includes(q))
);
});
function matchedTags(note: NoteItem): string[] {
const q = searchQuery.value.trim().toLowerCase();
if (!q) return [];
return (note.tags ?? []).filter(
(t) => t.toLowerCase().includes(q) && !note.title.toLowerCase().includes(q)
);
}
// Editor state
const editingId = ref<number | null>(null);
const noteTitle = ref("");
const noteBody = ref("");
const noteTags = ref<string[]>([]);
const dirty = ref(false);
const saving = ref(false);
const tagSuggestions = useTagSuggestions(noteTitle, noteBody, noteTags, () => { dirty.value = true; });
// New note inline creation
const showNewNoteInput = ref(false);
const newNoteTitle = ref("");
const creatingNote = ref(false);
const newNoteTitleRef = ref<HTMLInputElement | null>(null);
function _noteKey(pid: number) { return `workspace_note_${pid}`; }
async function startNewNote() {
showNewNoteInput.value = true;
newNoteTitle.value = "";
await nextTick();
newNoteTitleRef.value?.focus();
}
function cancelNewNote() {
showNewNoteInput.value = false;
newNoteTitle.value = "";
}
async function createNote() {
const title = newNoteTitle.value.trim();
if (!title || creatingNote.value) return;
creatingNote.value = true;
try {
const note = await apiPost<{ id: number; title: string; body: string; tags: string[]; updated_at: string }>(
"/api/notes",
{ title, project_id: props.projectId, body: "", is_task: false }
);
showNewNoteInput.value = false;
newNoteTitle.value = "";
await loadProjectNotes();
await openNote(note.id);
} catch {
toast.show("Failed to create note", "error");
} finally {
creatingNote.value = false;
}
}
// TipTap editor ref
const titleRef = ref<HTMLInputElement | null>(null);
const editorRef = ref<InstanceType<typeof TiptapEditor> | null>(null);
const tiptapEditor = computed<Editor | null>(() =>
(editorRef.value?.editor as Editor | undefined) ?? null
);
// Link suggestions
interface LinkSuggestion { note_id: number; title: string; count: number; }
const linkSuggestions = ref<LinkSuggestion[]>([]);
let linkCheckTimer: ReturnType<typeof setTimeout> | null = null;
async function fetchLinkSuggestions() {
if (!editingId.value || !noteBody.value) { linkSuggestions.value = []; return; }
try {
const res = await apiPost<{ suggestions: LinkSuggestion[] }>('/api/notes/link-suggestions', {
body: noteBody.value,
project_id: props.projectId,
exclude_note_id: editingId.value,
});
linkSuggestions.value = res.suggestions;
} catch {
linkSuggestions.value = [];
}
}
function scheduleLinkCheck() {
if (linkCheckTimer) clearTimeout(linkCheckTimer);
linkCheckTimer = setTimeout(fetchLinkSuggestions, 2500);
}
function applyWikilinkToText(text: string, title: string): string {
const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
const parts = text.split(/(\[\[[^\]]*\]\])/);
const pattern = new RegExp(`\\b${escaped}\\b`, 'gi');
return parts.map((part, i) =>
i % 2 === 0 ? part.replace(pattern, `[[${title}]]`) : part
).join('');
}
function applyLink(s: LinkSuggestion) {
noteBody.value = applyWikilinkToText(noteBody.value, s.title);
dirty.value = true;
linkSuggestions.value = linkSuggestions.value.filter(x => x.note_id !== s.note_id);
}
function applyAllLinks() {
let text = noteBody.value;
for (const s of linkSuggestions.value) text = applyWikilinkToText(text, s.title);
noteBody.value = text;
dirty.value = true;
linkSuggestions.value = [];
}
async function loadProjectNotes() {
listLoading.value = true;
try {
const data = await apiGet<{ notes: NoteItem[] }>(
`/api/projects/${props.projectId}/notes?type=note&limit=200`
);
projectNotes.value = data.notes ?? [];
} catch {
toast.show("Failed to load notes", "error");
} finally {
listLoading.value = false;
}
}
async function openNote(id: number) {
try {
const note = await apiGet<{ id: number; title: string; body: string; tags: string[]; updated_at: string }>(
`/api/notes/${id}`
);
editingId.value = note.id;
noteTitle.value = note.title;
noteBody.value = note.body ?? "";
noteTags.value = note.tags ?? [];
dirty.value = false;
tagSuggestions.dismissTagSuggestions();
linkSuggestions.value = [];
localStorage.setItem(_noteKey(props.projectId), String(id));
fetchLinkSuggestions();
emit("note-loaded", note.id);
} catch {
toast.show("Failed to load note", "error");
}
}
async function saveNote() {
if (!editingId.value) return;
saving.value = true;
try {
await apiPatch(`/api/notes/${editingId.value}`, {
title: noteTitle.value,
body: noteBody.value,
tags: noteTags.value,
});
dirty.value = false;
const idx = projectNotes.value.findIndex((n) => n.id === editingId.value);
if (idx !== -1) {
projectNotes.value[idx] = {
...projectNotes.value[idx],
title: noteTitle.value,
tags: noteTags.value,
updated_at: new Date().toISOString(),
};
projectNotes.value.sort((a, b) =>
new Date(b.updated_at).getTime() - new Date(a.updated_at).getTime()
);
}
} catch {
toast.show("Failed to save note", "error");
} finally {
saving.value = false;
}
}
function requestDelete(id: number, e: Event) {
e.stopPropagation();
if (deletingId.value === id) {
confirmDelete(id);
} else {
deletingId.value = id;
}
}
function cancelDelete(e: Event) {
e.stopPropagation();
deletingId.value = null;
}
async function confirmDelete(id: number) {
pendingDelete.value = id;
try {
await apiDelete(`/api/notes/${id}`);
projectNotes.value = projectNotes.value.filter((n) => n.id !== id);
if (editingId.value === id) {
editingId.value = null;
noteTitle.value = "";
noteBody.value = "";
localStorage.removeItem(_noteKey(props.projectId));
}
} catch {
toast.show("Failed to delete note", "error");
} finally {
pendingDelete.value = null;
deletingId.value = null;
}
}
watch(noteTitle, () => { dirty.value = true; });
watch(noteBody, () => { dirty.value = true; if (editingId.value) scheduleLinkCheck(); });
watch(noteTags, () => { dirty.value = true; });
watch(
() => props.activeNoteId,
async (id) => {
if (id) {
await openNote(id);
await loadProjectNotes();
}
}
);
useAutoSave(dirty, saving, saveNote, 60_000);
onMounted(async () => {
await loadProjectNotes();
const stored = localStorage.getItem(_noteKey(props.projectId));
if (stored) {
const id = Number(stored);
if (projectNotes.value.find((n) => n.id === id)) {
openNote(id).catch(() => {});
}
}
});
onUnmounted(() => { if (linkCheckTimer) clearTimeout(linkCheckTimer); });
defineExpose({ reload: loadProjectNotes });
</script>
<template>
<div class="ws-note-editor">
<!-- Left rail: always-visible note list -->
<div class="note-rail">
<div class="rail-header">
<template v-if="showNewNoteInput">
<input
ref="newNoteTitleRef"
v-model="newNoteTitle"
class="new-note-input"
placeholder="Note title..."
:disabled="creatingNote"
@keydown.enter="createNote"
@keydown.escape="cancelNewNote"
/>
<button class="btn-primary btn-inline" :disabled="creatingNote || !newNoteTitle.trim()" @click="createNote">
{{ creatingNote ? '…' : '+' }}
</button>
<button class="btn-text" aria-label="Cancel new note" @click="cancelNewNote"><X :size="16" /></button>
</template>
<template v-else>
<span class="rail-title">Notes</span>
<button class="btn-ghost btn-inline" @click="startNewNote" title="New note">+ New</button>
</template>
</div>
<div class="rail-search">
<input
v-model="searchQuery"
class="rail-search-input"
placeholder="Search…"
type="search"
aria-label="Search notes"
/>
<button v-if="searchQuery" class="btn-text btn-search-clear" aria-label="Clear search" @click="searchQuery = ''"><X :size="16" /></button>
</div>
<div v-if="listLoading" class="rail-state">Loading…</div>
<ul v-else class="note-list">
<li
v-for="note in filteredNotes"
:key="note.id"
:class="['note-row', { active: editingId === note.id }]"
@click="openNote(note.id)"
>
<div class="note-row-main">
<span class="note-row-title">{{ note.title || 'Untitled' }}</span>
<span class="note-row-age">{{ relativeTimeOrDate(note.updated_at) }}</span>
</div>
<div v-if="note.tags?.length" class="note-row-tags">
<span
v-for="tag in note.tags.slice(0, 2)"
:key="tag"
:class="['note-tag-pill', { 'tag-match': matchedTags(note).includes(tag) }]"
>#{{ tag }}</span>
<span v-if="note.tags.length > 2" class="note-tag-more">+{{ note.tags.length - 2 }}</span>
</div>
<div class="note-row-actions" @click.stop>
<template v-if="deletingId === note.id">
<button class="btn-danger-outline btn-inline" :disabled="pendingDelete === note.id" @click="requestDelete(note.id, $event)">
{{ pendingDelete === note.id ? '…' : 'Delete?' }}
</button>
<button class="btn-text" aria-label="Cancel delete" @click="cancelDelete($event)"><X :size="16" /></button>
</template>
<button v-else class="btn-text" title="Delete note" @click="requestDelete(note.id, $event)">
<Trash2 :size="16" />
</button>
</div>
</li>
<li v-if="filteredNotes.length === 0" class="rail-state">
{{ searchQuery.trim() ? 'No matches.' : 'No notes yet.' }}
</li>
</ul>
</div>
<!-- Right pane: editor -->
<div class="note-editor-pane">
<template v-if="editingId">
<div class="panel-header">
<div class="editor-header-right">
<WordCount :body="noteBody" />
<span v-if="dirty && !saving" class="unsaved">Unsaved</span>
<span v-if="saving" class="saving-txt">Saving…</span>
<button class="btn-primary btn-compact" :disabled="saving || !dirty" @click="saveNote">Save</button>
</div>
</div>
<div class="note-title-row">
<input
ref="titleRef"
v-model="noteTitle"
class="note-title-input"
placeholder="Note title"
@keydown.ctrl.s.prevent="saveNote"
@keydown.ctrl.e.prevent="editorRef?.editor?.commands.focus()"
/>
</div>
<div class="tag-row">
<TagInput v-model="noteTags" :fetchTags="(q: string) => notesStore.fetchAllTags(q)" />
<button
class="btn-ghost btn-compact"
:disabled="tagSuggestions.suggestingTags.value"
title="Auto-suggest tags from title and body"
@click="tagSuggestions.fetchTagSuggestions()"
>
{{ tagSuggestions.suggestingTags.value ? '…' : 'Suggest' }}
</button>
</div>
<div v-if="tagSuggestions.suggestedTags.value.length" class="tag-suggestions">
<span class="tag-suggestions-label">Suggested:</span>
<button
v-for="tag in tagSuggestions.suggestedTags.value"
:key="tag"
:class="['btn-tag-suggestion', { applied: tagSuggestions.appliedTags.value.has(tag) }]"
@click="tagSuggestions.applyTagSuggestion(tag)"
>#{{ tag }}{{ tagSuggestions.appliedTags.value.has(tag) ? ' ✓' : '' }}</button>
<button class="btn-text" aria-label="Dismiss tag suggestions" @click="tagSuggestions.dismissTagSuggestions()"><X :size="16" /></button>
</div>
<div class="toolbar-row">
<MarkdownToolbar :editor="tiptapEditor" />
</div>
<div v-if="linkSuggestions.length" class="link-suggest-strip">
<span class="link-suggest-label">Links:</span>
<span v-for="s in linkSuggestions" :key="s.note_id" class="link-suggest-chip" :title="`Appears ${s.count}× unlinked`">
<button class="btn-chip-link" @click="applyLink(s)">[[{{ s.title }}]]</button>
</span>
<button class="btn-ghost btn-inline" @click="applyAllLinks" title="Link all suggestions">All</button>
<button class="btn-text" aria-label="Dismiss link suggestions" @click="linkSuggestions = []"><X :size="16" /></button>
</div>
<div class="editor-area" @keydown.ctrl.s.prevent="saveNote" @keydown.ctrl.e.prevent="editorRef?.editor?.commands.focus()">
<TiptapEditor ref="editorRef" v-model="noteBody" @escape="titleRef?.focus()" />
</div>
</template>
<div v-else class="editor-empty-state">
<p>Select a note or create a new one</p>
</div>
</div>
</div>
</template>
<style scoped>
.ws-note-editor {
display: flex;
flex-direction: row;
height: 100%;
overflow: hidden;
background: var(--fs-surface-hover);
border-left: 1px solid var(--fs-border-color);
}
/* ── Left rail ── */
.note-rail {
width: 200px;
flex-shrink: 0;
display: flex;
flex-direction: column;
overflow: hidden;
background: var(--fs-surface-raised);
}
.rail-header {
display: flex;
align-items: center;
gap: 0.3rem;
padding: 0.5rem 0.6rem;
border-bottom: 1px solid var(--fs-border-color);
flex-shrink: 0;
}
.rail-title {
color: var(--fs-text-tertiary);
text-transform: uppercase;
letter-spacing: 0.04em;
font-size: 0.72rem;
font-weight: 500;
flex: 1;
}
.rail-search-input {
flex: 1;
background: transparent;
border: none;
font-size: 0.78rem;
color: var(--fs-text-primary);
min-width: 0;
padding: 0;
}
.rail-search-input:focus { outline: none; }
.rail-search-input::-webkit-search-cancel-button { display: none; }
/* Sits inside the search field: no padding, and must not flex. */
.btn-search-clear { padding: 0; flex-shrink: 0; }
.rail-state {
padding: 1rem 0.65rem;
font-size: 0.78rem;
color: var(--fs-text-tertiary);
}
/* Note list */
.note-list {
list-style: none;
margin: 0;
padding: 0;
overflow-y: auto;
flex: 1;
}
.note-row {
display: flex;
flex-direction: column;
padding: 0.4rem 0.6rem;
border-bottom: 1px solid color-mix(in srgb, var(--fs-border-color) 60%, transparent);
cursor: pointer;
gap: 0.15rem;
border-right: 2px solid transparent;
transition: background 0.12s;
}
.note-row:hover { background: color-mix(in srgb, var(--fs-accent) 5%, var(--fs-surface-hover)); }
.note-row.active {
background: color-mix(in srgb, var(--fs-accent) 8%, var(--fs-surface-hover));
border-right-color: var(--fs-accent);
}
.note-row-main {
display: flex;
align-items: baseline;
gap: 0.25rem;
}
.note-row-title {
flex: 1;
font-size: 0.78rem;
font-weight: 500;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
color: var(--fs-text-primary);
}
.note-row-age {
font-size: 0.62rem;
color: var(--fs-text-tertiary);
white-space: nowrap;
flex-shrink: 0;
}
.note-row-tags {
display: flex;
gap: 0.15rem;
overflow: hidden;
}
.note-tag-pill {
font-size: 0.58rem;
color: var(--fs-accent-fg);
background: color-mix(in srgb, var(--fs-accent) 10%, transparent);
border-radius: 999px;
padding: 0 0.3rem;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
max-width: 5rem;
}
.note-tag-pill.tag-match {
background: color-mix(in srgb, var(--fs-accent) 22%, transparent);
outline: 1px solid var(--fs-accent);
}
.note-tag-more {
font-size: 0.58rem;
color: var(--fs-text-tertiary);
white-space: nowrap;
}
.note-row-actions {
display: flex;
gap: 0.2rem;
align-items: center;
}
/* Editor UI */
.panel-header {
display: flex;
align-items: center;
padding: 0.5rem 0.75rem;
flex-shrink: 0;
gap: 0.5rem;
}
.editor-header-right {
display: flex;
align-items: center;
gap: 0.5rem;
margin-left: auto;
}
.unsaved { font-size: 0.72rem; color: var(--fs-text-tertiary); }
.saving-txt { font-size: 0.72rem; color: var(--fs-accent); }
/* Moss action-primary per Hybrid */
.note-title-input {
width: 100%;
background: transparent;
border: none;
font-size: 1.4rem;
font-weight: 500;
line-height: 1.25;
color: var(--fs-text-primary);
padding: 0;
font-family: 'Fraunces', serif;
letter-spacing: -0.01em;
}
.note-title-input:focus { outline: none; }
.note-title-input::placeholder {
color: var(--fs-text-tertiary);
}
.tag-row {
display: flex;
align-items: flex-start;
gap: 0.4rem;
padding: 0.4rem 0.6rem;
flex-shrink: 0;
}
.tag-row > :first-child { flex: 1; min-width: 0; }
.tag-suggestions {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 0.3rem;
padding: 0.35rem 0.6rem;
background: color-mix(in srgb, var(--fs-accent) 5%, var(--fs-surface-hover));
flex-shrink: 0;
}
.tag-suggestions-label { font-size: 0.72rem; color: var(--fs-text-tertiary); flex-shrink: 0; }
.btn-tag-suggestion {
background: none;
border: 1px solid var(--fs-border-color);
border-radius: 999px;
padding: 0.15rem 0.55rem;
font-size: 0.75rem;
color: var(--fs-text-primary);
cursor: pointer;
}
.btn-tag-suggestion:hover { border-color: var(--fs-accent); color: var(--fs-accent); }
.btn-tag-suggestion.applied {
background: color-mix(in srgb, var(--fs-accent) 15%, transparent);
border-color: var(--fs-accent);
color: var(--fs-accent-fg);
}
.link-suggest-strip {
display: flex;
align-items: center;
flex-wrap: wrap;
gap: 0.25rem;
padding: 0.3rem 0.6rem;
background: color-mix(in srgb, var(--fs-accent) 5%, var(--fs-surface-hover));
flex-shrink: 0;
}
.link-suggest-label {
font-size: 0.7rem;
color: var(--fs-text-tertiary);
flex-shrink: 0;
font-weight: 500;
text-transform: uppercase;
letter-spacing: 0.04em;
}
.link-suggest-chip { display: inline-flex; }
.btn-chip-link {
background: none;
border: 1px solid var(--fs-accent);
border-radius: 999px;
padding: 0.1rem 0.45rem;
font-size: 0.7rem;
color: var(--fs-accent);
cursor: pointer;
font-family: monospace;
white-space: nowrap;
}
.btn-chip-link:hover { background: color-mix(in srgb, var(--fs-accent) 15%, transparent); }
</style>
@@ -1,618 +0,0 @@
<script setup lang="ts">
import { ref, computed, onMounted } from "vue";
import { RouterLink } from "vue-router";
import { apiGet, apiPatch, apiPost, apiDelete } from "@/api/client";
import { useToastStore } from "@/stores/toast";
import TaskLogSection from "@/components/TaskLogSection.vue";
import KindBadge from "@/components/KindBadge.vue";
import type { TaskKind } from "@/types/note";
import { renderMarkdown } from "@/utils/markdown";
import { Trash2, X } from "lucide-vue-next";
import { relativeTimeOrDate } from "@/composables/useRelativeTime";
const props = defineProps<{ projectId: number }>();
const toast = useToastStore();
interface Milestone {
id: number;
title: string;
status: string;
order_index: number;
}
interface Task {
id: number;
title: string;
status: string;
priority: string;
milestone_id: number | null;
due_date: string | null;
updated_at: string;
body?: string;
task_kind?: TaskKind;
}
const tasks = ref<Task[]>([]);
const milestones = ref<Milestone[]>([]);
const loading = ref(false);
// Detail slide-over
const activeTask = ref<Task | null>(null);
const taskBody = ref("");
const loadingBody = ref(false);
// Collapsed milestone groups (set of milestone IDs, null = "No Milestone" group)
const collapsedGroups = ref<Set<number | null>>(new Set());
// New task quick-add
const newTaskTitle = ref("");
const addingTask = ref(false);
const STATUS_CYCLE: Record<string, string> = {
todo: "in_progress",
in_progress: "done",
done: "todo",
};
const STATUS_ICON: Record<string, string> = {
todo: "○",
in_progress: "▶",
done: "✓",
};
const PRIORITY_CLASS: Record<string, string> = {
high: "priority-high",
medium: "priority-medium",
low: "priority-low",
};
function isRowOverdue(task: Task): boolean {
if (!task.due_date || task.status === "done") return false;
return task.due_date < new Date().toISOString().slice(0, 10);
}
// Group tasks by milestone, "No Milestone" first
const groupedTasks = computed(() => {
const noMs = tasks.value.filter((t) => t.milestone_id === null);
const msGroups = milestones.value.map((ms) => ({
milestone: ms,
tasks: tasks.value.filter((t) => t.milestone_id === ms.id),
}));
return { noMilestone: noMs, milestoneGroups: msGroups };
});
async function loadAll() {
loading.value = true;
try {
const [tasksRes, msRes] = await Promise.all([
apiGet<{ notes: Task[] }>(`/api/projects/${props.projectId}/notes?type=task&limit=200`),
apiGet<{ milestones: Milestone[] }>(`/api/projects/${props.projectId}/milestones`),
]);
tasks.value = tasksRes.notes ?? [];
milestones.value = msRes.milestones ?? [];
} catch {
toast.show("Failed to load tasks", "error");
} finally {
loading.value = false;
}
}
async function cycleStatus(task: Task, e: Event) {
e.stopPropagation();
const next = STATUS_CYCLE[task.status] ?? "todo";
try {
await apiPatch(`/api/tasks/${task.id}/status`, { status: next });
task.status = next;
if (activeTask.value?.id === task.id) activeTask.value.status = next;
} catch {
toast.show("Failed to update status", "error");
}
}
function toggleGroup(key: number | null) {
if (collapsedGroups.value.has(key)) {
collapsedGroups.value.delete(key);
} else {
collapsedGroups.value.add(key);
}
}
async function openTask(task: Task) {
activeTask.value = task;
taskBody.value = task.body ?? "";
loadingBody.value = true;
try {
const full = await apiGet<Task>(`/api/tasks/${task.id}`);
taskBody.value = full.body ?? "";
// Update cached task so re-opens don't re-fetch if unchanged
task.body = full.body;
} catch {
// Non-critical — body just won't show
} finally {
loadingBody.value = false;
}
}
function closeTask() {
activeTask.value = null;
taskBody.value = "";
deleteConfirmPending.value = false;
}
async function addTask() {
const title = newTaskTitle.value.trim();
if (!title) return;
addingTask.value = true;
try {
const task = await apiPost<Task>("/api/tasks", {
title,
project_id: props.projectId,
status: "todo",
});
tasks.value.unshift(task);
newTaskTitle.value = "";
} catch {
toast.show("Failed to create task", "error");
} finally {
addingTask.value = false;
}
}
const deletingTask = ref(false);
const deleteConfirmPending = ref(false);
const changingMilestone = ref(false);
async function setMilestone(milestoneId: number | null) {
if (!activeTask.value) return;
changingMilestone.value = true;
try {
await apiPatch(`/api/notes/${activeTask.value.id}`, { milestone_id: milestoneId });
activeTask.value.milestone_id = milestoneId;
// Update in tasks list too
const t = tasks.value.find((x) => x.id === activeTask.value!.id);
if (t) t.milestone_id = milestoneId;
} catch {
toast.show("Failed to update milestone", "error");
} finally {
changingMilestone.value = false;
}
}
async function deleteActiveTask() {
if (!activeTask.value) return;
if (!deleteConfirmPending.value) {
deleteConfirmPending.value = true;
return;
}
deletingTask.value = true;
try {
await apiDelete(`/api/tasks/${activeTask.value.id}`);
tasks.value = tasks.value.filter((t) => t.id !== activeTask.value!.id);
activeTask.value = null;
deleteConfirmPending.value = false;
} catch {
toast.show("Failed to delete task", "error");
} finally {
deletingTask.value = false;
}
}
function cancelDeleteTask() {
deleteConfirmPending.value = false;
}
onMounted(loadAll);
defineExpose({ reload: loadAll });
</script>
<template>
<div class="ws-task-panel">
<!-- Task list — always visible, shrinks when detail is open -->
<div :class="['task-list-view', { 'has-detail': !!activeTask }]">
<div class="panel-header">
<span class="panel-title">Tasks</span>
</div>
<div class="task-add">
<input
v-model="newTaskTitle"
class="task-add-input"
placeholder="New task..."
@keydown.enter="addTask"
/>
<button class="btn-primary btn-inline btn-add" :disabled="addingTask || !newTaskTitle.trim()" @click="addTask">+</button>
</div>
<div v-if="loading" class="state-msg">Loading...</div>
<div v-else class="groups-scroll">
<!-- No Milestone group (always first) -->
<div class="ms-group">
<button class="ms-group-header" @click="toggleGroup(null)">
<span class="ms-chevron">{{ collapsedGroups.has(null) ? '▶' : '▼' }}</span>
<span class="ms-name">No Milestone</span>
<span class="ms-count">{{ groupedTasks.noMilestone.length }}</span>
</button>
<ul v-show="!collapsedGroups.has(null)" class="task-items">
<li
v-for="task in groupedTasks.noMilestone"
:key="task.id"
:class="['task-row', { 'task-active': activeTask?.id === task.id }]"
@click="openTask(task)"
>
<button :class="['status-dot', `status-${task.status}`]" :title="`${task.status} — click to cycle`" @click="cycleStatus(task, $event)">{{ STATUS_ICON[task.status] ?? '○' }}</button>
<span v-if="task.priority && task.priority !== 'none'" :class="['priority-dot', PRIORITY_CLASS[task.priority] ?? '']"></span>
<span class="task-title" :class="{ done: task.status === 'done' }">{{ task.title }}</span>
<KindBadge :kind="task.task_kind" />
<span v-if="task.due_date" :class="['task-due', { overdue: isRowOverdue(task) }]">{{ task.due_date }}</span>
<span class="task-age">{{ relativeTimeOrDate(task.updated_at) }}</span>
</li>
<li v-if="groupedTasks.noMilestone.length === 0" class="empty-group">No tasks</li>
</ul>
</div>
<!-- Milestone groups -->
<div v-for="{ milestone, tasks: msTasks } in groupedTasks.milestoneGroups" :key="milestone.id" class="ms-group">
<button class="ms-group-header" @click="toggleGroup(milestone.id)">
<span class="ms-chevron">{{ collapsedGroups.has(milestone.id) ? '▶' : '▼' }}</span>
<span class="ms-name">{{ milestone.title }}</span>
<span :class="['ms-status', `ms-status-${milestone.status}`]">{{ milestone.status.replace('_',' ') }}</span>
<span class="ms-count">{{ msTasks.length }}</span>
</button>
<ul v-show="!collapsedGroups.has(milestone.id)" class="task-items">
<li
v-for="task in msTasks"
:key="task.id"
:class="['task-row', { 'task-active': activeTask?.id === task.id }]"
@click="openTask(task)"
>
<button :class="['status-dot', `status-${task.status}`]" :title="`${task.status} — click to cycle`" @click="cycleStatus(task, $event)">{{ STATUS_ICON[task.status] ?? '○' }}</button>
<span v-if="task.priority && task.priority !== 'none'" :class="['priority-dot', PRIORITY_CLASS[task.priority] ?? '']"></span>
<span class="task-title" :class="{ done: task.status === 'done' }">{{ task.title }}</span>
<KindBadge :kind="task.task_kind" />
<span v-if="task.due_date" :class="['task-due', { overdue: isRowOverdue(task) }]">{{ task.due_date }}</span>
<span class="task-age">{{ relativeTimeOrDate(task.updated_at) }}</span>
</li>
<li v-if="msTasks.length === 0" class="empty-group">No tasks</li>
</ul>
</div>
</div>
</div>
<!-- Detail pane — bottom split when a task is selected -->
<Transition name="detail-fade">
<div v-if="activeTask" class="task-detail">
<div class="detail-header">
<RouterLink :to="`/tasks/${activeTask.id}/edit`" target="_blank" class="btn-text btn-edit-task" title="Open full editor">Edit ↗</RouterLink>
<span :class="['status-cycler', `status-${activeTask.status}`]" @click="cycleStatus(activeTask, $event)" title="Click to cycle status">
{{ STATUS_ICON[activeTask.status] ?? "○" }} {{ activeTask.status.replace("_", " ") }}
</span>
<template v-if="deleteConfirmPending">
<button class="btn-danger-outline btn-inline btn-delete-confirm" :disabled="deletingTask" @click="deleteActiveTask">{{ deletingTask ? '...' : 'Delete?' }}</button>
<button class="btn-text" aria-label="Cancel delete" @click="cancelDeleteTask"><X :size="16" /></button>
</template>
<button v-else class="btn-text btn-delete-task" title="Delete task" @click="deleteActiveTask">
<Trash2 :size="16" />
</button>
<button class="btn-text btn-close-detail" @click="closeTask" aria-label="Close detail"><X :size="16" /></button>
</div>
<h3 class="detail-title">{{ activeTask.title }}</h3>
<div class="detail-meta">
<span v-if="activeTask.priority && activeTask.priority !== 'none'" class="meta-chip priority">{{ activeTask.priority }}</span>
<span v-if="activeTask.due_date" class="meta-chip due">Due {{ activeTask.due_date }}</span>
<select
class="milestone-select"
:value="activeTask.milestone_id ?? ''"
:disabled="changingMilestone"
@change="setMilestone(($event.target as HTMLSelectElement).value === '' ? null : Number(($event.target as HTMLSelectElement).value))"
>
<option value="">No Milestone</option>
<option v-for="ms in milestones" :key="ms.id" :value="ms.id">{{ ms.title }}</option>
</select>
</div>
<div v-if="taskBody || loadingBody" class="detail-body">
<div v-if="loadingBody" class="body-loading">…</div>
<div v-else class="prose" v-html="renderMarkdown(taskBody)" />
</div>
<div class="detail-log">
<TaskLogSection :task-id="activeTask.id" />
</div>
</div>
</Transition>
</div>
</template>
<style scoped>
.ws-task-panel {
position: relative;
display: flex;
flex-direction: column;
height: 100%;
overflow: hidden;
background: var(--fs-surface-hover);
border-right: 1px solid var(--fs-border-color);
}
/* ── List view ── */
.task-list-view {
display: flex;
flex-direction: column;
flex: 1;
min-height: 0;
overflow: hidden;
}
.task-list-view.has-detail {
flex: 0 0 44%;
}
.task-active {
background: color-mix(in srgb, var(--fs-accent) 6%, var(--fs-surface-hover)) !important;
}
.panel-header {
padding: 0.6rem 0.75rem;
border-bottom: 1px solid var(--fs-border-color);
flex-shrink: 0;
}
.panel-title {
color: var(--fs-text-tertiary);
text-transform: uppercase;
letter-spacing: 0.04em;
font-size: 0.75rem;
font-weight: 500;
}
.task-add {
display: flex;
gap: 0.4rem;
padding: 0.45rem 0.6rem;
border-bottom: 1px solid var(--fs-border-color);
flex-shrink: 0;
}
.task-add-input {
flex: 1;
background: var(--fs-surface-page);
border: 1px solid var(--fs-border-color);
border-radius: 5px;
padding: 0.28rem 0.5rem;
font-size: 0.83rem;
color: var(--fs-text-primary);
}
.task-add-input:focus { outline: none; border-color: var(--fs-accent); }
.btn-add { font-size: 1rem; } /* a '+' glyph, not a label */
.groups-scroll {
flex: 1;
overflow-y: auto;
}
.ms-group {
border-bottom: 1px solid var(--fs-border-color);
}
.ms-group-header {
display: flex;
align-items: center;
gap: 0.4rem;
width: 100%;
padding: 0.4rem 0.65rem;
background: var(--fs-surface-raised);
border: none;
cursor: pointer;
text-align: left;
font-size: 0.8rem;
color: var(--fs-text-primary);
}
.ms-group-header:hover { background: color-mix(in srgb, var(--fs-accent) 8%, var(--fs-surface-hover)); }
.ms-chevron { font-size: 0.6rem; color: var(--fs-text-tertiary); width: 0.8rem; }
.ms-name { flex: 1; font-weight: 500; font-size: 0.8rem; }
.ms-count { font-size: 0.72rem; color: var(--fs-text-tertiary); background: var(--fs-surface-page); border-radius: 10px; padding: 0 0.4rem; }
.ms-status {
font-size: 0.68rem;
padding: 0.1rem 0.4rem;
border-radius: 10px;
text-transform: capitalize;
}
.ms-status-active { background: color-mix(in srgb, var(--fs-accent) 15%, transparent); color: var(--fs-accent-fg); }
.ms-status-completed { background: color-mix(in srgb, var(--fs-success) 15%, transparent); color: var(--fs-success-fg); }
.task-items {
list-style: none;
margin: 0;
padding: 0;
}
.task-row {
display: flex;
align-items: center;
gap: 0.4rem;
padding: 0.35rem 0.65rem 0.35rem 1.4rem;
cursor: pointer;
border-bottom: 1px solid color-mix(in srgb, var(--fs-border-color) 50%, transparent);
}
.task-row:hover { background: color-mix(in srgb, var(--fs-accent) 5%, var(--fs-surface-hover)); }
.task-row:last-child { border-bottom: none; }
.status-dot {
flex-shrink: 0;
width: 1.35rem;
height: 1.35rem;
border-radius: 50%;
border: 1.5px solid var(--fs-border-color);
background: none;
cursor: pointer;
font-size: 0.62rem;
display: flex;
align-items: center;
justify-content: center;
}
.status-dot.status-in_progress { border-color: var(--fs-accent); color: var(--fs-accent); }
.status-dot.status-done { border-color: var(--fs-success); color: var(--fs-success); }
.task-title {
flex: 1;
font-size: 0.83rem;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
color: var(--fs-text-primary);
}
.task-title.done { text-decoration: line-through; color: var(--fs-text-tertiary); }
.task-age {
font-size: 0.68rem;
color: var(--fs-text-tertiary);
white-space: nowrap;
flex-shrink: 0;
}
.empty-group { padding: 0.4rem 1.4rem; font-size: 0.78rem; color: var(--fs-text-tertiary); }
.state-msg { padding: 1.5rem; text-align: center; font-size: 0.85rem; color: var(--fs-text-tertiary); }
/* ── Detail pane (bottom split) ── */
.task-detail {
flex: 1;
min-height: 0;
display: flex;
flex-direction: column;
overflow: hidden;
background: var(--fs-surface-hover);
border-top: 2px solid var(--fs-border-color);
}
.detail-header {
display: flex;
align-items: center;
gap: 0.6rem;
padding: 0.6rem 0.75rem;
border-bottom: 1px solid var(--fs-border-color);
flex-shrink: 0;
}
/* An interactive CYCLER, not a chip: it is clickable, outlined and
transparent. It shared a name with the task chip and was never the same
shape (#3132). */
.status-cycler {
padding: 0.2rem 0.55rem;
border-radius: 12px;
font-size: 0.75rem;
font-weight: 500;
cursor: pointer;
border: 1.5px solid var(--fs-border-color);
background: none;
text-transform: capitalize;
user-select: none;
margin-left: auto;
}
.status-cycler.status-in_progress { border-color: var(--fs-accent); color: var(--fs-accent-fg); background: color-mix(in srgb, var(--fs-accent) 10%, transparent); }
.status-cycler.status-done { border-color: var(--fs-success); color: var(--fs-success-fg); background: color-mix(in srgb, var(--fs-success) 10%, transparent); }
.btn-edit-task { margin-left: 0.25rem; }
.btn-edit-task:hover { text-decoration: underline; }
.detail-body {
padding: 0.5rem 0.75rem 0.5rem;
border-bottom: 1px solid var(--fs-border-color);
flex-shrink: 0;
max-height: 40%;
overflow-y: auto;
}
.body-loading {
font-size: 0.8rem;
color: var(--fs-text-tertiary);
}
.detail-body .prose {
font-size: 0.83rem;
line-height: 1.5;
color: var(--fs-text-primary);
}
.btn-delete-task { margin-left: 0.25rem; }
.btn-delete-task:hover { color: var(--fs-action-destructive); }
.btn-delete-confirm { margin-left: 0.25rem; }
.detail-meta {
display: flex;
gap: 0.4rem;
padding: 0 0.75rem 0.5rem;
flex-shrink: 0;
}
.meta-chip {
font-size: 0.72rem;
padding: 0.15rem 0.5rem;
border-radius: 10px;
background: var(--fs-surface-page);
border: 1px solid var(--fs-border-color);
color: var(--fs-text-tertiary);
text-transform: capitalize;
}
.milestone-select {
font-size: 0.72rem;
padding: 0.15rem 0.4rem;
border-radius: 10px;
background: var(--fs-surface-page);
border: 1px solid var(--fs-border-color);
color: var(--fs-text-tertiary);
cursor: pointer;
max-width: 140px;
}
.milestone-select:disabled { opacity: 0.5; cursor: default; }
.milestone-select:focus { outline: none; border-color: var(--fs-accent); }
.detail-log {
flex: 1;
overflow-y: auto;
padding: 0 0.6rem 0.6rem;
border-top: 1px solid var(--fs-border-color);
}
/* Detail fade transition */
.detail-fade-enter-active,
.detail-fade-leave-active { transition: opacity 0.15s; }
.detail-fade-enter-from,
.detail-fade-leave-to { opacity: 0; }
/* Priority dots on task rows */
.priority-dot {
width: 6px;
height: 6px;
border-radius: 2px;
flex-shrink: 0;
}
.priority-high { background: #ef4444; }
.priority-medium { background: #f59e0b; }
.priority-low { background: #3b82f6; }
/* Due date on task rows */
.task-due {
font-size: 0.65rem;
color: var(--fs-text-tertiary);
white-space: nowrap;
flex-shrink: 0;
}
.task-due.overdue {
color: var(--fs-error);
font-weight: 500;
}
/* Close detail button */
.btn-close-detail { margin-left: 0.2rem; }
</style>
@@ -6,7 +6,10 @@ import { useMomentsStore } from "@/stores/moments";
import RuleHistoryPanel from "@/components/rules/RuleHistoryPanel.vue";
import RuleHomePicker from "@/components/rules/RuleHomePicker.vue";
import { apiErrorMessage } from "@/api/client";
import { listRulebooks, listTopics, type Rule, type RuleKind, type RulePreset } from "@/api/rulebooks";
import {
listRulebooks, listTopics,
type Rule, type RuleEnforcement, type RuleKind, type RulePreset, type RuleSalience,
} from "@/api/rulebooks";
const props = defineProps<{
ruleId: number | null;
@@ -26,6 +29,14 @@ const whenToApply = ref("");
// followed too faithfully, where a rule mislabelled as a preference is one a
// session may quietly rewrite.
const kind = ref<RuleKind>("rule");
// The server's defaults: a line beside the work, at normal rank.
const enforcement = ref<RuleEnforcement>("inform");
const salience = ref<RuleSalience>("normal");
// A preference carries no force but `inform`, and the server refuses any
// other, so switching kind settles it here rather than as a failed save.
watch(kind, (k) => {
if (k === "preference") enforcement.value = "inform";
});
const systemIds = ref<number[]>([]);
// The moments this rule is mounted on. Catalog moments are
// ticked; a named procedure's moment (`skill.<name>`) is typed, since its
@@ -123,6 +134,8 @@ async function load() {
statement.value = r.statement;
whenToApply.value = r.when_to_apply || "";
kind.value = r.kind;
enforcement.value = r.enforcement ?? "inform";
salience.value = r.salience ?? "normal";
systemIds.value = (r.systems ?? []).map((sys) => sys.id);
ruleMoments.value = [...(r.moments ?? [])];
why.value = r.why || "";
@@ -135,6 +148,8 @@ async function load() {
statement.value = "";
whenToApply.value = props.preset?.whenToApply ?? "";
kind.value = props.preset?.kind ?? "rule";
enforcement.value = "inform";
salience.value = "normal";
systemIds.value = [];
ruleMoments.value = [...(props.preset?.moments ?? [])];
why.value = "";
@@ -181,6 +196,8 @@ async function save() {
statement: statement.value,
when_to_apply: whenToApply.value,
kind: kind.value,
enforcement: enforcement.value,
salience: salience.value,
// Always sent, so clearing the last area actually clears it — the server
// reads a list as "these ARE the areas now".
system_ids: systemIds.value,
@@ -271,6 +288,38 @@ watch(() => props.ruleId, load);
preference.
</p>
</fieldset>
<fieldset class="kind arrival">
<legend>When it arrives</legend>
<template v-if="kind === 'rule'">
<label class="kind-opt">
<input v-model="enforcement" type="radio" value="inform" />
<span><strong>Inform</strong> — a line beside the work. Most rules.</span>
</label>
<label class="kind-opt">
<input v-model="enforcement" type="radio" value="hold" />
<span>
<strong>Hold</strong> — the reply or act it governs waits for one
read of it. For a rule whose miss costs a rewrite.
</span>
</label>
<label class="kind-opt">
<input v-model="enforcement" type="radio" value="enforce" />
<span>
<strong>Enforce</strong> — the act itself is checked. For a hard
boundary.
</span>
</label>
</template>
<p v-else class="field-note">A preference arrives as a line beside the work.</p>
<label class="salience">
Rank among the rest
<select v-model="salience" class="fs-input">
<option value="high">High — shown first when a moment is crowded</option>
<option value="normal">Normal</option>
<option value="low">Low — the first to give way</option>
</select>
</label>
</fieldset>
<p v-if="kind === 'preference'" class="kind-drift">
Sessions rewrite preferences without asking, which is what makes them
stay current. Every rewrite is kept, and
@@ -4,9 +4,9 @@
* full. Not on the list row: a history entry point there would compete with
* the row's actual job.
*
* A SIBLING OF HistoryPanel.vue, NOT A REUSE OF IT, and the reason is in its
* props: `noteId` + `currentBody`, a `NoteVersion` carrying tags and pin
* columns, a fetch of /api/notes/…, a `restore` emit, and pin/unpin buttons.
* A SIBLING OF VersionHistorySection.vue (a note's history), NOT A REUSE OF
* IT, and the reason is in its props: `noteId` + `currentBody`, a note
* version carrying tags, a fetch of /api/notes/…, and a `restore` emit.
* Every one of those is note-shaped. Rules have no tags, no pins, and
* deliberately no restore, and a rule's text is EIGHT fields rather than one
* body — which changes the central question from "what changed" to "which
@@ -27,6 +27,15 @@ const emit = defineEmits<{
class="rule-chip rule-chip-preference"
title="How you want work done. It does not bind, and Grimoire updates it as the work teaches it."
>preference</span>
<!-- Marked only when the rule stops the work: a line beside the work
is the default, and marking it on every row would mark nothing. -->
<span
v-if="r.enforcement === 'hold' || r.enforcement === 'enforce'"
class="rule-chip"
:title="r.enforcement === 'hold'
? 'The reply or act it governs waits for one read of it'
: 'The act it governs is checked against it'"
>{{ r.enforcement === "hold" ? "holds" : "enforced" }}</span>
<!-- Marked only when something is WRONG: every rule arrives by
retrieval now, so "conditional" stopped distinguishing anything.
A missing trigger does — it means nothing can retrieve this. -->
+2 -1
View File
@@ -51,7 +51,8 @@ export function useAutocomplete(
// Must be start of line or preceded by whitespace
if (i === 0 || /\s/.test(text[i - 1])) {
const query = text.slice(i + 1, cursor);
if (/^[\w/]*$/.test(query)) {
// Digits alone are a record reference being typed (`#4286`), not a tag.
if (/^[\w/]*$/.test(query) && !/^\d+$/.test(query)) {
acTriggerStart = i;
acType = "tag";
debouncedSearch(query);
+199
View File
@@ -0,0 +1,199 @@
import type { ObjectDirective } from "vue";
import { apiPost } from "@/api/client";
import router from "@/router";
import { recordHref } from "@/utils/recordHref";
import type { RefSpace } from "@/utils/recordRefs";
/** v-record-refs — makes the `a.record-ref` links in a v-html body real.
*
* Put it on the element that holds rendered markdown:
* <div class="prose" v-html="renderMarkdown(body)" v-record-refs />
*
* After each render it asks the server, once for the whole body, what every
* referenced id is. Each link then gets the route its kind opens at (a `#N`
* may be a task, lesson or snippet), the record's title drawn before its
* number — "Fix the cache key #3127" — so a reader knows what is cited
* without hovering, its kind, full title and status as a tooltip, and a
* "leads nowhere" style when the reader cannot open it: missing, trashed and
* not-shared-with-you look the same, on purpose, and keep the bare number.
* The stored text stays `#N`; the title is read at render, so an edited
* title shows everywhere it is cited.
* A plain click navigates in the app; a modified click (new tab) keeps the
* browser's own behaviour.
*/
interface NoteInfo { id: number; title: string; is_task: boolean; note_type: string; status: string | null; task_kind: string | null }
interface MilestoneInfo { id: number; title: string; project_id: number | null; status: string }
interface RuleInfo { id: number; title: string; kind: string }
type Resolved = { notes: Record<string, NoteInfo>; milestones: Record<string, MilestoneInfo>; rules: Record<string, RuleInfo> };
// `title` is drawn in the link; `label` (kind · title (status)) is its tooltip.
type Info = { href: string; title: string; label: string } | null;
// A short-lived cache: the same body re-renders on every keystroke in a
// preview, and a page of work logs cites the same few records again and again.
const CACHE_MS = 60_000;
const cache = new Map<string, { at: number; info: Info }>();
const TASK_KIND_LABEL: Record<string, string> = { issue: "Issue", spike: "Spike" };
function noteInfo(n: NoteInfo): Info {
let kind = "Note";
if (n.is_task) kind = TASK_KIND_LABEL[n.task_kind ?? ""] ?? "Task";
else if (n.note_type === "lesson") kind = "Lesson";
else if (n.note_type === "snippet") kind = "Snippet";
const state = n.is_task && n.status ? ` (${n.status.replace(/_/g, " ")})` : "";
const title = n.title || "Untitled";
return { href: recordHref(n), title, label: `${kind} · ${title}${state}` };
}
function milestoneInfo(m: MilestoneInfo): Info {
if (m.project_id == null) return null;
const title = m.title || "Untitled";
return {
href: `/projects/${m.project_id}?milestone=${m.id}`,
title,
label: `Milestone · ${title}${m.status === "done" ? " (done)" : ""}`,
};
}
function ruleInfo(r: RuleInfo): Info {
const kind = r.kind === "preference" ? "Preference" : "Rule";
const title = r.title || "Untitled";
return { href: `/rules?rule=${r.id}`, title, label: `${kind} · ${title}` };
}
// Titles here are often whole sentences; in running text a reference names its
// record in a few words and the tooltip carries the rest.
const MAX_TITLE = 60;
function shorten(title: string): string {
if (title.length <= MAX_TITLE) return title;
const cut = title.slice(0, MAX_TITLE);
const space = cut.lastIndexOf(" ");
return (space > MAX_TITLE / 2 ? cut.slice(0, space) : cut).replace(/[\s,.;:—–-]+$/, "") + "…";
}
const BLOCK = "p, li, td, th, blockquote, h1, h2, h3, h4, h5, h6";
/** Whether the sentence around this link already names the record — a batch
* writes `#9 "Step two"`, and a paragraph citing one record twice names it
* the first time. A short title is drawn regardless: three letters turn up
* in prose by chance. */
function alreadyNamed(a: HTMLAnchorElement, shown: string, title: string): boolean {
if (title.length < 8) return false;
const text = (a.closest(BLOCK) ?? a.parentElement)?.textContent?.toLowerCase() ?? "";
return text.includes(title.toLowerCase()) || text.includes(shown.toLowerCase());
}
/** Draw the record's title in the link, its number after it, muted. Set as
* text, never as markup: a title is whatever its author typed. */
function showTitle(a: HTMLAnchorElement, title: string): boolean {
const shown = shorten(title);
if (alreadyNamed(a, shown, title)) return false;
const name = document.createElement("span");
name.className = "record-ref__title";
name.textContent = shown;
const ref = document.createElement("span");
ref.className = "record-ref__id";
ref.textContent = a.textContent ?? "";
a.replaceChildren(name, " ", ref);
return true;
}
function refKey(space: RefSpace, id: number): string {
return `${space}:${id}`;
}
/** What each of these references is, from the cache or one server call. */
export async function resolveRecordRefs(wanted: { space: RefSpace; id: number }[]): Promise<Map<string, Info>> {
const now = Date.now();
const out = new Map<string, Info>();
const ask: Record<RefSpace, number[]> = { notes: [], milestones: [], rules: [] };
for (const w of wanted) {
const k = refKey(w.space, w.id);
if (out.has(k)) continue;
const hit = cache.get(k);
if (hit && now - hit.at < CACHE_MS) out.set(k, hit.info);
else if (!ask[w.space].includes(w.id)) ask[w.space].push(w.id);
}
if (ask.notes.length + ask.milestones.length + ask.rules.length === 0) return out;
const res = await apiPost<Resolved>("/api/notes/resolve-refs", ask);
const store = (space: RefSpace, id: number, info: Info) => {
cache.set(refKey(space, id), { at: now, info });
out.set(refKey(space, id), info);
};
for (const id of ask.notes) store("notes", id, res.notes[id] ? noteInfo(res.notes[id]) : null);
for (const id of ask.milestones) store("milestones", id, res.milestones[id] ? milestoneInfo(res.milestones[id]) : null);
for (const id of ask.rules) store("rules", id, res.rules[id] ? ruleInfo(res.rules[id]) : null);
return out;
}
function unresolvedLinks(el: HTMLElement): HTMLAnchorElement[] {
return Array.from(el.querySelectorAll<HTMLAnchorElement>("a.record-ref:not([data-ref-state])"));
}
async function decorate(el: HTMLElement) {
const links = unresolvedLinks(el);
if (!links.length) return;
const wanted = links.map((a) => ({ space: a.dataset.refSpace as RefSpace, id: Number(a.dataset.refId) }));
let resolved: Map<string, Info>;
try {
resolved = await resolveRecordRefs(wanted);
} catch {
// The links keep their provisional routes, which open the right view for
// notes, rules and milestones alike; only the titles are missing.
return;
}
for (const a of links) {
if (!a.isConnected) continue;
const info = resolved.get(refKey(a.dataset.refSpace as RefSpace, Number(a.dataset.refId)));
if (info === undefined) continue;
if (info === null) {
a.dataset.refState = "missing";
a.classList.add("record-ref--missing");
a.removeAttribute("href");
a.setAttribute("aria-disabled", "true");
a.title = `${a.textContent} — no record you can open`;
continue;
}
a.dataset.refState = "ok";
a.href = info.href;
a.title = info.label;
const bare = a.textContent;
// Drawn with its title, the link's own text is its accessible name; a bare
// number needs the label spoken for it.
if (!showTitle(a, info.title)) a.setAttribute("aria-label", `${bare}: ${info.label}`);
}
}
const clickHandlers = new WeakMap<HTMLElement, (e: MouseEvent) => void>();
function onClick(e: MouseEvent) {
const a = (e.target as HTMLElement).closest("a.record-ref") as HTMLAnchorElement | null;
if (!a) return;
if (a.dataset.refState === "missing") {
e.preventDefault();
return;
}
if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
const href = a.getAttribute("href");
if (!href) return;
e.preventDefault();
router.push(href);
}
export const vRecordRefs: ObjectDirective<HTMLElement> = {
mounted(el) {
clickHandlers.set(el, onClick);
el.addEventListener("click", onClick);
void decorate(el);
},
updated(el) {
void decorate(el);
},
beforeUnmount(el) {
const h = clickHandlers.get(el);
if (h) el.removeEventListener("click", h);
clickHandlers.delete(el);
},
};
+3 -1
View File
@@ -2,7 +2,9 @@ import { Extension } from "@tiptap/core";
import { Plugin, PluginKey } from "@tiptap/pm/state";
import { Decoration, DecorationSet } from "@tiptap/pm/view";
const TAG_RE = /(?<=\s|^)#([\w]+(?:\/[\w]+)*)/g;
// Digits alone (`#4286`) are a record reference, not a tag, and are left plain
// here; the rendered view links them (utils/recordRefs.ts).
const TAG_RE = /(?<=\s|^)#(?!\d+(?![\w/-]))([\w]+(?:\/[\w]+)*)/g;
export const TagDecoration = Extension.create({
name: "tagDecoration",
+20
View File
@@ -123,6 +123,26 @@ const router = createRouter({
name: "project-view",
component: () => import("@/views/ProjectView.vue"),
},
{
// Where a `milestone N` reference leads. A milestone is shown on its
// project's board, so this only looks up which project and goes there.
path: "/milestones/:id",
name: "milestone",
component: () => import("@/views/ProjectListView.vue"),
beforeEnter: async (to) => {
const id = Number(to.params.id);
const { resolveRecordRefs } = await import("@/directives/recordRefs");
try {
const found = (await resolveRecordRefs([{ space: "milestones", id }])).get(`milestones:${id}`);
if (found) return found.href;
} catch {
// Fall through to the projects list with the notice below.
}
const { useToastStore } = await import("@/stores/toast");
useToastStore().show(`No milestone ${id} you can open`, "warning");
return { name: "projects" };
},
},
{
path: "/rules",
name: "rules",
+3
View File
@@ -111,6 +111,9 @@ export const useRulebooksStore = defineStore("rulebooks", () => {
// force as the same row re-fetched, or a preference the operator just
// created would sit in the list looking like a rule until a reload.
kind: rule.kind,
enforcement: rule.enforcement ?? "inform",
// Mirrors rule_brief: present only when raised or lowered.
salience: rule.salience && rule.salience !== "normal" ? rule.salience : undefined,
updated_at: rule.updated_at,
when_to_apply: rule.when_to_apply || undefined,
arose_from_id: rule.arose_from_id ?? undefined,
+1 -1
View File
@@ -2,7 +2,7 @@
* Line diff — one copy, for every surface that shows what changed.
*
* WHY THIS FILE EXISTS. The one LCS diff walk, shared by `useAssist.ts`,
* `HistoryPanel.vue`, `VersionHistorySection.vue` and the rule edit history.
* `VersionHistorySection.vue` and the rule edit history.
* A copy per consumer means a fix has to be found in N places by someone who
* does not know N.
*/
+7 -4
View File
@@ -1,6 +1,7 @@
import { marked, type RendererThis, type Tokens } from "marked";
import DOMPurify from "dompurify";
import { linkifyTags, linkifyWikilinks } from "@/utils/tags";
import { linkifyRecordRefs } from "@/utils/recordRefs";
function decodeEntities(text: string): string {
const textarea = document.createElement("textarea");
@@ -20,9 +21,11 @@ export function slugify(text: string): string {
export function stripFirstLineTags(text: string): string {
const match = text.match(/^[ \t]*((?:(?<!\w)#[\w]+(?:\/[\w]+)*[ \t]*)+)\n?/);
if (!match) return text;
// Verify every #-token is a tag, not a heading (headings have "# " with space)
// Verify every #-token is a tag, not a heading (headings have "# " with
// space) and not a record reference: a first line of "#4286 #4290" cites two
// records and stays in the body.
const tokens = match[1].trim().split(/\s+/);
const allTags = tokens.every((t) => /^#[\w]+(?:\/[\w]+)*$/.test(t));
const allTags = tokens.every((t) => /^#[\w]+(?:\/[\w]+)*$/.test(t) && !/^#\d+$/.test(t));
if (!allTags) return text;
return text.slice(match[0].length);
}
@@ -38,7 +41,7 @@ const headingRenderer = {
marked.use({ renderer: headingRenderer });
const PURIFY_OPTS_FULL = {
ADD_ATTR: ["data-tag", "data-title", "data-task-index"],
ADD_ATTR: ["data-tag", "data-title", "data-task-index", "data-ref-space", "data-ref-id"],
FORCE_BODY: true,
};
@@ -64,7 +67,7 @@ export function renderMarkdown(text: string, { interactiveCheckboxes = false } =
}
const withTags = linkifyTags(html);
const withLinks = linkifyWikilinks(withTags);
const withLinks = linkifyRecordRefs(linkifyWikilinks(withTags));
const sanitized = DOMPurify.sanitize(withLinks, PURIFY_OPTS_FULL);
// marked escapes ' to &#39; — replace after sanitization to ensure clean rendering
return sanitized.replace(/&#39;/g, "'");
+104
View File
@@ -0,0 +1,104 @@
/** Record references in rendered prose: `#N`, `milestone N`, `rule N`.
*
* Three id spaces, three forms:
* `#N` a note, task, lesson or snippet (one sequence, the notes table)
* `milestone N` a milestone — the form a batch create writes for `{{ref:milestone}}`
* `rule N` a rule; `preference N` too, since a preference is a rule
* A `#N` after a word that names another numbering ("PR #198", "rule #34",
* "step #3") is not a note, and stays plain text.
*
* The backend reads references with the same patterns and the same word list
* (src/grimoire/services/record_refs.py: REF_RE, PROSE_REF_RE, _OTHER_SPACE),
* so a backlink, a graph edge and a rendered link agree about what a body
* cites. tests/test_record_ref_links.py fails when the two differ.
*
* linkifyRecordRefs only marks the references up. What each one IS — its
* route, its title, whether the reader can open it — is filled in after render
* by the v-record-refs directive (directives/recordRefs.ts), which asks the
* server once per rendered body.
*/
export const NOTE_REF_RE = /(?<![\w&#/])#(\d+)\b/g;
export const PROSE_REF_RE = /(?<![\w/])\b(milestone|rule|preference)\s+#?(\d+)\b/gi;
export const OTHER_SPACE: readonly string[] = [
"pr", "prs", "pull", "pulls", "request", "requests", "mr", "mrs",
"run", "runs", "ci", "build", "builds", "job", "jobs", "pipeline",
"action", "actions", "commit", "github", "gitlab", "gitea", "gh",
"rule", "rules", "preference", "preferences", "milestone", "milestones",
"system", "systems", "project", "projects", "log", "logs", "topic",
"topics", "rulebook", "rulebooks", "step", "steps", "rank", "line",
"lines", "page", "item", "option", "version", "port",
];
const OTHER_SPACE_SET = new Set(OTHER_SPACE);
const PREV_WORD_RE = /([A-Za-z]+)[\s"'(\[*_:]*$/;
export type RefSpace = "notes" | "milestones" | "rules";
export interface RefMatch {
start: number;
end: number;
space: RefSpace;
id: number;
}
function prevWord(before: string): string {
const m = PREV_WORD_RE.exec(before);
return m ? m[1].toLowerCase() : "";
}
/** Every reference in a run of plain text, in order, never overlapping.
* `context` is the text that came before this run, for the word in front of
* a `#N` that starts the run. */
export function findRecordRefs(text: string, context = ""): RefMatch[] {
const found: RefMatch[] = [];
for (const m of text.matchAll(PROSE_REF_RE)) {
const space: RefSpace = m[1].toLowerCase() === "milestone" ? "milestones" : "rules";
found.push({ start: m.index!, end: m.index! + m[0].length, space, id: Number(m[2]) });
}
for (const m of text.matchAll(NOTE_REF_RE)) {
const start = m.index!;
const end = start + m[0].length;
if (found.some((f) => start < f.end && end > f.start)) continue;
if (OTHER_SPACE_SET.has(prevWord(context + text.slice(0, start)))) continue;
found.push({ start, end, space: "notes", id: Number(m[1]) });
}
return found.sort((a, b) => a.start - b.start);
}
/** Where a reference opens before the server has said what it is. A note id
* may turn out to be a task, lesson or snippet; the directive corrects it. */
export function provisionalHref(space: RefSpace, id: number): string {
if (space === "milestones") return `/milestones/${id}`;
if (space === "rules") return `/rules?rule=${id}`;
return `/notes/${id}`;
}
// Markup a reference is never drawn inside: an existing link (a wikilink, a
// markdown link, a tag chip), code, and the tags themselves.
const SKIP_RE = /(<a\b[\s\S]*?<\/a>|<code[\s\S]*?<\/code>|<pre[\s\S]*?<\/pre>|<[^>]+>)/gi;
/** Wrap each record reference in rendered HTML in an `a.record-ref`. */
export function linkifyRecordRefs(html: string): string {
const parts = html.split(SKIP_RE);
let context = "";
return parts
.map((part, i) => {
// Odd indices are markup the split kept; text between them is even.
if (i % 2 === 1) return part;
const refs = findRecordRefs(part, context);
context = (context + part).slice(-80);
if (!refs.length) return part;
let out = "";
let at = 0;
for (const r of refs) {
out += part.slice(at, r.start);
const label = part.slice(r.start, r.end);
out += `<a class="record-ref" data-ref-space="${r.space}" data-ref-id="${r.id}" href="${provisionalHref(r.space, r.id)}">${label}</a>`;
at = r.end;
}
return out + part.slice(at);
})
.join("");
}
+5 -1
View File
@@ -1,5 +1,9 @@
const CODE_FENCE_RE = /```[\s\S]*?```|`[^`\n]+`/g;
const TAG_RE = /(?<!\w)(?<!&)#([\w][\w-]*(?:\/[\w][\w-]*)*)/g;
// A `#` token made only of digits is a record reference (`#3127` names a note,
// task, lesson or snippet; utils/recordRefs.ts links it), never a tag. Digits
// followed by more of a tag (`#2fa`, `#123-notes`) is still a tag. The backend's
// src/grimoire/utils/tags.py holds the same pattern.
export const TAG_RE = /(?<!\w)(?<!&)#(?!\d+(?![\w/-]))([\w][\w-]*(?:\/[\w][\w-]*)*)/g;
function escapeHtmlAttr(s: string): string {
return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+21 -7
View File
@@ -19,6 +19,7 @@ import {
type FamilyIdea, type IdeaSnapshot, type IdeaStatus,
} from "@/api/family";
import FamilyAdoptionMatrix from "@/components/FamilyAdoptionMatrix.vue";
import ScrollSentinel from "@/components/ScrollSentinel.vue";
import { useToastStore } from "@/stores/toast";
import { fmtStamp } from "@/utils/dateFormat";
import { recordHref } from "@/utils/recordHref";
@@ -36,6 +37,8 @@ const loading = ref(true);
const failed = ref(false);
const moreDecisions = ref(false);
const loadingMore = ref(false);
const moreFailed = ref(false);
const decisionOffset = ref(0);
// One pending reversal at a time: which row, which act, and its reason.
const pending = ref<{ kind: "undo" | "retire"; id: number } | null>(null);
@@ -63,7 +66,9 @@ async function load() {
criteria.value = ideaData.criteria;
conflictOrder.value = ideaData.conflict_order ?? [];
decisions.value = log;
decisionOffset.value = log.length;
moreDecisions.value = log.length === PAGE;
moreFailed.value = false;
} catch {
// Said out loud: a log that failed to load must not read as "nothing
// has been decided".
@@ -73,14 +78,20 @@ async function load() {
}
}
// Older decisions load as the log is scrolled. The log is offset-paged, so a
// decision recorded since the first page shifts the rest down by one; a row
// already shown is skipped, and the offset still counts what the server sent.
async function loadMore() {
loadingMore.value = true;
moreFailed.value = false;
try {
const next = await listFamilyDecisions(PAGE, decisions.value.length);
decisions.value.push(...next);
const next = await listFamilyDecisions(PAGE, decisionOffset.value);
const shown = new Set(decisions.value.map((d) => d.id));
decisions.value.push(...next.filter((d) => !shown.has(d.id)));
decisionOffset.value += next.length;
moreDecisions.value = next.length === PAGE;
} catch (e: unknown) {
toast.show(apiErrorMessage(e, "Could not load more decisions"), "error");
} catch {
moreFailed.value = true;
} finally {
loadingMore.value = false;
}
@@ -343,9 +354,12 @@ onMounted(load);
</form>
</li>
</ul>
<button v-if="moreDecisions" class="btn-secondary btn-sm" :disabled="loadingMore" @click="loadMore">
{{ loadingMore ? "Loading…" : "Older decisions" }}
</button>
<ScrollSentinel
:cursor="moreDecisions ? String(decisionOffset) : ''"
:loading="loadingMore"
:failed="moreFailed"
@more="loadMore"
/>
</section>
</template>
</main>
+11 -7
View File
@@ -8,6 +8,7 @@ import { drag } from "d3-drag";
import { select } from "d3-selection";
import { apiGet } from "@/api/client";
import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
const router = useRouter();
@@ -26,7 +27,8 @@ interface GraphNode extends SimulationNodeDatum {
interface GraphEdge {
source: number | string | GraphNode;
target: number | string | GraphNode;
type: "wikilink" | "tag";
/** wikilink: `[[title]]`; reference: a `#N` citation; tag: a shared tag. */
type: "wikilink" | "reference" | "tag";
}
interface Project {
@@ -237,12 +239,14 @@ function initGraph() {
.append("line")
.attr("class", "graph-edge")
.attr("stroke", (d: any) =>
d.type === "wikilink" ? "var(--fs-accent)" : "var(--fs-text-tertiary)"
d.type === "tag" ? "var(--fs-text-tertiary)" : "var(--fs-accent)"
)
.attr("stroke-opacity", (d: any) => (d.type === "wikilink" ? 0.5 : 0.4))
.attr("stroke-dasharray", null)
.attr("stroke-width", (d: any) => (d.type === "wikilink" ? 1.5 : 1))
.attr("marker-end", (d: any) => (d.type === "wikilink" ? "url(#arrow)" : null));
.attr("stroke-opacity", (d: any) => (d.type === "tag" ? 0.4 : 0.5))
// A citation is a looser link than a wikilink: same colour and direction,
// drawn dashed so the two read apart.
.attr("stroke-dasharray", (d: any) => (d.type === "reference" ? "4 3" : null))
.attr("stroke-width", (d: any) => (d.type === "tag" ? 1 : 1.5))
.attr("marker-end", (d: any) => (d.type === "tag" ? null : "url(#arrow)"));
// Node groups
const nodeSel = zoomG
@@ -559,7 +563,7 @@ onUnmounted(() => {
<div
v-else-if="peekBody"
class="prose peek-prose"
v-html="renderMarkdown(peekBody)"
v-html="renderMarkdown(peekBody)" v-record-refs
/>
<div v-else class="peek-empty">No content.</div>
</div>
+50 -67
View File
@@ -1,5 +1,5 @@
<script setup lang="ts">
import { ref, computed, watch, onMounted, onUnmounted, nextTick } from "vue";
import { ref, computed, watch, onMounted, onUnmounted } from "vue";
import { useRouter } from "vue-router";
import { apiGet } from "@/api/client";
import type { TaskKind, TaskStatus, TaskPriority } from "@/types/note";
@@ -10,6 +10,7 @@ import UsageBadge from "@/components/UsageBadge.vue";
import NoteSweepPane from "@/components/NoteSweepPane.vue";
import StatusBadge from "@/components/StatusBadge.vue";
import PriorityBadge from "@/components/PriorityBadge.vue";
import ScrollSentinel from "@/components/ScrollSentinel.vue";
import GraphView from "@/views/GraphView.vue";
import {
FileText,
@@ -193,7 +194,7 @@ function onClickOutsideNewNote(e: MouseEvent) {
const ID_BATCH = 100; // IDs fetched per server round-trip
const INITIAL_CONTENT = 50; // items loaded on first render
const CONTENT_PAGE = 24; // items loaded per sentinel trigger
const CONTENT_PAGE = 24; // items loaded each time the end of the feed nears
const REFILL_THRESHOLD = 48; // fetch more IDs when queue drops below this
const items = ref<KnowledgeItem[]>([]);
@@ -214,11 +215,21 @@ const totalKnowledge = ref(0); // total matching items on server
const allIdsFetched = ref(false); // no more ID pages to fetch
const idsFetching = ref(false); // ID batch request in-flight
const contentFetching = ref(false); // content batch request in-flight
const sentinelVisible = ref(false); // updated by IntersectionObserver
const moreFailed = ref(false); // the last page asked for did not load
const loading = computed(() => idsFetching.value || contentFetching.value);
let fetchGen = 0; // incremented on each reset to invalidate stale responses
const feedGen = ref(0); // fetchGen, readable by the template
// What the next page is keyed on: the feed it belongs to and how many of its ids
// have been loaded. Ids, not items: a batch can return fewer records than it
// asked for, and the feed must still move on. Empty once every id is loaded.
const nextCursor = computed(() =>
idQueue.value.length > 0 || !allIdsFetched.value
? `${feedGen.value}:${idOffset.value - idQueue.value.length}`
: "",
);
function buildFilterParams(): URLSearchParams {
const p = new URLSearchParams();
@@ -244,7 +255,9 @@ async function fetchIdBatch(gen: number) {
idOffset.value += data.ids.length;
totalKnowledge.value = data.total;
if (!data.has_more) allIdsFetched.value = true;
} catch { /* silent */ }
} catch {
if (gen === fetchGen) moreFailed.value = true;
}
finally { if (gen === fetchGen) idsFetching.value = false; }
}
@@ -262,26 +275,38 @@ async function loadNextContent(gen: number, count: number) {
if (idQueue.value.length < REFILL_THRESHOLD && !allIdsFetched.value && !idsFetching.value) {
fetchIdBatch(gen);
}
} catch { /* silent */ }
finally {
if (gen !== fetchGen) return;
contentFetching.value = false;
// Sentinel may still be visible if new items didn't push it off screen
await nextTick();
if (sentinelVisible.value && idQueue.value.length > 0 && gen === fetchGen) {
loadNextContent(gen, CONTENT_PAGE);
} catch {
// The ids go back to the front of the queue, so Try again asks for the
// same records rather than skipping past them.
if (gen === fetchGen) {
idQueue.value.unshift(...toLoad);
moreFailed.value = true;
}
}
finally {
if (gen === fetchGen) contentFetching.value = false;
}
}
// The next page of the feed: more ids first when the queue has run dry.
async function loadMore() {
const gen = fetchGen;
moreFailed.value = false;
if (idQueue.value.length === 0) await fetchIdBatch(gen);
if (gen !== fetchGen) return;
await loadNextContent(gen, CONTENT_PAGE);
}
async function reset() {
fetchGen++;
feedGen.value = fetchGen;
const gen = fetchGen;
items.value = [];
idQueue.value = [];
idOffset.value = 0;
totalKnowledge.value = 0;
allIdsFetched.value = false;
moreFailed.value = false;
await fetchIdBatch(gen);
if (gen !== fetchGen) return;
await loadNextContent(gen, INITIAL_CONTENT);
@@ -294,23 +319,16 @@ async function fetchTags() {
} catch { /* silent */ }
}
async function resetAndReobserve() {
await reset();
await nextTick();
setupObserver();
}
function onSearchInput() {
if (searchDebounce) clearTimeout(searchDebounce);
searchDebounce = setTimeout(() => resetAndReobserve(), 380);
searchDebounce = setTimeout(() => reset(), 380);
}
watch([activeType, sortMode], () => resetAndReobserve());
// Closing the sweep remounts the feed, and with it the scroll sentinel — a
// fresh element the old observer is not watching. Without this the list loads
// its first page and then never loads another.
watch(sweepActive, (open) => { if (!open) resetAndReobserve(); });
watch(activeTag, () => { fetchCounts(); resetAndReobserve(); });
watch([activeType, sortMode], () => reset());
// Closing the sweep starts the feed over, so a note confirmed in the sweep is
// shown as it now stands.
watch(sweepActive, (open) => { if (!open) reset(); });
watch(activeTag, () => { fetchCounts(); reset(); });
// ─── Today bar ────────────────────────────────────────────────────────────────
@@ -377,24 +395,6 @@ function formatDate(iso: string): string {
return d.toLocaleDateString(undefined, { month: "short", day: "numeric", year: "numeric" });
}
// ─── Sentinel observer ────────────────────────────────────────────────────────
const sentinelEl = ref<HTMLElement | null>(null);
let observer: IntersectionObserver | null = null;
function setupObserver() {
observer?.disconnect();
if (!sentinelEl.value) return;
observer = new IntersectionObserver(
([entry]) => {
sentinelVisible.value = entry.isIntersecting;
if (entry.isIntersecting) loadNextContent(fetchGen, CONTENT_PAGE);
},
{ root: null, rootMargin: "200px" }
);
observer.observe(sentinelEl.value);
}
// ─── Lifecycle ────────────────────────────────────────────────────────────────
onMounted(async () => {
@@ -403,14 +403,11 @@ onMounted(async () => {
fetchTags();
fetchCounts();
fetchTodayBar();
await nextTick();
setupObserver();
});
onUnmounted(() => {
document.removeEventListener('click', onClickOutsideNewNote);
if (searchDebounce) clearTimeout(searchDebounce);
observer?.disconnect();
});
</script>
@@ -583,10 +580,7 @@ onUnmounted(() => {
</div>
<!-- The whole feed stands down while the sweep is open: two answers
to two different questions on one screen is neither. Wrapped
rather than given an extra v-if branch, because the scroll
sentinel lives inside the grid and the observer must not be left
holding a ref to something that never renders. -->
to two different questions on one screen is neither. -->
<template v-if="!sweepActive">
<!-- Loading / empty -->
<div v-if="loading && items.length === 0" class="knowledge-empty">Loading…</div>
@@ -675,10 +669,12 @@ onUnmounted(() => {
</div>
</div>
<!-- Sentinel — IntersectionObserver triggers next content batch -->
<div ref="sentinelEl" class="scroll-sentinel">
<span v-if="contentFetching" class="sentinel-loading">Loading…</span>
</div>
<ScrollSentinel
:cursor="nextCursor"
:loading="loading"
:failed="moreFailed"
@more="loadMore"
/>
</div>
</template>
</div>
@@ -1115,19 +1111,6 @@ onUnmounted(() => {
opacity: 0.85;
}
/* ── Sentinel ────────────────────────────────────────────── */
.scroll-sentinel {
grid-column: 1 / -1;
height: 40px;
display: flex;
align-items: center;
justify-content: center;
}
.sentinel-loading {
font-size: 0.8rem;
color: var(--fs-text-tertiary);
}
/* ── Graph panel ─────────────────────────────────────────── */
.graph-panel {
width: 500px;
+2 -1
View File
@@ -40,6 +40,7 @@ import UsageBadge from "@/components/UsageBadge.vue";
import { DEAD_WEIGHT_ADVICE } from "@/utils/deadWeight";
import { useToastStore } from "@/stores/toast";
import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import { canWriteRecord } from "@/utils/permission";
import { recordHref } from "@/utils/recordHref";
@@ -171,7 +172,7 @@ onMounted(load);
<div
v-if="insightHtml"
class="ld-insight markdown-body"
v-html="insightHtml"
v-html="insightHtml" v-record-refs
/>
<p v-else class="ld-muted ld-empty">
No detail was recorded — the claim above is the whole lesson.
+2 -1
View File
@@ -5,6 +5,7 @@ import type { NoteType } from "@/types/note";
import { useNotesStore } from "@/stores/notes";
import { useToastStore } from "@/stores/toast";
import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import { useAssist, type NoteDraft } from "@/composables/useAssist";
import { useAutoSave } from "@/composables/useAutoSave";
import { useEditorGuards } from "@/composables/useEditorGuards";
@@ -439,7 +440,7 @@ onUnmounted(() => assist.clearSelection());
<div
v-else
class="preview-pane prose"
v-html="renderedPreview"
v-html="renderedPreview" v-record-refs
/>
</Transition>
</template>
+11 -3
View File
@@ -3,6 +3,8 @@ import { onMounted, computed, ref, watch } from "vue";
import { useRoute, useRouter } from "vue-router";
import { useNotesStore } from "@/stores/notes";
import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import { recordHref } from "@/utils/recordHref";
import { relativeTime } from "@/composables/useRelativeTime";
import { apiPost, apiGet, apiPatch } from "@/api/client";
import type { Note } from "@/types/note";
@@ -14,7 +16,12 @@ import { Clock, Pencil, Link as LinkIcon } from "lucide-vue-next";
const route = useRoute();
const router = useRouter();
const store = useNotesStore();
const backlinks = ref<{ type: string; id: number; title: string }[]>([]);
/** What links here, and how: a `[[title]]` wikilink or a `#N` reference in a
* body or work log. */
const backlinks = ref<{
type: string; id: number; title: string;
is_task?: boolean; note_type?: string; via?: "wikilink" | "reference";
}[]>([]);
const converting = ref(false);
const showShare = ref(false);
@@ -259,7 +266,7 @@ async function convertToTask() {
<div
class="body prose"
:class="{ 'prose--checklist': isListNote }"
v-html="renderedBody"
v-html="renderedBody" v-record-refs
@click="onBodyClick"
@change="onBodyChange"
></div>
@@ -274,7 +281,8 @@ async function convertToTask() {
<router-link
v-for="link in backlinks"
:key="`${link.type}-${link.id}`"
:to="`/${link.type === 'note' ? 'notes' : 'tasks'}/${link.id}`"
:to="recordHref({ id: link.id, is_task: link.is_task ?? link.type === 'task', note_type: link.note_type })"
:title="link.via === 'reference' ? `Cites #${noteId} in its text` : `Links here by title`"
class="backlink-card"
>
<span :class="['backlink-type-badge', `badge-${link.type}`]">{{ link.type }}</span>
+29 -3
View File
@@ -1,5 +1,5 @@
<script setup lang="ts">
import { ref, computed, onMounted, watch } from "vue";
import { ref, computed, onMounted, watch, nextTick } from "vue";
import { useRoute, useRouter } from "vue-router";
import { apiGet, apiPatch, apiDelete, apiPost, apiPut, apiErrorMessage } from "@/api/client";
import { useAuthStore } from "@/stores/auth";
@@ -7,6 +7,7 @@ import { useToastStore } from "@/stores/toast";
import { useTasksStore } from "@/stores/tasks";
import { relativeTime } from "@/composables/useRelativeTime";
import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import ShareDialog from "@/components/ShareDialog.vue";
import KindBadge from "@/components/KindBadge.vue";
import ProjectStatusBadge from "@/components/ProjectStatusBadge.vue";
@@ -585,8 +586,27 @@ async function saveForgePin() {
}
}
/** `?milestone=N` opens the board at that milestone: the Tasks tab, the
* milestone expanded and scrolled into view, its header focused. This is
* where a `milestone N` reference in any body leads. */
async function focusMilestoneFromRoute() {
const id = Number(route.query.milestone);
if (!id || !milestones.value.some((m) => m.id === id)) return;
activeTab.value = "tasks";
collapsedMilestones.value.delete(id);
await nextTick();
const header = document.querySelector<HTMLElement>(
`[data-milestone-id="${id}"] .milestone-header`,
);
header?.scrollIntoView({ block: "start", behavior: "smooth" });
header?.focus({ preventScroll: true });
}
watch(() => route.query.milestone, () => void focusMilestoneFromRoute());
onMounted(async () => {
await loadProject();
void focusMilestoneFromRoute();
loadTasks();
loadNotes();
loadDesignSystems();
@@ -985,9 +1005,15 @@ async function confirmDelete() {
</div>
</div>
<div v-for="group in milestoneGroups" :key="group.milestone?.id ?? 'unassigned'" class="milestone-group">
<div
v-for="group in milestoneGroups"
:key="group.milestone?.id ?? 'unassigned'"
class="milestone-group"
:data-milestone-id="group.milestone?.id"
>
<div
class="milestone-header"
tabindex="-1"
:class="{ clickable: renamingMilestoneId !== group.milestone?.id }"
:aria-expanded="!collapsedMilestones.has(groupKey(group))"
@click="renamingMilestoneId !== group.milestone?.id && toggleMilestoneCollapse(groupKey(group))"
@@ -1050,7 +1076,7 @@ async function confirmDelete() {
:class="['ms-plan-rendered', 'markdown-body',
{ 'ms-plan-clamped': isPlanClamped(group.milestone) }]"
@click="startEditPlan(group.milestone.id, group.milestone.body)"
v-html="renderMarkdown(group.milestone.body || '')"
v-html="renderMarkdown(group.milestone.body || '')" v-record-refs
></div>
<button
v-if="isPlanLong(group.milestone)"
+16 -52
View File
@@ -9,8 +9,10 @@ import { apiGet, apiPost, apiPut, apiDelete, listGroups, createGroup, deleteGrou
import type { User } from "@/types/auth";
import PaginationBar from "@/components/PaginationBar.vue";
import MomentsSettings from "@/components/MomentsSettings.vue";
import ReverseProxySettings from "@/components/ReverseProxySettings.vue";
import ReplyShapesSettings from "@/components/ReplyShapesSettings.vue";
import BackupScheduleSettings from "@/components/BackupScheduleSettings.vue";
import RestoreBackupDialog from "@/components/RestoreBackupDialog.vue";
import { formatBytes } from "@/utils/bytes";
import { fmtDate, fmtLogStamp } from "@/utils/dateFormat";
import { fetchVersion, type VersionPayload } from "@/api/version";
@@ -467,7 +469,7 @@ const confirmNewPassword = ref("");
const changingPassword = ref(false);
const invalidatingSessions = ref(false);
const exporting = ref(false);
const restoring = ref(false);
const showRestore = ref(false);
// Backup, export and restore walk the whole store, so they are slow BY DESIGN
// and the client's ordinary 30s default would cut them off mid-work. They are
// still bounded — every wait has a deadline, not necessarily a short one — and
@@ -509,7 +511,6 @@ async function copyCommit() {
commitCopied.value = true;
setTimeout(() => { commitCopied.value = false; }, 2000);
}
const restoreFileInput = ref<HTMLInputElement | null>(null);
// Migrate stored "admin" → "config"; unknown tabs fall back to "general"
const VALID_TABS = new Set(["general", "account", "notifications", "integrations", "data", "apikeys", "config", "users", "logs", "groups", "areas", "platforms"]);
@@ -1079,10 +1080,6 @@ async function exportNotes(format: "markdown" | "json") {
}
}
function triggerRestoreUpload() {
restoreFileInput.value?.click();
}
async function saveNotifications() {
savingNotifications.value = true;
notificationsSaved.value = false;
@@ -1279,42 +1276,6 @@ async function runDbMaintenanceNow() {
}
}
async function handleRestoreFile(event: Event) {
const file = (event.target as HTMLInputElement).files?.[0];
if (!file) return;
restoring.value = true;
try {
// The scheduled backup's .tar goes up as it is; the JSON download is
// parsed first so a damaged file fails here, before the upload.
const isTar = file.name.toLowerCase().endsWith(".tar");
const res = await fetch("/api/admin/restore", {
method: "POST",
headers: { "Content-Type": isTar ? "application/x-tar" : "application/json" },
body: isTar ? file : JSON.stringify(JSON.parse(await file.text())),
signal: bulkDeadline(),
});
if (res.status === 413) {
throw new Error(
"the file is bigger than the web upload allows. Restore it with " +
"`python -m grimoire.restore <file>` inside the Grimoire container instead.",
);
}
if (!res.ok) {
const body = await res.json().catch(() => ({ error: `Error ${res.status}` }));
throw new Error((body as Record<string, string>).error || `Error ${res.status}`);
}
const result = await res.json();
toastStore.show(
`Restored ${result.stats?.users ?? 0} users, ${result.stats?.notes ?? 0} notes, ${result.stats?.conversations ?? 0} conversations`
);
} catch (e) {
toastStore.show("Restore failed: " + (e as Error).message, "error");
} finally {
restoring.value = false;
if (restoreFileInput.value) restoreFileInput.value.value = "";
}
}
async function testSearch() {
const q = searchQuery.value.trim();
if (!q) return;
@@ -2429,17 +2390,11 @@ async function deleteUser(userId: number) {
<button class="btn-secondary" @click="exportData('full')" :disabled="exporting">
{{ exporting ? "Exporting..." : "Full Backup" }}
</button>
<button class="btn-secondary btn-warn" @click="triggerRestoreUpload" :disabled="restoring">
{{ restoring ? "Restoring..." : "Restore from Backup" }}
<button class="btn-secondary btn-warn" @click="showRestore = true">
Restore from Backup
</button>
<input
ref="restoreFileInput"
type="file"
accept=".json,.tar"
class="hidden-file-input"
@change="handleRestoreFile"
/>
</div>
<RestoreBackupDialog v-if="showRestore" @close="showRestore = false" />
</section>
<section class="settings-section full-width">
<h2>Scheduled backups</h2>
@@ -2710,6 +2665,16 @@ async function deleteUser(userId: number) {
<div v-else class="empty-msg">Nothing asked yet.</div>
</section>
<section class="settings-section full-width">
<h2>Reverse proxy</h2>
<p class="section-desc">
How many proxies a request passes through before it reaches Grimoire. Sign-in rate
limits and the audit log key on the visitor's address, read through this count; if it
is too low, every visitor reads as the proxy and one run of bad sign-ins blocks everyone.
</p>
<ReverseProxySettings />
</section>
<section class="settings-section full-width">
<h2>Application URL</h2>
<p class="section-desc">
@@ -3597,7 +3562,6 @@ async function deleteUser(userId: number) {
flex-wrap: wrap;
gap: 0.5rem;
}
.hidden-file-input { display: none; }
/* Checkboxes */
.checkbox-field { margin-bottom: 1rem; }
+2 -1
View File
@@ -10,6 +10,7 @@ import {
import { useToastStore } from "@/stores/toast";
import ConfirmDialog from "@/components/ConfirmDialog.vue";
import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import { canWriteRecord } from "@/utils/permission";
const route = useRoute();
@@ -185,7 +186,7 @@ async function confirmDelete() {
<section v-if="snippet.snippet.notes" class="notes">
<h2 class="notes-heading">Notes</h2>
<div class="prose" v-html="renderMarkdown(snippet.snippet.notes)" />
<div class="prose" v-html="renderMarkdown(snippet.snippet.notes)" v-record-refs />
</section>
<div v-if="snippet.tags.length" class="tag-row">
+2 -1
View File
@@ -5,6 +5,7 @@ import { useTasksStore } from "@/stores/tasks";
import { useNotesStore } from "@/stores/notes";
import { useToastStore } from "@/stores/toast";
import { renderMarkdown } from "@/utils/markdown";
import { vRecordRefs } from "@/directives/recordRefs";
import { useAssist } from "@/composables/useAssist";
import { useAutoSave } from "@/composables/useAutoSave";
import { useEditorGuards } from "@/composables/useEditorGuards";
@@ -538,7 +539,7 @@ useEditorGuards(dirty, save);
<div
v-show="showPreview"
class="preview-pane prose"
v-html="renderedPreview"
v-html="renderedPreview" v-record-refs
/>
</template>
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "grimoire",
"description": "Grimoire for Claude Code: connects the grimoire MCP server, adds the hooks that deliver live project state and relevant records at the right moment, ships the shared client-neutral Grimoire skills (using-grimoire, writing-plans, reporting-back, systematic-debugging, verification, brainstorming, reusing-code, shape-accounting, family-canon), and syncs your saved Grimoire Processes as skills (/grimoire:sync).",
"version": "2026.10.22.1945",
"version": "2026.11.22.2312",
"author": {
"name": "Bryan Van Deusen"
},
+2 -1
View File
@@ -15,7 +15,7 @@ another one means adding files, not moving or rewriting any.
|---|---|---|
| **The skills** | `plugin/skills/*/SKILL.md` | Agent Skills (the open SKILL.md format). They state every Grimoire reflex in full and name no client. `tests/test_guidance_ownership.py` fails if a skill names a particular client, or references anything outside its own folder. Every client package ships this folder verbatim. |
| **The MCP server** | `<base URL>/mcp` | HTTP, `Authorization: Bearer <fmcp_ key>`. Its `_INSTRUCTIONS` is a client-neutral orientation — the workflow across tools (≤1,600 chars); each tool's description carries its contract; in-band responses (`placement`, `report_back`, `systems_hint`, the duplicate gate, the guessed-id refusal) fire in every client. |
| **The adapter API** | `<base URL>/api/plugin/*` | Endpoints any client's hooks can call with the same key. `GET`, so read scope is enough: `context` (live session state), `retrieve` (rules, preferences and notes for a message), `prior-art` (records and shape-ledger hints for code being written), `tool-rules` (rules for a command about to run), `moment-tools` (which tools reach a mounted moment), `shape-check` (definitions written this turn that nobody has judged), `claim-session` / `release-session` (task claims), `processes` (stored Processes to expose as skills). `POST`, so write scope: `moment` (rules mounted on the moments a tool call reaches), `rule-opened` (a rule was read), `reply-rules` (the finished reply, held for an unopened rule or — when the turn closed a task — for missing completion sections). |
| **The adapter API** | `<base URL>/api/plugin/*` | Endpoints any client's hooks can call with the same key. `GET`, so read scope is enough: `context` (live session state), `retrieve` (rules, preferences and notes for a message), `prior-art` (records and shape-ledger hints for code being written), `tool-rules` (rules for a command about to run), `moment-tools` (which tools reach a mounted moment), `shape-check` (definitions written this turn that nobody has judged), `claim-session` / `release-session` (task claims), `write-scope` (which project a pending write lands in, and whether this session may make it), `processes` (stored Processes to expose as skills). `POST`, so write scope: `moment` (rules mounted on the moments a tool call reaches), `rule-opened` (a rule was read), `reply-rules` (the finished reply, held for an unopened rule or — when the turn closed a task — for missing completion sections). |
| **The API key** | Grimoire → Settings → MCP Access | One `fmcp_` key per install. Write scope covers the MCP tools and every hook; a read key runs only the `GET` hooks. |
## Added by each client
@@ -39,6 +39,7 @@ another one means adding files, not moving or rewriting any.
| `hooks/grimoire_prior_art.sh` | PreToolUse on editor writes: `GET /api/plugin/prior-art`. |
| `hooks/grimoire_after_write.sh` | PostToolUse on shell commands: the same check for code written through the shell. |
| `hooks/grimoire_tool_rules.sh` | PreToolUse on shell commands: `GET /api/plugin/tool-rules`. |
| `hooks/grimoire_project_fence.sh` | PreToolUse on editor writes, shell commands and Grimoire's tools: `GET /api/plugin/write-scope` for an act aimed at another project, answered `ask` with the reason; PostToolUse on `enter_project` remembers the project a session without one entered. |
| `hooks/grimoire_moment.sh` | PreToolUse on every tool: the rules mounted on the moments the call reaches, `POST /api/plugin/moment`; skips tools `GET /api/plugin/moment-tools` says reach nothing mounted, and Grimoire's own (their responses carry `moment_rules`). |
| `hooks/grimoire_reply_check.sh` | Stop: sends the finished reply to `POST /api/plugin/reply-rules` — the rules mounted on the reply moments, and the reply against every rule's trigger, and — when the turn closed a task — the completion-section check; holds once per rule, with the reason the server returns, and never holds the rewrite. |
| `hooks/grimoire_shape_check.sh` | Stop: sends the definitions the turn wrote (the write hooks' `<sid>.written.ids` ledger) to `GET /api/plugin/shape-check`; blocks once, with the reason the server returns, so the agent judges what it built. |
+14
View File
@@ -79,6 +79,20 @@ On install you'll be asked for:
message, as a short menu of titles and matched passages.
- `hooks/hooks.json` → PreToolUse hook on `Bash` (`hooks/grimoire_tool_rules.sh`)
→ `GET /api/plugin/tool-rules`: the rules that match the command about to run.
- `hooks/hooks.json` → PreToolUse hook on editor writes, `Bash` and Grimoire's
tools (`hooks/grimoire_project_fence.sh`) → `GET /api/plugin/write-scope`:
holds a session to its own project. A session belongs to the project its
starting directory resolves to (a `.grimoire` marker, else the git remote's
binding), or, started outside any, to the first project it enters. Editing
another project's files, a git commit, push, merge, rebase, pull, tag or
reset in its repo (from `git -C`, after `cd`, or in a worktree of it), and a
Grimoire write that lands in another project each stop on a permission
prompt naming that project, in every permission mode. Filing an issue there
(`create_task(kind="issue")`) and every read go ahead. An edit in the
session's own repo never calls the server. It can't see a non-git shell
write into another repo (`sed -i`, a redirect), but it fences that repo's
commit and push. When the instance doesn't answer, the act goes ahead and
the hook says so once per outage.
- `hooks/hooks.json` → PreToolUse hook on every tool (`hooks/grimoire_moment.sh`)
→ `POST /api/plugin/moment`: the rules mounted on the moments the call
reaches. It skips tools that `GET /api/plugin/moment-tools` says reach
+14 -8
View File
@@ -119,10 +119,11 @@ combined=""
n_files=0
while IFS= read -r rel_path; do
[ -n "${rel_path:-}" ] || continue
# A Bash call that rewrote many files is a refactor or a generator, not a
# shape being instantiated; four is enough to name what matters.
# Every changed file goes into the end-of-turn ledger, up to forty — a bound
# on this hook's run time, past which the call was a generator. The arms
# below speak for the first four only (see the check after the ledger).
n_files=$((n_files + 1))
[ "$n_files" -le 4 ] || break
[ "$n_files" -le 40 ] || break
file_path="$repo_root/$rel_path"
# The code just written: the ADDED lines of the uncommitted diff for a
@@ -136,14 +137,19 @@ while IFS= read -r rel_path; do
fresh="new"
fi
[ -n "$code" ] || continue
# `|| true` inside: an early-exiting `head` must not void its own output.
names=$(printf '%s' "$code" | grimoire_defs | sort -u | head -12 || true)
# What this write defined, for the end-of-turn question —
all_names=$(printf '%s' "$code" | grimoire_defs | sort -u || true)
# What this write defined, for the end-of-turn question: every definition,
# recorded before the arms below, which skip a write that defines nothing.
printf '%s\n' "$names" | grimoire_written_append "$safe_sid" "$rel_path" "$fresh" "$code"
printf '%s\n' "$all_names" | grimoire_written_append "$safe_sid" "$rel_path" "$fresh" "$code"
# Nothing DEFINED in what was written (prose, data, a call-site edit) →
# nothing to say; the arms are about shapes.
[ -n "$names" ] || continue
[ -n "$all_names" ] || continue
# A Bash call that rewrote many files is a refactor or a generator, not a
# shape being instantiated; four files and twelve names per file are enough
# for the arms to name what matters, and bound their git grep and URL.
[ "$n_files" -le 4 ] || continue
# `|| true` inside: an early-exiting `head` must not void its own output.
names=$(printf '%s\n' "$all_names" | head -12 || true)
local_lines=$(grimoire_local_dups "$repo_root" "$rel_path" <<< "$names") || local_lines=""
local_context=""
+2
View File
@@ -125,6 +125,8 @@ if [ -n "$session_id" ]; then
[ -n "$rule_seen" ] && exclude_q="${exclude_q}&exclude_rule_ids=${rule_seen}"
# What the session actually OPENED, as against what it was shown.
exclude_q="${exclude_q}$(grimoire_held_query "$rule_state_dir/${safe_sid}.opened.ids")"
# Which session the rule lines go to, so each is recorded as a delivery.
exclude_q="${exclude_q}&session_id=${safe_sid}"
# Which reply shapes it already holds in full: the core is
# sent whole once, and as its one-line reminder on every later turn.
shapefile=$(grimoire_shapes_file "$safe_sid")
+12 -3
View File
@@ -79,10 +79,16 @@ fi
# ARM 1 — BY NAME, LOCALLY: does a definition of this already exist
# in the repo? (grimoire_local_dups in grimoire_defs.sh carries the why.)
#
# `all_names` is every definition the write carries; it feeds the end-of-turn
# ledger, which must hear about all of them. `names` is the first twelve, and
# bounds the queries below — a git grep and a URL per name.
all_names=""
names=""
if [ -n "$code" ]; then
all_names=$(printf '%s' "$code" | grimoire_defs | sort -u || true)
# `|| true` inside: an early-exiting `head` must not void its own output.
names=$(printf '%s' "$code" | grimoire_defs | sort -u | head -12 || true)
names=$(printf '%s\n' "$all_names" | head -12 || true)
fi
local_lines=""
@@ -204,10 +210,11 @@ if [ -n "$session_id" ]; then
# Write onto a path that does not exist yet creates a file, which may be a
# unit in its own right (see grimoire_written_append). Written before any
# server call: the ask at the end of the turn must not depend on this
# write's hint having been answered.
# write's hint having been answered. Every definition, not the capped list
# the queries use; an Edit that names none records its enclosing one.
fresh=""
[ -e "$file_path" ] || fresh="new"
printf '%s\n' "$shapes" | grimoire_written_append "$safe_sid" "$rel_path" "$fresh" "$code"
printf '%s\n' "${all_names:-$shapes}" | grimoire_written_append "$safe_sid" "$rel_path" "$fresh" "$code"
idfile="$state_dir/${safe_sid}.ids"
syncfile="$state_dir/${safe_sid}.sync.ids"
derivefile="$state_dir/${safe_sid}.derive.ids"
@@ -233,6 +240,8 @@ if [ -n "$session_id" ]; then
[ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
# What the session actually OPENED, as against what it was shown.
rule_exclude_q="${rule_exclude_q}$(grimoire_held_query "$state_dir/${safe_sid}.opened.ids")"
# Which session the rule lines go to, so each is recorded as a delivery.
rule_exclude_q="${rule_exclude_q}&session_id=${safe_sid}"
fi
# Not `|| exit 0`: an unreachable instance must not discard a local finding
+246
View File
@@ -0,0 +1,246 @@
#!/usr/bin/env bash
# Grimoire — hold a session to its own project.
#
# A session belongs to the project its starting directory resolves to
# (CLAUDE_PROJECT_DIR: a `.grimoire` marker, else the git remote's binding). A
# session that starts outside any project belongs to the first project it
# enters. Toward any other project a session may read anything and file an
# issue. Every other write stops on a permission prompt naming the other
# project, so the operator decides:
# - editing a file in another project's repo (Write, Edit, MultiEdit,
# NotebookEdit);
# - a git command that changes history or a remote there (commit, push,
# merge, rebase, pull, cherry-pick, revert, tag, am, reset, worktree add),
# wherever it runs from: `git -C DIR`, `cd DIR && git …`, or the shell's
# current directory;
# - a Grimoire write that lands in another project.
#
# `ask`, not `deny`. Which projects a session may change is the operator's
# call, and `ask` puts it to them each time, in every permission mode,
# bypassPermissions included.
#
# The server says where an act lands (GET /api/plugin/write-scope). Two cases
# never reach it:
# - a directory that resolves the same way as the session's own, which is
# nearly every edit;
# - a tool named like a read (READ_PREFIXES in services/write_scope.py, held
# equal to FENCE_READ_PREFIXES below by tests/test_write_scope.py).
#
# What it can't see: a non-git write from the shell (`sed -i`, a redirect)
# into another repo. That repo's commit and push are still fenced.
#
# EXIT 0, ALWAYS. When the server doesn't answer, the act goes ahead and the
# hook says once per outage that it couldn't check.
#
# Run as PostToolUse on enter_project, it records the project a session
# without one has entered, and says nothing.
set -uo pipefail
# shellcheck source=plugin/hooks/grimoire_defs.sh
. "$(dirname "${BASH_SOURCE[0]}")/grimoire_defs.sh"
FENCE_READ_PREFIXES="get_ list_ search find_ enter_project what_might_apply resolve_design_system"
FENCE_GIT_WRITES="commit push merge rebase pull cherry-pick revert tag am reset"
event=$(cat 2>/dev/null || true)
[ -n "$event" ] || exit 0
event_flat=$(printf '%s' "$event" | grimoire_json_flat)
[ -n "$event_flat" ] || exit 0
session_id=$(grimoire_json_pick "$event_flat" '.session_id')
tool_name=$(grimoire_json_pick "$event_flat" '.tool_name')
hook_event=$(grimoire_json_pick "$event_flat" '.hook_event_name')
cwd=$(grimoire_json_pick "$event_flat" '.cwd')
# Its own directory, which no compaction sweeps: the project a session
# entered stays its project for the whole session.
state_dir="${TMPDIR:-/tmp}/grimoire-fence"
safe_sid=$(printf '%s' "${session_id:-none}" | tr -c 'A-Za-z0-9._-' '_')
entered_file="$state_dir/${safe_sid}.entered"
# ── PostToolUse on enter_project: remember the first project entered ─────
if [ "$hook_event" = "PostToolUse" ]; then
case "$tool_name" in
*__enter_project)
pid=$(grimoire_json_pick "$event_flat" '.tool_input.project_id' | tr -cd '0-9')
if [ -n "$pid" ] && [ -n "$session_id" ] && [ ! -s "$entered_file" ]; then
mkdir -p "$state_dir" 2>/dev/null || true
printf '%s' "$pid" > "$entered_file" 2>/dev/null || true
fi
;;
esac
exit 0
fi
# The nearest directory at or above $1 that exists. A Write may create the
# directories its file goes in.
fence_existing_dir() {
local d="$1" depth=0
while [ -n "$d" ] && [ ! -d "$d" ] && [ "$depth" -lt 40 ]; do
d=$(dirname -- "$d" 2>/dev/null) || return 0
depth=$((depth + 1))
done
[ -d "$d" ] && printf '%s' "$d"
}
# "DIR<TAB>SUBCOMMAND" for each git command in the shell command $1 that
# changes history or a remote, with DIR resolved from $2: `cd` moves it for
# the segments after, `git -C` for that one command. Segments split on ; && ||
# | and newlines, and a quoted separator inside a message splits too; the
# words after it are read as a command only if they start with cd or git.
fence_git_targets() {
printf '%s\n' "$1" | awk -v start="$2" -v home="${HOME:-}" -v writes="$FENCE_GIT_WRITES" '
function unq(w) { gsub(/^["\047(]+|["\047)]+$/, "", w); return w }
function at(base, p) {
if (p ~ /^\//) return p
if (p == "~") return home
if (p ~ /^~\//) return home substr(p, 2)
return base "/" p
}
BEGIN { dir = start; n = split(writes, w, " "); for (i = 1; i <= n; i++) iswrite[w[i]] = 1 }
{
line = $0
gsub(/&&|\|\||;|\|/, "\n", line)
m = split(line, segs, "\n")
for (s = 1; s <= m; s++) {
k = split(segs[s], t, /[ \t]+/)
i = 1
while (i <= k && (t[i] == "" || t[i] ~ /^[A-Za-z_][A-Za-z0-9_]*=/)) i++
if (i > k) continue
cmd = unq(t[i])
if (cmd == "cd") {
if (i + 1 <= k && t[i + 1] != "") dir = at(dir, unq(t[i + 1]))
continue
}
if (cmd != "git" && cmd !~ /\/git$/) continue
gdir = dir; i++
while (i <= k && t[i] ~ /^-/) {
if (t[i] == "-C" && i + 1 <= k) { gdir = at(gdir, unq(t[i + 1])); i += 2; continue }
if (t[i] == "-c" || t[i] == "--git-dir" || t[i] == "--work-tree") { i += 2; continue }
i++
}
if (i > k) continue
sub_ = unq(t[i])
if (sub_ == "worktree") { if (i + 1 <= k && unq(t[i + 1]) == "add") print gdir "\tworktree add"; continue }
if (sub_ in iswrite) print gdir "\t" sub_
}
}' 2>/dev/null || true
}
# The short scalar arguments of the MCP call, as a JSON object of strings:
# ids, kind, status, a repo url, and arrays of ids. Long text (bodies, code) is
# left out; nothing that says where a write lands is long.
fence_tool_input() {
printf '%s\n' "$event_flat" | awk -F'\t' '
function add(k, v) { if (!(k in seen)) { seen[k] = 1; order[++n] = k } }
$2 ~ /^\.tool_input\.[A-Za-z_]+$/ && $3 != "null" && length($3) <= 200 {
k = substr($2, 13); add(k); val[k] = "\"" $3 "\""
}
$2 ~ /^\.tool_input\.[A-Za-z_]+\[[0-9]+\]$/ && $3 != "null" && length($3) <= 200 {
k = substr($2, 13); sub(/\[.*$/, "", k); add(k)
# Tested before assigning: mawk creates arr[k] as soon as it is the
# target, so the test inside the assignment would always be true.
item = "\"" $3 "\""
if (k in arr) item = arr[k] "," item
arr[k] = item
}
END {
printf "{"
for (i = 1; i <= n; i++) {
k = order[i]
printf "%s\"%s\":%s", (i > 1 ? "," : ""), k, ((k in arr) ? "[" arr[k] "]" : val[k])
}
printf "}"
}' 2>/dev/null || printf '{}'
}
grimoire_config || exit 0
command -v curl >/dev/null 2>&1 || exit 0
project_dir=${CLAUDE_PROJECT_DIR:-$PWD}
session_scope=$(grimoire_scope_query "$project_dir")
entered=$(cat "$entered_file" 2>/dev/null | tr -cd '0-9')
# No project to hold the session to: started outside any, and entered none.
[ -n "$session_scope" ] || [ -n "$entered" ] || exit 0
# Each check this act needs: "SCOPE<TAB>ACT" for a directory, or a single
# "tool" line for a Grimoire call.
checks=""
case "$tool_name" in
Write|Edit|MultiEdit|NotebookEdit)
path=$(grimoire_json_pick "$event_flat" '.tool_input.file_path')
[ -n "$path" ] || path=$(grimoire_json_pick "$event_flat" '.tool_input.notebook_path')
[ -n "$path" ] || exit 0
case "$path" in /*) ;; *) path="${cwd:-$PWD}/$path" ;; esac
dir=$(fence_existing_dir "$(dirname -- "$path")")
[ -n "$dir" ] || exit 0
scope=$(grimoire_scope_query "$dir")
[ -n "$scope" ] && [ "$scope" != "$session_scope" ] || exit 0
checks=$(printf '%s\t%s' "$scope" "Editing a file in")
;;
Bash)
command=$(grimoire_json_pick "$event_flat" '.tool_input.command')
case "$command" in *git*) ;; *) exit 0 ;; esac
while IFS=$'\t' read -r gdir gsub; do
[ -n "$gdir" ] || continue
[ -d "$gdir" ] || continue
scope=$(grimoire_scope_query "$gdir")
[ -n "$scope" ] && [ "$scope" != "$session_scope" ] || continue
checks="${checks}${checks:+$'\n'}${scope}"$'\t'"git ${gsub} in"
done <<EOF
$(fence_git_targets "$command" "${cwd:-$PWD}")
EOF
[ -n "$checks" ] || exit 0
;;
mcp__*)
short=${tool_name##*__}
for prefix in $FENCE_READ_PREFIXES; do
case "$short" in "$prefix"*) exit 0 ;; esac
done
checks="tool"
;;
*) exit 0 ;;
esac
base="${url%/}/api/plugin/write-scope?"
[ -n "$session_scope" ] && base="${base}${session_scope}&"
[ -n "$entered" ] && base="${base}fallback_project_id=${entered}&"
fence_unreached() {
local marker="$state_dir/${safe_sid}.fence.unreached" now last
mkdir -p "$state_dir" 2>/dev/null || true
now=$(date +%s 2>/dev/null) || now=0
if [ -f "$marker" ]; then
last=$(cat "$marker" 2>/dev/null) || last=0
case "$last" in ''|*[!0-9]*) last=0 ;; esac
[ $((now - last)) -lt 600 ] && return 0
fi
printf '%s' "$now" > "$marker" 2>/dev/null || true
grimoire_json_out "PreToolUse" "> Grimoire did not answer the project fence check, so this act went ahead without being checked against the session's project. If it changes another project's files or records, stop and file an issue there instead. Said once per outage."
}
while IFS= read -r check; do
[ -n "$check" ] || continue
if [ "$check" = "tool" ]; then
input=$(fence_tool_input | grimoire_urlenc)
q="tool=$(printf '%s' "$short" | grimoire_urlenc)&input=${input}"
else
scope=${check%%$'\t'*}
act=${check#*$'\t'}
q="target_${scope}&act=$(printf '%s' "$act" | grimoire_urlenc)"
fi
resp=$(curl -fsS --max-time 4 -H "Authorization: Bearer ${token}" "${base}${q}" 2>/dev/null) || {
fence_unreached
exit 0
}
rm -f "$state_dir/${safe_sid}.fence.unreached" 2>/dev/null || true
flat=$(printf '%s' "$resp" | grimoire_json_flat)
if [ "$(grimoire_json_pick "$flat" '.allowed')" = "false" ]; then
reason=$(grimoire_json_pick "$flat" '.reason')
esc=$(printf '%s' "$reason" | grimoire_json_escape) || exit 0
printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"%s"}}\n' "$esc"
exit 0
fi
done <<EOF
$checks
EOF
exit 0
+29 -12
View File
@@ -72,20 +72,37 @@ printf '%s\n' "$rule_id" | grimoire_rules_append "$state_dir/${safe_sid}.opened.
# ── What came just before the open ───────────────────────────────────────
#
# grimoire_moment.sh writes every call to `grimoire-moment/<sid>.acts`. The ones
# from the last three minutes go to the server with this rule's id: a rule
# opened just after a moment fired is evidence it belongs on that moment, and
# once that repeats across sessions the server answers with one line asking
# the reader to offer the operator the mount. Nothing is mounted by this.
# grimoire_moment.sh writes every call to `grimoire-moment/<sid>.acts`. The
# last three, from the last ninety seconds, go to the server with this rule's
# id: a rule the agent went and opened right after a moment fired is evidence
# it belongs on that moment, and once that repeats across sessions the server
# answers with one line putting the question to the reader. Nothing is
# mounted by this.
#
# EVERY OPEN IS REPORTED: the server stamps it on this session's latest
# delivery of the rule, which is how an open rate per delivery is measured.
#
# The acts go with it only when the rule was NOT just named by a hook. A
# ranked arm or a moment line put a named rule in front of the reader, and
# that explains the open; the moment beside it did not, so counting it would
# propose mounts on whatever moment happened to fire while search was
# surfacing the rule. The window is short for the same reason: a few minutes
# of agent work reaches many moments.
command -v curl >/dev/null 2>&1 || exit 0
grimoire_config || exit 0
acts_file="${TMPDIR:-/tmp}/grimoire-moment/${safe_sid}.acts"
[ -f "$acts_file" ] || exit 0
now=$(date +%s 2>/dev/null) || exit 0
acts=$(awk -F '\t' -v since=$((now - 180)) \
'$1 + 0 >= since { sub(/^[^\t]*\t/, ""); print }' "$acts_file" 2>/dev/null \
| tail -n 30 | paste -sd ',' - 2>/dev/null)
[ -n "$acts" ] || exit 0
acts=""
case ",$(grimoire_rules_live "$state_dir/${safe_sid}.rules.ids")," in
*",${rule_id},"*) ;;
*)
acts_file="${TMPDIR:-/tmp}/grimoire-moment/${safe_sid}.acts"
now=$(date +%s 2>/dev/null) || now=0
if [ -f "$acts_file" ] && [ "$now" -gt 0 ]; then
acts=$(awk -F '\t' -v since=$((now - 90)) \
'$1 + 0 >= since { sub(/^[^\t]*\t/, ""); print }' "$acts_file" 2>/dev/null \
| tail -n 3 | paste -sd ',' - 2>/dev/null)
fi
;;
esac
sid_esc=$(printf '%s' "$session_id" | grimoire_json_escape) || exit 0
event_cwd=$(grimoire_json_pick "$event_flat" '.cwd')
+6 -4
View File
@@ -31,11 +31,13 @@ event_flat=$(printf '%s' "$event" | grimoire_json_flat)
session_id=$(grimoire_json_pick "$event_flat" '.session_id')
[ -n "$session_id" ] || exit 0
# The moment arm's per-session files (its tool cache and the acts ledger)
# describe a session that is over, on any exit — a clear
# included, since the next conversation is a new session id.
# The moment arm's per-session files (its tool cache and the acts ledger) and
# the fence's (the project the session entered, its outage marker) describe a
# session that is over, on any exit — a clear included, since the next
# conversation is a new session id.
safe_sid=$(printf '%s' "$session_id" | tr -c 'A-Za-z0-9._-' '_')
rm -f "${TMPDIR:-/tmp}/grimoire-moment/${safe_sid}".* 2>/dev/null || true
rm -f "${TMPDIR:-/tmp}/grimoire-moment/${safe_sid}".* \
"${TMPDIR:-/tmp}/grimoire-fence/${safe_sid}".* 2>/dev/null || true
reason=$(grimoire_json_pick "$event_flat" '.reason')
[ "$reason" = "clear" ] && exit 0
+2
View File
@@ -101,6 +101,8 @@ if [ -n "$session_id" ]; then
[ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
# What the session actually OPENED, as against what it was shown.
rule_exclude_q="${rule_exclude_q}$(grimoire_held_query "$state_dir/${safe_sid}.opened.ids")"
# Which session the rule lines go to, so each is recorded as a delivery.
rule_exclude_q="${rule_exclude_q}&session_id=${safe_sid}"
# The Systems whose rulings were shown in full — shared with the write-path
# hook, for the reason the rule file is.
rulingsfile="$state_dir/${safe_sid}.rulings.ids"
+18
View File
@@ -25,6 +25,15 @@
}
],
"PreToolUse": [
{
"matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash|mcp__.*grimoire.*",
"hooks": [
{
"type": "command",
"command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/grimoire_project_fence.sh\""
}
]
},
{
"matcher": "Write|Edit",
"hooks": [
@@ -89,6 +98,15 @@
"command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/grimoire_claim_session.sh\""
}
]
},
{
"matcher": "mcp__.*__enter_project",
"hooks": [
{
"type": "command",
"command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/grimoire_project_fence.sh\""
}
]
}
],
"PreCompact": [
+6 -5
View File
@@ -277,11 +277,12 @@ bound — confine the session to it:
- **Pass that `project_id` to every read** (`search`, `list_tasks`,
`list_notes`). An unscoped read bleeds every other project's work into your
context.
- **Only reference or offer work on the in-scope project.** Don't surface,
suggest, or start work on other projects unless the operator explicitly widens
scope.
- If something clearly belongs to a *different* project, say so and **ask before
switching** — never silently operate cross-project.
- **Only reference or offer work on the in-scope project**, unless the
operator explicitly widens scope; work that belongs elsewhere, say so and ask.
- **Cross-project, the one change to make is filing an issue**:
`create_task(project_id=<theirs>, kind="issue")` with how you found it and the
evidence. Reading there is fine; editing its files, committing or pushing in
its repo, or changing its records is the operator's call, and the plugin asks.
## Read these when the moment comes
+10 -6
View File
@@ -73,12 +73,16 @@ than a mount is fixed through its trigger instead.
## When a line proposes a mount
A rule that keeps being opened just after the same moment, across several
sessions, probably belongs on that moment. A line says so, naming the rule,
the moment and how often. It is a question for the operator, not a change you
make: offer it in one line, and record their answer with
`judge_rule_moments` — `confirm` mounts the rule, `reject` with their reason
stops the question being asked again.
A rule that sessions keep going and opening just after the same moment —
without a hook having shown it to them first — may belong on that moment. A
line says so, naming the rule, the moment, the action that reached it and how
often. That is co-occurrence, not a recommendation, so judge it before it
reaches the operator: read the rule's trigger against what the moment means
(`list_moments`). Offer it only when the rule governs that point in the work
whatever the work is about, as a question with your reason; a rule about a
subject (a library, a file, a style) is reached by meaning, and the line is
left alone. Record their answer with `judge_rule_moments` — `confirm` mounts
the rule, `reject` with their reason stops the question being asked again.
The same tool answers proposals from a pass over the rules
(`rules_to_mount`, `propose_rule_moments`, `rule_moment_proposals`): a pass
+17 -5
View File
@@ -395,6 +395,13 @@ SMOKE_EVENTS: dict[str, str] = {
{"session_id": "smoke", "cwd": ".", "hook_event_name": "SessionEnd",
"reason": "prompt_input_exit"}
),
# The project fence. A Grimoire write is the one act that always asks the
# server, so it is what reaches the network in the unreachable case: there
# the act goes ahead and the hook says once that it couldn't check.
"grimoire_project_fence.sh": json.dumps(
{"session_id": "smoke", "cwd": ".", "hook_event_name": "PreToolUse",
"tool_name": "mcp__grimoire__update_task", "tool_input": {"task_id": 1}}
),
# The shared library is sourced, never run; executed bare it defines
# functions and exits — silent by construction.
"grimoire_defs.sh": "",
@@ -415,9 +422,14 @@ STATIC_EMITTERS = {
# would look like a leak; it is the opposite.
"grimoire_precompact_preserve.sh": "preservation instructions present",
}
# The hooks that say so when a configured instance does not answer.
OUTAGE_SPEAKERS = {"grimoire_prior_art.sh", "grimoire_after_write.sh"}
OUTAGE_LINE = "> Grimoire did not answer the prior-art check"
# The hooks that say so when a configured instance does not answer, each with
# the line it says it in.
_PRIOR_ART_OUTAGE = "> Grimoire did not answer the prior-art check"
OUTAGE_LINES = {
"grimoire_prior_art.sh": _PRIOR_ART_OUTAGE,
"grimoire_after_write.sh": _PRIOR_ART_OUTAGE,
"grimoire_project_fence.sh": "> Grimoire did not answer the project fence check",
}
def _run_hook(script: Path, event: str, env_extra: dict[str, str]) -> subprocess.CompletedProcess:
@@ -464,13 +476,13 @@ def check_fail_open() -> None:
f"output must survive having no credentials ({what})")
else:
ok(f"{rel} [{label}]: exit 0, {what}")
elif out and label == "unreachable" and script.name in OUTAGE_SPEAKERS:
elif out and label == "unreachable" and script.name in OUTAGE_LINES:
# The only thing allowed here is the outage line itself.
try:
ctx = json.loads(out)["hookSpecificOutput"]["additionalContext"]
except (ValueError, KeyError, TypeError):
ctx = ""
if ctx.startswith(OUTAGE_LINE):
if ctx.startswith(OUTAGE_LINES[script.name]):
ok(f"{rel} [{label}]: exit 0, says the instance did not answer")
else:
fail(f"{rel} [{label}]: emitted output with no working instance "
+24 -10
View File
@@ -6,7 +6,8 @@ from pathlib import Path
from quart import Quart, g, jsonify, make_response, request, send_from_directory
from grimoire.config import PLACEHOLDER_SECRET_KEYS, SECRET_KEY_FILENAME, Config
from grimoire.config import SECRET_KEY_FILENAME, Config
from grimoire.proxy import PerRequestSecureSession, apply_https_headers
from grimoire.routes.admin import admin_bp
from grimoire.routes.api import api
from grimoire.routes.auth import auth_bp
@@ -61,13 +62,13 @@ def create_app() -> Quart:
app.secret_key = Config.SECRET_KEY
app.config["SESSION_COOKIE_HTTPONLY"] = True
app.config["SESSION_COOKIE_SAMESITE"] = "Lax"
app.config["SESSION_COOKIE_SECURE"] = Config.SECURE_COOKIES
# Secure is decided per request, from the trusted proxy's X-Forwarded-Proto.
app.session_interface = PerRequestSecureSession()
if Config.SECRET_KEY in PLACEHOLDER_SECRET_KEYS:
if os.environ.get("SECURE_COOKIES"):
logger.warning(
"SECRET_KEY is set to a public placeholder, so session cookies are insecure. "
"Remove it to let the instance keep its own key in %s, or set a real one.",
Config.DATA_DIR,
"SECURE_COOKIES is not used: the session cookie is Secure on every request "
"the trusted proxy reports as HTTPS. Remove it from the environment."
)
if Config.SECRET_KEY_SOURCE == "ephemeral":
logger.warning(
@@ -82,11 +83,12 @@ def create_app() -> Quart:
Config.DATA_DIR, SECRET_KEY_FILENAME,
)
if not Config.TRUST_PROXY_HEADERS:
if os.environ.get("TRUST_PROXY_HEADERS") and not os.environ.get("TRUSTED_PROXY_HOPS"):
logger.warning(
"TRUST_PROXY_HEADERS is not set. If this instance is behind a reverse proxy "
"(nginx, Caddy, Traefik) set TRUST_PROXY_HEADERS=true so rate limiting uses "
"real client IPs rather than the proxy IP."
"TRUST_PROXY_HEADERS is not used (the starting proxy hop count is %d). "
"Remove it; set the count in Settings → Config, or TRUSTED_PROXY_HOPS "
"to change the starting value.",
Config.TRUSTED_PROXY_HOPS,
)
app.register_blueprint(admin_bp)
@@ -159,6 +161,7 @@ def create_app() -> Quart:
except Exception:
logger.debug("Failed to log usage", exc_info=True)
apply_https_headers(response)
response.headers.setdefault("X-Content-Type-Options", "nosniff")
response.headers.setdefault("X-Frame-Options", "DENY")
response.headers.setdefault("Referrer-Policy", "strict-origin-when-cross-origin")
@@ -195,9 +198,20 @@ def create_app() -> Quart:
from grimoire.services.logging import start_log_retention_loop
from grimoire.services.notifications import start_notification_loop
from grimoire.services.rule_deliveries import start_prune_loop as start_rule_delivery_prune
start_log_retention_loop()
start_notification_loop()
start_auth_token_retention_loop()
start_rule_delivery_prune()
# The proxy hop count saved in Settings decides every request's client
# address, so it is loaded before serving, under a deadline (a failed
# or slow read leaves the environment's count in force), and re-read
# on an interval so a save in another worker reaches this one.
from grimoire.services import proxy_settings
await proxy_settings.load_at_startup()
proxy_settings.start_refresh_loop()
# Write down any shipped default that moved in this release.
#
+34 -6
View File
@@ -85,6 +85,21 @@ def _secret_key() -> tuple[str, str]:
return secrets.token_hex(32), "ephemeral"
def _trusted_proxy_hops() -> int:
"""TRUSTED_PROXY_HOPS, default 1. The older TRUST_PROXY_HEADERS switch is
still read when the hop count is unset: false means 0 hops. A value that
is not a whole number reads as -1, which validate() refuses."""
raw = os.environ.get("TRUSTED_PROXY_HOPS", "").strip()
if raw:
try:
return int(raw)
except ValueError:
return -1
if os.environ.get("TRUST_PROXY_HEADERS", "").strip().lower() in ("0", "false", "no"):
return 0
return 1
class Config:
DATABASE_URL: str = _read_secret(
"DATABASE_URL",
@@ -95,7 +110,6 @@ class Config:
# shipped compose file, beside the model cache and diagnostics.
DATA_DIR: str = os.environ.get("DATA_DIR", "/data")
SECRET_KEY, SECRET_KEY_SOURCE = _secret_key()
SECURE_COOKIES: bool = os.environ.get("SECURE_COOKIES", "").lower() in ("1", "true", "yes")
LOG_LEVEL: str = os.environ.get("LOG_LEVEL", "INFO")
LOG_RETENTION_DAYS: int = int(os.environ.get("LOG_RETENTION_DAYS", "90"))
@@ -108,7 +122,16 @@ class Config:
SMTP_FROM_NAME: str = os.environ.get("SMTP_FROM_NAME", "Fabled Grimoire")
SMTP_USE_TLS: bool = os.environ.get("SMTP_USE_TLS", "true").lower() in ("1", "true", "yes")
BASE_URL: str = os.environ.get("BASE_URL", "http://localhost:5000").rstrip("/")
TRUST_PROXY_HEADERS: bool = os.environ.get("TRUST_PROXY_HEADERS", "").lower() in ("1", "true", "yes")
# How many reverse proxies stand in front of the app; the client address
# and scheme are read that many entries in from the right of the
# forwarding headers (grimoire/proxy.py). 0 trusts no proxy. This is the
# install's starting value: a count saved in Settings → Config wins over
# it (services/proxy_settings.py).
TRUSTED_PROXY_HOPS: int = _trusted_proxy_hops()
TRUSTED_PROXY_HOPS_FROM_ENV: bool = bool(
os.environ.get("TRUSTED_PROXY_HOPS", "").strip()
or os.environ.get("TRUST_PROXY_HEADERS", "").strip()
)
# Git URL of the repo that ships this Grimoire plugin. There is one correct
# value per deployment (the repo serving the plugin), so it's a config
@@ -163,11 +186,16 @@ class Config:
errors.append(f"SMTP_PORT={cls.SMTP_PORT} must be between 1 and 65535")
if cls.oidc_enabled() and not cls.BASE_URL.startswith(("http://", "https://")):
errors.append(f"BASE_URL='{cls.BASE_URL}' must start with http:// or https:// when OIDC is enabled")
if cls.SECRET_KEY == "dev-secret-change-me" and cls.SECURE_COOKIES:
if cls.TRUSTED_PROXY_HOPS < 0:
errors.append(
"SECRET_KEY is set to the public placeholder 'dev-secret-change-me' but "
"SECURE_COOKIES=true indicates a production deployment. Remove SECRET_KEY "
"to let the instance keep its own key in DATA_DIR, or set a real one."
f"TRUSTED_PROXY_HOPS={os.environ.get('TRUSTED_PROXY_HOPS')!r} must be a whole "
"number of proxies, 0 or more"
)
if cls.SECRET_KEY in PLACEHOLDER_SECRET_KEYS:
errors.append(
f"SECRET_KEY is set to the public placeholder {cls.SECRET_KEY!r}, so anyone "
"could forge a session. Remove SECRET_KEY to let the instance keep its own "
"key in DATA_DIR, or set a real one."
)
if errors:
raise ValueError("Configuration errors:\n" + "\n".join(f" - {e}" for e in errors))
+4 -1
View File
@@ -144,7 +144,10 @@ async def create_note(
Args:
title: Note title (required).
body: Markdown content. Supports [[wikilinks]] to other notes by title.
body: Markdown content. Cite another record as `#N` (note, task,
lesson, snippet), `milestone N` or `rule N`; the web UI links each
one, titled on hover, and lists it in the target's backlinks.
`[[Title]]` links a note by its title.
tags: List of plain-string tags without # prefix, e.g. ["python", "ideas"].
project_id: Associate with a project (use 0 for no project / orphan note).
system_ids: Ids of the project's Systems to associate this note with
+46 -1
View File
@@ -342,6 +342,7 @@ async def create_rule(
arose_from_id: int = 0, verify_with: str = "", expires_when: str = "",
system_ids: list[int] | None = None,
moments: list[str] | None = None, force: bool = False,
enforcement: str = "inform", salience: str = "normal",
) -> dict:
"""Create a new rule in a rulebook (a SHARED rule — keep it general).
@@ -530,6 +531,14 @@ async def create_rule(
constraint expires when the ground under it moves, not on a
schedule. Pairs with verify_with; both empty is the normal case.
order_index: Display order within the topic (default 0).
enforcement: What this rule does when it arrives. `inform` (the
default) puts a line beside the work. `hold` makes the reply or
act it governs wait for one read of it — for a rule whose miss
costs a rewrite. `enforce` checks the act itself — for a hard
boundary. Declare hold or enforce on purpose; most rules inform.
salience: `high`, `normal` (the default) or `low` — how this record
ranks against others of the same enforcement when a moment has
more to say than fits.
force: Bypass the near-duplicate gate. By default, a title-identical rule
already in this topic BLOCKS creation and returns its id so you update
it instead. Set true only for a genuinely distinct rule. A rule or
@@ -553,6 +562,7 @@ async def create_rule(
arose_from_id=arose_from_id,
why=why, how_to_apply=how_to_apply, order_index=order_index,
verify_with=verify_with, expires_when=expires_when,
enforcement=enforcement, salience=salience,
)
data = await rulebooks_svc.rule_detail(uid, rule, system_ids, moments)
data.update(dedup_svc.overlap_response(overlaps, "rule"))
@@ -565,6 +575,7 @@ async def create_project_rule(
arose_from_id: int = 0, verify_with: str = "", expires_when: str = "",
system_ids: list[int] | None = None,
moments: list[str] | None = None, force: bool = False,
enforcement: str = "inform", salience: str = "normal",
) -> dict:
"""Create a rule scoped to a single project (no rulebook needed).
@@ -640,6 +651,14 @@ async def create_project_rule(
expires_when: The state under which the rule stops being true — see
create_rule. A state, not a date.
order_index: Display order within the project's rule list (default 0).
enforcement: What this rule does when it arrives. `inform` (the
default) puts a line beside the work. `hold` makes the reply or
act it governs wait for one read of it — for a rule whose miss
costs a rewrite. `enforce` checks the act itself — for a hard
boundary. Declare hold or enforce on purpose; most rules inform.
salience: `high`, `normal` (the default) or `low` — how this record
ranks against others of the same enforcement when a moment has
more to say than fits.
force: Bypass the near-duplicate gate. By default, a title-identical rule
already on this project BLOCKS creation and returns its id so you
update it instead. Set true only for a genuinely distinct rule. An
@@ -662,6 +681,7 @@ async def create_project_rule(
arose_from_id=arose_from_id,
why=why, how_to_apply=how_to_apply, order_index=order_index,
verify_with=verify_with, expires_when=expires_when,
enforcement=enforcement, salience=salience,
)
data = await rulebooks_svc.rule_detail(uid, rule, system_ids, moments)
data.update(dedup_svc.overlap_response(overlaps, "rule"))
@@ -675,6 +695,7 @@ async def update_rule(
moments: list[str] | None = None, arose_from_id: int = 0,
verify_with: str = "", expires_when: str = "", kind: str = "",
clear_fields: list[str] | None = None,
enforcement: str = "", salience: str = "",
) -> dict:
"""Update a rule. Empty strings / order_index=-1 leave fields unchanged.
@@ -735,6 +756,15 @@ async def update_rule(
expires_when: The state under which the rule stops being true. A
state, not a date. See create_rule.
clear_fields: Names of fields to empty, as above.
enforcement: What this rule does when it arrives. `inform` (the
default for a new rule) puts a line beside the work. `hold` makes the reply or
act it governs wait for one read of it — for a rule whose miss
costs a rewrite. `enforce` checks the act itself — for a hard
boundary. Declare hold or enforce on purpose; most rules inform.
salience: `high`, `normal` (the default) or `low` — how this record
ranks against others of the same enforcement when a moment has
more to say than fits.
Omit either to leave it unchanged.
"""
uid = current_user_id()
moments = moments_svc.require_moments(moments)
@@ -759,6 +789,10 @@ async def update_rule(
fields["expires_when"] = expires_when
if order_index >= 0:
fields["order_index"] = order_index
if enforcement:
fields["enforcement"] = enforcement
if salience:
fields["salience"] = salience
rule = await rulebooks_svc.update_rule(
rule_id, uid, clear=clear_fields or (), **fields,
)
@@ -786,7 +820,7 @@ async def create_preference(
arose_from_id: int, why: str = "", how_to_apply: str = "",
order_index: int = 0, system_ids: list[int] | None = None,
moments: list[str] | None = None,
force: bool = False,
force: bool = False, salience: str = "normal",
) -> dict:
"""Record how the operator wants work done. No approval loop — write it.
@@ -860,6 +894,9 @@ async def create_preference(
done rather than what it is about: a rule on when work counts as
finished belongs at work.finish and reply.report, where nothing
said resembles it. Replaces the set; [] clears it.
salience: `high`, `normal` (the default) or `low` — how this record
ranks against others of the same enforcement when a moment has
more to say than fits.
force: Bypass the near-duplicate gate. For a genuinely distinct
preference, not for one that is "mostly" different — a mostly
different preference is an update. A RULE that already answers
@@ -893,6 +930,7 @@ async def create_preference(
title=title, statement=statement, when_to_apply=when_to_apply,
kind="preference", arose_from_id=arose_from_id,
why=why, how_to_apply=how_to_apply, order_index=order_index,
salience=salience,
)
data = await rulebooks_svc.rule_detail(uid, rule, system_ids, moments)
data.update(dedup_svc.overlap_response(overlaps, "preference"))
@@ -905,6 +943,7 @@ async def update_preference(
how_to_apply: str = "", order_index: int = -1,
system_ids: list[int] | None = None,
moments: list[str] | None = None, clear_fields: list[str] | None = None,
salience: str = "",
) -> dict:
"""Bring a preference up to date. Doing this mid-work is expected.
@@ -959,6 +998,10 @@ async def update_preference(
moments: Replaces the moments this preference arrives at (see
create_preference); omit to leave them alone.
when_to_apply: The moment it applies, in session vocabulary. See above.
salience: `high`, `normal` (the default) or `low` — how this record
ranks against others of the same enforcement when a moment has
more to say than fits.
Omit to leave it unchanged.
"""
uid = current_user_id()
moments = moments_svc.require_moments(moments)
@@ -981,6 +1024,8 @@ async def update_preference(
fields["how_to_apply"] = how_to_apply
if order_index >= 0:
fields["order_index"] = order_index
if salience:
fields["salience"] = salience
rule = await rulebooks_svc.update_rule(
rule_id, uid, clear=clear_fields or (), **fields,
)
+6 -1
View File
@@ -271,7 +271,9 @@ async def create_task(
Args:
title: Task title (required).
body: Markdown description / notes for the task.
body: Markdown description / notes for the task. Cite another record
as `#N` (note, task, lesson, snippet), `milestone N` or `rule N`;
the web UI links each one and lists it in the target's backlinks.
status: Initial status — one of: todo (default), in_progress, done, cancelled.
priority: One of: low, medium, high, or 'none'. Omit (empty string) to leave unset.
project_id: Associate with a project (0 = no project).
@@ -482,6 +484,9 @@ async def add_task_log(task_id: int, content: str) -> dict:
cannot get from the body or the diff is what you tried, what you ruled
out, and where it actually stands.
Records named as `#N`, `milestone N` or `rule N` are links in the web UI,
and a `#N` here lists this task in that record's backlinks.
A log on an open task also marks it as being worked by this session — its
`claim`. That is what brings the task and its newest
entries back to you after a compaction; it lapses by itself once the
+2
View File
@@ -60,6 +60,7 @@ from grimoire.models.retrieval_log import RetrievalLog # noqa: E402, F401
from grimoire.models.retrieval_tuning import RetrievalTuningEvent # noqa: E402, F401
from grimoire.models.note_usage import NoteUsageEvent # noqa: E402, F401
from grimoire.models.rule_usage import RuleUsageEvent # noqa: E402, F401
from grimoire.models.rule_delivery import RuleDelivery # noqa: E402, F401
from grimoire.models.system_usage import SystemUsageEvent # noqa: E402, F401
from grimoire.models.retrieval_judgment import RetrievalJudgment # noqa: E402, F401
from grimoire.models.moment_mapping import MomentMapping # noqa: E402, F401
@@ -94,3 +95,4 @@ from grimoire.models.family import ( # noqa: E402, F401
FamilyAdoption, FamilyDecision, FamilyIdea, FamilyIdeaPlatform,
FamilyIdeaReference, Platform, ProjectPlatform,
)
from grimoire.models.instance import InstanceIdentity # noqa: E402, F401
+26
View File
@@ -0,0 +1,26 @@
from datetime import datetime
from sqlalchemy import CheckConstraint, DateTime, Integer, Text, func
from sqlalchemy.orm import Mapped, mapped_column
from grimoire.models import Base
class InstanceIdentity(Base):
"""The one row naming this database's id lineage.
Two stores with the same instance id number their rows the same way: one
is the other, or a restore of it made with the original ids kept. That is
what lets a backup roll a live instance back by id, and what refuses a
backup whose ids would land on unrelated rows. Made by the migration, so
an instance has it before anyone registers.
"""
__tablename__ = "instance_identity"
__table_args__ = (CheckConstraint("id = 1", name="ck_instance_identity_single_row"),)
id: Mapped[int] = mapped_column(Integer, primary_key=True, default=1)
instance_id: Mapped[str] = mapped_column(Text, nullable=False)
created_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True), nullable=False, server_default=func.now()
)
+69
View File
@@ -0,0 +1,69 @@
from datetime import datetime
from sqlalchemy import BigInteger, DateTime, Index, Text, func
from sqlalchemy.orm import Mapped, mapped_column
from grimoire.models import Base
from grimoire.models.base import iso
FULL = "full"
REPEAT = "repeat"
FORMS = (FULL, REPEAT)
class RuleDelivery(Base):
"""One rule line put in front of one session, and whether it was opened after.
WHAT IT ANSWERS that `rule_usage_events` cannot. A surfaced event and a
pulled event are counted separately, so "was THIS delivery opened" has no
answer there: a rule opened once in a session reads as pulled whether it
was delivered once or twenty times. Here each delivery is a row, and the
open is stamped on the delivery it followed — so the open rate per rule,
per moment and per arm is a count of rows, and the ordering function reads
it as the rule's history at that moment.
`at` is where the rule was delivered: the moment it was mounted on
(`work.finish`) or the arm that found it (`pre_tool_rule`). `form` is
whether the line carried the rule's trigger (`full`) or only cited it
(`repeat`). Repeats are recorded too: they are deliveries a session can
open, and the case for retiring a rule rests on how rarely they are.
FK-free on `rule_id` and `user_id`, like the other telemetry tables: the
evidence that a rule was delivered forty times and opened never outlives
the rule, because it is the case for having deleted it.
"""
__tablename__ = "rule_deliveries"
id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
user_id: Mapped[int] = mapped_column(BigInteger, nullable=False)
session_id: Mapped[str] = mapped_column(Text, nullable=False)
rule_id: Mapped[int] = mapped_column(BigInteger, nullable=False)
source: Mapped[str] = mapped_column(Text, nullable=False)
at: Mapped[str] = mapped_column(Text, nullable=False)
form: Mapped[str] = mapped_column(Text, nullable=False)
delivered_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True), nullable=False, server_default=func.now(),
)
opened_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
__table_args__ = (
# Stamping an open: this session's latest delivery of this rule.
Index("ix_rule_deliveries_session_rule", "user_id", "session_id", "rule_id", "delivered_at"),
# History: a batch of rules at one moment.
Index("ix_rule_deliveries_rule_at", "rule_id", "at"),
Index("ix_rule_deliveries_delivered_at", "delivered_at"),
)
def to_dict(self) -> dict:
return {
"id": self.id,
"user_id": self.user_id,
"session_id": self.session_id,
"rule_id": self.rule_id,
"source": self.source,
"at": self.at,
"form": self.form,
"delivered_at": iso(self.delivered_at),
"opened_at": iso(self.opened_at),
}
+11
View File
@@ -116,6 +116,15 @@ class Rule(Base, TimestampMixin, SoftDeleteMixin):
# Defaults to `rule` so nothing changes force on upgrade.
# CHECK ck_rules_kind (migration 0098).
kind: Mapped[str] = mapped_column(Text, default="rule", server_default="rule")
# WHAT THE RULE DOES WHEN IT ARRIVES, declared by its author rather than
# guessed from a score. `enforce`: the act it governs is checked. `hold`:
# the reply or act waits for one read of it. `inform`: a line beside the
# work, and never a stop. A preference is always `inform` (CHECK
# ck_rules_preference_informs). CHECK ck_rules_enforcement (migration 0128).
enforcement: Mapped[str] = mapped_column(Text, default="inform", server_default="inform")
# How this rule ranks among rules of the same enforcement when a moment has more
# to say than fits: `high`, `normal`, `low`. CHECK ck_rules_salience.
salience: Mapped[str] = mapped_column(Text, default="normal", server_default="normal")
why: Mapped[str | None] = mapped_column(Text, nullable=True)
how_to_apply: Mapped[str | None] = mapped_column(Text, nullable=True)
# The three fields that tell a CONSTRAINT apart from a NORM (milestone
@@ -161,6 +170,8 @@ class Rule(Base, TimestampMixin, SoftDeleteMixin):
# codebase keeps re-encountering. Twenty bytes buys an answer that
# cannot be misread.
"kind": self.kind or "rule",
"enforcement": self.enforcement or "inform",
"salience": self.salience or "normal",
"why": self.why or "",
"how_to_apply": self.how_to_apply or "",
"verify_with": self.verify_with or "",
+164
View File
@@ -0,0 +1,164 @@
"""What the trusted reverse proxy says about a request: who sent it, and
whether it arrived over HTTPS.
Grimoire serves plain HTTP; TLS ends at the operator's proxy. The proxy
reports the client's address in X-Forwarded-For and the scheme in
X-Forwarded-Proto, and each proxy on the road APPENDS its entry, so only the
right-hand end of either header was written by a proxy we trust. Anything to
the left of that is whatever the client chose to send.
The hop count says how many proxies stand in front of the app. An admin sets
it in Settings → Config; until they do, it is `TRUSTED_PROXY_HOPS` from the
environment (default 1). The entry read is that many in from the right. Zero
trusts no proxy: the headers are ignored and the socket peer is the client.
Never read X-Forwarded-For or X-Forwarded-Proto anywhere else. The client
address keys the rate limits and the audit log, and the scheme decides the
session cookie's Secure flag and HSTS. A second reader is a second trust rule.
"""
from __future__ import annotations
from quart import has_request_context, request
from quart.sessions import SecureCookieSessionInterface
from grimoire.config import Config
# HSTS for a year, sent only on a request the trusted proxy says is HTTPS.
# No includeSubDomains or preload: the app does not own the operator's domain.
HSTS_VALUE = "max-age=31536000"
def trusted_entry(header: str, hops: int) -> str | None:
"""The entry `hops` in from the right of a forwarding header.
A header shorter than that is read at its leftmost entry, the one the
first proxy wrote. A road with fewer proxies than the count (a LAN road
beside a Cloudflare one) still reads right that way. None when no proxy
is trusted or there is no header. Pure, so the trust boundary is
testable without a request."""
if hops <= 0:
return None
entries = [part.strip() for part in header.split(",") if part.strip()]
if not entries:
return None
return entries[-min(hops, len(entries))]
# The count saved in Settings, or None when none is saved. Held here because
# every request reads it and the read is synchronous; services/proxy_settings
# loads it at startup, refreshes it on an interval in every worker, and sets it
# at once in the worker that saved a new one.
_saved_hops: int | None = None
def set_saved_hops(hops: int | None) -> None:
global _saved_hops
_saved_hops = hops
def saved_hops_in_force() -> int | None:
"""The count saved in Settings that this worker holds, or None."""
return _saved_hops
def trusted_hops() -> int:
"""The hop count in force: the one saved in Settings, else the env's."""
return Config.TRUSTED_PROXY_HOPS if _saved_hops is None else _saved_hops
def _chain(name: str) -> str:
# Joined, because a header sent twice arrives as two values, and each
# proxy's append may land on either one.
return ",".join(request.headers.getlist(name))
def _forwarded(name: str) -> str | None:
return trusted_entry(_chain(name), trusted_hops())
def client_ip() -> str:
"""The caller's address, as the trusted proxy saw it."""
if not has_request_context():
return ""
return (_forwarded("X-Forwarded-For") or request.remote_addr or "")[:64]
def is_https() -> bool:
"""Whether this request arrived over HTTPS, by the trusted proxy's word."""
if not has_request_context():
return False
if request.scheme == "https":
return True
return (_forwarded("X-Forwarded-Proto") or "").lower() == "https"
class PerRequestSecureSession(SecureCookieSessionInterface):
"""The session cookie is Secure exactly when the request is HTTPS, so a
public deployment gets it and a plain-HTTP one keeps working."""
def get_cookie_secure(self, app) -> bool:
return is_https()
def apply_https_headers(response) -> None:
"""HSTS on an HTTPS request, and only then. The app never redirects to
HTTPS; plain HTTP is a supported way to run it."""
if is_https():
response.headers.setdefault("Strict-Transport-Security", HSTS_VALUE)
# Cloudflare writes the visitor's address here on every request it proxies.
# Read only to SUGGEST a hop count in the readout, never to decide one: a
# client that reaches the app without Cloudflare can send it too.
CLOUDFLARE_CLIENT_HEADER = "CF-Connecting-IP"
CLOUDFLARE_MARKERS = (CLOUDFLARE_CLIENT_HEADER, "CF-Ray")
READOUT_HOPS = range(0, 4)
MAX_HOPS = 5
def readout(peer: str, forwarded_for: str, forwarded_proto: str,
cloudflare_client: str | None, scheme: str = "http") -> dict:
"""What each hop count would make of one request, so an admin can pick
the count that shows their own address. Pure: the request's parts come in
as arguments.
`suggested` is the smallest count that reads the address Cloudflare
reports, when the request came through Cloudflare; otherwise None, since
only the admin knows which address is theirs.
"""
def read(hops: int) -> dict:
address = trusted_entry(forwarded_for, hops) or peer
proto = trusted_entry(forwarded_proto, hops)
https = scheme == "https" or (proto or "").lower() == "https"
return {"hops": hops, "client": address, "https": https}
suggested = None
if cloudflare_client:
suggested = next(
(h for h in range(1, MAX_HOPS + 1)
if trusted_entry(forwarded_for, h) == cloudflare_client),
None,
)
return {
"peer": peer,
"forwarded_for": [p.strip() for p in forwarded_for.split(",") if p.strip()],
"forwarded_proto": [p.strip() for p in forwarded_proto.split(",") if p.strip()],
"cloudflare": cloudflare_client is not None,
"cloudflare_client": cloudflare_client,
"rows": [read(h) for h in READOUT_HOPS],
"suggested": suggested,
}
def request_readout() -> dict:
"""`readout` for the current request."""
cloudflare = request.headers.get(CLOUDFLARE_CLIENT_HEADER)
if cloudflare is None and request.headers.get("CF-Ray"):
cloudflare = ""
return readout(
request.remote_addr or "",
_chain("X-Forwarded-For"),
_chain("X-Forwarded-Proto"),
cloudflare.strip() if cloudflare is not None else None,
request.scheme,
)
+11 -3
View File
@@ -2,15 +2,23 @@
IMPORTANT — deployment note:
Rate limit counters are stored in memory and are lost on process restart.
When deployed behind a reverse proxy (nginx, Caddy, Traefik) you MUST set
TRUST_PROXY_HEADERS=true so that the real client IP is used as the bucket key
rather than the proxy's IP (which would cause all users to share one bucket).
The bucket key is the client address from grimoire/proxy.py, read by the
proxy hop count (Settings → Config). A count that is too low keys every
caller on the proxy's address, so they all share one bucket.
"""
import asyncio
import time
from collections import defaultdict
# Said beside every "too many attempts" reply, because the one case a person
# can't diagnose on their own is everybody being blocked at once: the proxy
# count is too low, so every visitor reads as the proxy and shares one bucket.
SHARED_ADDRESS_HINT = (
"If everyone is being blocked, an admin should check the reverse proxy count "
"in Settings → Config: every visitor may be reading as the proxy's address."
)
_buckets: dict[str, list[float]] = defaultdict(list)
_lock = asyncio.Lock()
+80 -30
View File
@@ -1,20 +1,26 @@
"""Restore a Grimoire backup into an empty instance, from the command line.
"""Restore a Grimoire backup from the command line.
python -m grimoire.restore /backups/grimoire-20261015T020000Z.tar
python -m grimoire.restore /backups/grimoire-20261015T020000Z.tar --yes
This is how a fresh instance is brought back after losing the old one. Run it
inside the Grimoire container, which already has the database settings and has
already migrated the schema on start. It reads either the scheduled backup's
tar (services/backup_file.py) or the JSON the admin download produces.
Run it inside the Grimoire container, which already has the database settings
and has migrated the schema on start. It reads the scheduled backup's tar
(services/backup_file.py) or the JSON the admin download produces, and nothing
limits the file's size.
It refuses a database that already holds an account. A restore re-creates
every user, project and record from the file with new ids; into a live
instance it would add a second copy of everything rather than replace it.
(Settings → Backup & Restore still offers the upload for that case, on
purpose and with its own warning.)
It does what Settings → Restore does (services/backup.py replace_from_backup):
- **A new, empty instance** takes the backup as it is.
- **A live instance** rolls back to a backup of its own: everything goes back
to the moment the backup was taken, for every user.
- A backup from another instance, or one made before backups recorded their
instance, only goes into an empty instance.
Unlike the upload, nothing limits the file's size here, so this is also the
way in for a backup too big for the web upload.
Without --yes it only says what would change. With --yes it first saves the
current state as a backup (to the backup destination, or DATA_DIR/pre-restore),
then restores. Everyone is signed out afterwards.
A backup in the oldest (v1) format is copied into an empty instance with new
ids instead, as before.
Afterwards, restart Grimoire: search indexes are not part of a backup and are
rebuilt from the restored records at startup.
@@ -48,9 +54,39 @@ async def _account_count() -> int:
return (await session.execute(select(func.count()).select_from(User))).scalar_one()
async def run(path: Path) -> int:
from grimoire.models import engine
async def _restore_v1(payload: dict) -> int:
from grimoire.services.backup import restore_full_backup
accounts = await _account_count()
if accounts:
print(
f"This database already holds {accounts} account(s). A backup in the oldest "
"format is copied in with new ids rather than replacing anything, so it only "
"goes into an empty instance. Start Grimoire on an empty database and run "
"this again.",
file=sys.stderr,
)
return 3
stats = await restore_full_backup(payload)
print(json.dumps({"restored": stats}, indent=2, default=str))
return 0
def _print_preview(preview: dict) -> None:
taken = preview.get("exported_at") or "an unknown date"
if preview["mode"] == "rollback":
print(f"This rolls the whole instance back to {taken}, for every user. Anything "
"made since is removed, edits since are undone, records deleted since come back.")
else:
print(f"This instance has no records yet; it takes the backup from {taken} as it is.")
for count in preview["counts"]:
print(f" {count['kind']:<24} now {count['now']:>7} after {count['after']:>7}")
async def run(path: Path, *, yes: bool = False) -> int:
from grimoire.models import engine
from grimoire.services import backup_job
from grimoire.services.backup import RestoreRefused, replace_preview
from grimoire.services.backup_file import ArchiveError
try:
@@ -63,20 +99,29 @@ async def run(path: Path) -> int:
print(f"{path} isn't a backup this Grimoire can read: {exc}", file=sys.stderr)
return 2
accounts = await _account_count()
if accounts:
print(
f"This database already holds {accounts} account(s). A restore adds a second "
"copy of everything rather than replacing it, so it only runs into an empty "
"instance. Start Grimoire on an empty database and run this again.",
file=sys.stderr,
)
return 3
stats = await restore_full_backup(payload)
print(json.dumps({"restored": stats}, indent=2, default=str))
print("Restored. Restart Grimoire so the search indexes are rebuilt.", file=sys.stderr)
return 0
if (payload.get("version") or 1) < 2:
code = await _restore_v1(payload)
else:
try:
_print_preview(await replace_preview(payload))
if not yes:
print("Nothing was changed. Run it again with --yes to restore.",
file=sys.stderr)
return 4
result = await backup_job.rollback_to_backup(payload)
except RestoreRefused as exc:
print(str(exc), file=sys.stderr)
return 3
safety = result["safety_backup"]
print(json.dumps({"restored": result["restored"], "safety_backup": safety},
indent=2, default=str))
print(f"The state it replaced is saved as {safety['file']} in {safety['where']}.",
file=sys.stderr)
code = 0
if code == 0:
print("Restored. Restart Grimoire so the search indexes are rebuilt; "
"everyone signs in again.", file=sys.stderr)
return code
finally:
await engine.dispose()
@@ -84,11 +129,16 @@ async def run(path: Path) -> int:
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(
prog="python -m grimoire.restore",
description="Restore a Grimoire backup (.tar or .json) into an empty instance.",
description=(
"Restore a Grimoire backup (.tar or .json): into an empty instance, or "
"roll this instance back to a backup of its own."
),
)
parser.add_argument("file", type=Path, help="the backup file")
parser.add_argument("--yes", action="store_true",
help="restore; without it, only say what would change")
args = parser.parse_args(argv)
return asyncio.run(run(args.file))
return asyncio.run(run(args.file, yes=args.yes))
if __name__ == "__main__":
+155 -35
View File
@@ -3,7 +3,11 @@ import json
from quart import Blueprint, Response, g, jsonify, request
from grimoire import proxy
from grimoire.auth import admin_required, login_required, get_current_user_id
from grimoire.config import Config
from grimoire.proxy import client_ip
from grimoire.services import proxy_settings
from grimoire.services.auth import (
create_invitation,
delete_user,
@@ -16,7 +20,6 @@ from grimoire.services.auth import (
from grimoire.services.backup import (
export_full_backup,
export_user_backup,
restore_full_backup,
)
from grimoire.services.email import SMTP_SETTING_KEYS, get_base_url, get_smtp_config, is_smtp_configured, send_test_email
from grimoire.services.logging import get_logs, get_log_stats, log_audit
@@ -46,7 +49,7 @@ async def backup():
else:
data = await export_user_backup(uid)
await log_audit("backup", user_id=uid, username=g.user.username, ip_address=request.remote_addr, details={"scope": scope})
await log_audit("backup", user_id=uid, username=g.user.username, ip_address=client_ip(), details={"scope": scope})
return Response(
json.dumps(data, indent=2, default=str),
content_type="application/json",
@@ -56,31 +59,111 @@ async def backup():
)
async def _restore_payload() -> tuple[dict | None, tuple | None]:
"""The backup a restore request names: `?source=<file>` at the backup
destination, or the uploaded file (the JSON download as
application/json, or the tar as the raw body; held to the request-size
limit, which is why the destination is the way in for a large one).
Returns (payload, None) or (None, an error response)."""
import io
import tempfile
from pathlib import Path
from grimoire.services import backup_destination as dest
from grimoire.services.backup_file import ArchiveError, read_archive
source = request.args.get("source")
try:
if source:
config = await dest.load_config()
secret, _ = await dest.load_secret()
with tempfile.TemporaryDirectory(prefix="grimoire-restore-") as staging:
path = await dest.open_backup(config, secret, source, Path(staging))
def load() -> dict:
with open(path, "rb") as f:
return read_archive(f)
data = await asyncio.to_thread(load)
elif request.mimetype == "application/json":
data = await request.get_json()
else:
data = read_archive(io.BytesIO(await request.get_data()))
except dest.DestinationError as exc:
return None, (jsonify({"error": str(exc)}), 400)
except ArchiveError as exc:
return None, (jsonify({"error": f"That file isn't a Grimoire backup: {exc}"}), 400)
if not isinstance(data, dict) or not data:
return None, (jsonify({"error": "No backup data provided"}), 400)
return data, None
@admin_bp.route("/restore/sources", methods=["GET"])
@admin_required
async def restore_sources():
"""The backups at the backup destination, newest first, to restore from
without uploading one."""
from grimoire.services import backup_destination as dest
config = await dest.load_config()
secret, _ = await dest.load_secret()
try:
backups = await asyncio.wait_for(dest.list_backups(config, secret), _BACKUP_CHECK_TIMEOUT)
except dest.DestinationError as exc:
return jsonify({"backups": [], "error": str(exc)})
except (TimeoutError, asyncio.TimeoutError):
return jsonify({"backups": [], "error": (
f"The destination didn't answer within {int(_BACKUP_CHECK_TIMEOUT)} seconds."
)})
return jsonify({"backups": [{"name": b.name, "size_bytes": b.size_bytes} for b in backups]})
@admin_bp.route("/restore/preview", methods=["POST"])
@admin_required
async def restore_preview():
"""What restoring this backup would do, changing nothing: fresh or
rollback, when it was taken, and the counts now and after. 409 with the
reason when it can't be restored here."""
from grimoire.services.backup import RestoreRefused, replace_preview
data, error = await _restore_payload()
if error:
return error
try:
return jsonify(await replace_preview(data))
except RestoreRefused as exc:
return jsonify({"error": str(exc)}), 409
@admin_bp.route("/restore", methods=["POST"])
@admin_required
async def restore():
"""Restore from an uploaded backup: the JSON download (application/json)
or the scheduled backup's tar (sent as the raw body). The upload is held
to the app's request-size limit; `python -m grimoire.restore` has none, and
is the way in for a bigger file or a fresh instance."""
if request.mimetype == "application/json":
data = await request.get_json()
else:
import io
"""Put the whole instance back to a full backup (services/backup.py
replace_from_backup), after backing up what it replaces. `?confirm=rollback`
is required: this removes everything made since the backup, for every
user. Every session ends, the caller's included; search is rebuilt in the
background."""
from grimoire.services import backup_job as job
from grimoire.services.backup import RestoreRefused
from grimoire.services.backup_file import ArchiveError, read_archive
try:
data = read_archive(io.BytesIO(await request.get_data()))
except ArchiveError as exc:
return jsonify({"error": f"That file isn't a Grimoire backup: {exc}"}), 400
if not data:
return jsonify({"error": "No backup data provided"}), 400
stats = await restore_full_backup(data)
if request.args.get("confirm") != "rollback":
return jsonify({"error": "Restoring replaces the whole instance; confirm it first."}), 400
data, error = await _restore_payload()
if error:
return error
try:
result = await job.rollback_to_backup(data)
except RestoreRefused as exc:
return jsonify({"error": str(exc)}), 409
except job.BackupBusy:
return jsonify({"error": "A backup is running. Restore once it has finished."}), 409
job.start_reindex_after_restore()
uid = get_current_user_id()
await log_audit("restore", user_id=uid, username=g.user.username, ip_address=request.remote_addr, details={"stats": stats})
return jsonify({"status": "ok", "stats": stats})
await log_audit(
"restore", user_id=uid, username=g.user.username, ip_address=client_ip(),
details={"mode": result["mode"], "exported_at": result.get("exported_at"),
"safety_backup": result["safety_backup"], "stats": result["restored"]},
)
return jsonify({"status": "ok", **result})
@admin_bp.route("/users", methods=["GET"])
@@ -100,7 +183,7 @@ async def remove_user(user_id: int):
deleted = await delete_user(user_id)
if not deleted:
return jsonify({"error": "User not found"}), 404
await log_audit("user_delete", user_id=current_uid, username=g.user.username, ip_address=request.remote_addr, details={"deleted_user_id": user_id})
await log_audit("user_delete", user_id=current_uid, username=g.user.username, ip_address=client_ip(), details={"deleted_user_id": user_id})
return jsonify({"status": "ok"})
@@ -121,7 +204,7 @@ async def toggle_registration():
uid = get_current_user_id()
await set_registration_open(uid, bool(open_val))
await log_audit("registration_toggle", user_id=uid, username=g.user.username, ip_address=request.remote_addr, details={"open": bool(open_val)})
await log_audit("registration_toggle", user_id=uid, username=g.user.username, ip_address=client_ip(), details={"open": bool(open_val)})
return jsonify({"status": "ok", "open": bool(open_val)})
@@ -151,7 +234,7 @@ async def update_smtp():
if settings_to_save:
await set_settings_batch(uid, settings_to_save)
await log_audit("smtp_config", user_id=uid, username=g.user.username, ip_address=request.remote_addr)
await log_audit("smtp_config", user_id=uid, username=g.user.username, ip_address=client_ip())
return jsonify({"status": "ok"})
@@ -166,7 +249,7 @@ async def test_smtp():
uid = get_current_user_id()
try:
await send_test_email(recipient)
await log_audit("smtp_test", user_id=uid, username=g.user.username, ip_address=request.remote_addr, details={"recipient": recipient})
await log_audit("smtp_test", user_id=uid, username=g.user.username, ip_address=client_ip(), details={"recipient": recipient})
return jsonify({"status": "ok"})
except Exception as e:
return jsonify({"error": str(e)}), 500
@@ -180,7 +263,6 @@ async def test_smtp():
@admin_bp.route("/forge-webhook", methods=["GET"])
@admin_required
async def get_forge_webhook_settings():
from grimoire.config import Config
from grimoire.routes.webhooks import FORGE_WEBHOOK_SECRET_KEY
webhook_secret = (
@@ -209,7 +291,7 @@ async def update_forge_webhook_settings():
# The secret is deliberately absent from the audit detail.
await log_audit(
"forge_webhook_config", user_id=uid, username=g.user.username,
ip_address=request.remote_addr, details={},
ip_address=client_ip(), details={},
)
return jsonify({"status": "ok"})
@@ -262,10 +344,48 @@ async def update_base_url():
return jsonify({"error": "Base URL must use http or https"}), 400
uid = get_current_user_id()
await set_setting(uid, "base_url", url)
await log_audit("base_url_config", user_id=uid, username=g.user.username, ip_address=request.remote_addr, details={"base_url": url})
await log_audit("base_url_config", user_id=uid, username=g.user.username, ip_address=client_ip(), details={"base_url": url})
return jsonify({"status": "ok"})
def _proxy_payload() -> dict:
return {
"hops": proxy.trusted_hops(),
"source": proxy_settings.source(),
"env_hops": Config.TRUSTED_PROXY_HOPS,
"max_hops": proxy.MAX_HOPS,
"readout": proxy.request_readout(),
}
@admin_bp.route("/proxy", methods=["GET"])
@admin_required
async def get_proxy_setting():
"""The hop count in force, where it came from, and what each count would
make of the admin's own request."""
return jsonify(_proxy_payload())
@admin_bp.route("/proxy", methods=["PUT"])
@admin_required
async def update_proxy_setting():
"""Save the hop count, or `{"hops": null}` to go back to the environment's.
It applies to the next request."""
data = await request.get_json() or {}
raw = data.get("hops")
hops = None if raw is None else proxy_settings.parse_hops(raw)
if raw is not None and hops is None:
return jsonify({"error": f"The proxy count must be a whole number from 0 to {proxy.MAX_HOPS}."}), 400
before = proxy.trusted_hops()
await proxy_settings.save_hops(hops)
uid = get_current_user_id()
await log_audit(
"proxy_hops_config", user_id=uid, username=g.user.username, ip_address=client_ip(),
details={"before": before, "after": proxy.trusted_hops(), "saved": hops},
)
return jsonify(_proxy_payload())
@admin_bp.route("/db-maintenance", methods=["GET"])
@admin_required
async def get_db_maintenance():
@@ -310,7 +430,7 @@ async def update_db_maintenance():
uid = get_current_user_id()
await log_audit(
"db_maintenance_config", user_id=uid, username=g.user.username,
ip_address=request.remote_addr, details={"enabled": enabled, "hour": hour},
ip_address=client_ip(), details={"enabled": enabled, "hour": hour},
)
return jsonify({"status": "ok", "enabled": enabled, "hour": hour})
@@ -323,7 +443,7 @@ async def run_db_maintenance_now():
uid = get_current_user_id()
await log_audit(
"db_maintenance_run", user_id=uid, username=g.user.username,
ip_address=request.remote_addr,
ip_address=client_ip(),
)
summary = await run_maintenance()
return jsonify(summary)
@@ -389,7 +509,7 @@ async def update_backups():
uid = get_current_user_id()
await log_audit(
"backup_config", user_id=uid, username=g.user.username,
ip_address=request.remote_addr,
ip_address=client_ip(),
details={**config.to_dict(), "secret_changed": bool(
data.get("clear_s3_secret") or (isinstance(secret, str) and secret and secret != SECRET_MASK)
)},
@@ -439,7 +559,7 @@ async def run_backup_now():
return jsonify({"error": "A backup is already running."}), 409
uid = get_current_user_id()
await log_audit("backup_run", user_id=uid, username=g.user.username,
ip_address=request.remote_addr, details={})
ip_address=client_ip(), details={})
return jsonify({"status": "started"}), 202
@@ -463,7 +583,7 @@ async def create_invite():
"invitation_created",
user_id=uid,
username=g.user.username,
ip_address=request.remote_addr,
ip_address=client_ip(),
details={"invited_email": email},
)
return jsonify({"status": "ok"}), 201
@@ -497,7 +617,7 @@ async def delete_invitation(invitation_id: int):
"invitation_revoked",
user_id=uid,
username=g.user.username,
ip_address=request.remote_addr,
ip_address=client_ip(),
details={"invitation_id": invitation_id},
)
return jsonify({"status": "ok"})
+24 -32
View File
@@ -8,7 +8,8 @@ from quart import Blueprint, g, jsonify, redirect, request, session
from grimoire.auth import login_required, get_current_user_id
from grimoire.config import Config
from grimoire.rate_limit import is_rate_limited
from grimoire.proxy import client_ip
from grimoire.rate_limit import SHARED_ADDRESS_HINT, is_rate_limited
from grimoire.services.auth import (
authenticate,
change_password,
@@ -43,21 +44,12 @@ from grimoire.services.oauth import (
auth_bp = Blueprint("auth", __name__, url_prefix="/api/auth")
def _client_ip() -> str:
if Config.TRUST_PROXY_HEADERS:
for header in ("X-Forwarded-For", "X-Real-IP"):
val = request.headers.get(header, "").split(",")[0].strip()
if val:
return val
return request.remote_addr or ""
@auth_bp.route("/register", methods=["POST"])
async def register():
if not Config.LOCAL_AUTH_ENABLED:
return jsonify({"error": "Local authentication is disabled. Please use SSO."}), 403
if await is_rate_limited(f"register:{_client_ip()}", max_requests=5, window_seconds=300):
return jsonify({"error": "Too many registration attempts. Try again later."}), 429
if await is_rate_limited(f"register:{client_ip()}", max_requests=5, window_seconds=300):
return jsonify({"error": f"Too many registration attempts. Try again later. {SHARED_ADDRESS_HINT}"}), 429
if not await is_registration_open():
return jsonify({"error": "Registration is closed"}), 403
@@ -78,7 +70,7 @@ async def register():
session["user_id"] = user.id
session["session_version"] = user.session_version
await log_audit("register", user_id=user.id, username=user.username, ip_address=_client_ip())
await log_audit("register", user_id=user.id, username=user.username, ip_address=client_ip())
return jsonify(user.to_dict()), 201
@@ -86,8 +78,8 @@ async def register():
async def login():
if not Config.LOCAL_AUTH_ENABLED:
return jsonify({"error": "Local authentication is disabled. Please use SSO."}), 403
if await is_rate_limited(f"login:{_client_ip()}", max_requests=10, window_seconds=60):
return jsonify({"error": "Too many login attempts. Try again later."}), 429
if await is_rate_limited(f"login:{client_ip()}", max_requests=10, window_seconds=60):
return jsonify({"error": f"Too many login attempts. Try again later. {SHARED_ADDRESS_HINT}"}), 429
data = await request.get_json()
username = (data.get("username") or "").strip()
password = data.get("password") or ""
@@ -97,22 +89,22 @@ async def login():
user = await authenticate(username, password)
if not user:
await log_audit("login_failed", username=username, ip_address=_client_ip())
await log_audit("login_failed", username=username, ip_address=client_ip())
# Try to notify the actual user about the failed attempt
target_user = await get_user_by_username(username)
if target_user:
asyncio.create_task(notify_security_event(
target_user.id, "login_failed",
{"ip_address": _client_ip(), "username": username},
{"ip_address": client_ip(), "username": username},
))
return jsonify({"error": "Invalid username or password"}), 401
session["user_id"] = user.id
session["session_version"] = user.session_version
await log_audit("login", user_id=user.id, username=user.username, ip_address=_client_ip())
await log_audit("login", user_id=user.id, username=user.username, ip_address=client_ip())
asyncio.create_task(notify_security_event(
user.id, "login",
{"ip_address": _client_ip()},
{"ip_address": client_ip()},
))
return jsonify(user.to_dict())
@@ -122,10 +114,10 @@ async def logout():
uid = session.get("user_id")
if uid:
user = await get_user_by_id(uid)
await log_audit("logout", user_id=uid, username=user.username if user else None, ip_address=_client_ip())
await log_audit("logout", user_id=uid, username=user.username if user else None, ip_address=client_ip())
asyncio.create_task(notify_security_event(
uid, "logout",
{"ip_address": _client_ip()},
{"ip_address": client_ip()},
))
session.clear()
return jsonify({"status": "ok"})
@@ -159,10 +151,10 @@ async def update_password():
# Keep the current session alive with the new version (other sessions are now invalidated)
session["session_version"] = new_version
await log_audit("password_change", user_id=uid, username=g.user.username, ip_address=_client_ip())
await log_audit("password_change", user_id=uid, username=g.user.username, ip_address=client_ip())
asyncio.create_task(notify_security_event(
uid, "password_change",
{"ip_address": _client_ip()},
{"ip_address": client_ip()},
))
return jsonify({"status": "ok"})
@@ -178,7 +170,7 @@ async def invalidate_sessions_route():
uid = get_current_user_id()
new_version = await invalidate_other_sessions(uid)
session["session_version"] = new_version
await log_audit("sessions_invalidated", user_id=uid, username=g.user.username, ip_address=_client_ip())
await log_audit("sessions_invalidated", user_id=uid, username=g.user.username, ip_address=client_ip())
return jsonify({"status": "ok"})
@@ -208,14 +200,14 @@ async def update_email():
return jsonify({"error": "Email already in use by another account"}), 409
await update_user_email(uid, new_email)
await log_audit("email_change", user_id=uid, username=user.username, ip_address=_client_ip())
await log_audit("email_change", user_id=uid, username=user.username, ip_address=client_ip())
updated = await get_user_by_id(uid)
return jsonify(updated.to_dict())
@auth_bp.route("/forgot-password", methods=["POST"])
async def forgot_password():
if await is_rate_limited(f"forgot:{_client_ip()}", max_requests=5, window_seconds=300):
if await is_rate_limited(f"forgot:{client_ip()}", max_requests=5, window_seconds=300):
return jsonify({"status": "ok"})
data = await request.get_json()
email = (data.get("email") or "").strip().lower()
@@ -234,7 +226,7 @@ async def forgot_password():
"password_reset_requested",
user_id=user.id,
username=user.username,
ip_address=_client_ip(),
ip_address=client_ip(),
)
return jsonify({"status": "ok"})
@@ -242,8 +234,8 @@ async def forgot_password():
@auth_bp.route("/reset-password", methods=["POST"])
async def reset_password():
if await is_rate_limited(f"reset:{_client_ip()}", max_requests=10, window_seconds=60):
return jsonify({"error": "Too many attempts. Try again later."}), 429
if await is_rate_limited(f"reset:{client_ip()}", max_requests=10, window_seconds=60):
return jsonify({"error": f"Too many attempts. Try again later. {SHARED_ADDRESS_HINT}"}), 429
data = await request.get_json()
token = (data.get("token") or "").strip()
new_password = data.get("new_password") or ""
@@ -261,7 +253,7 @@ async def reset_password():
if user:
await log_audit(
"password_reset_completed",
user_id=user.id, username=user.username, ip_address=_client_ip(),
user_id=user.id, username=user.username, ip_address=client_ip(),
)
if user.email:
asyncio.create_task(send_password_reset_success_email(user.email))
@@ -304,7 +296,7 @@ async def register_with_invite():
"register_with_invite",
user_id=user.id,
username=user.username,
ip_address=_client_ip(),
ip_address=client_ip(),
)
return jsonify(user.to_dict()), 201
@@ -371,5 +363,5 @@ async def oauth_callback():
user = await find_or_create_oauth_user(sub, email, preferred_username)
session["user_id"] = user.id
session["session_version"] = user.session_version
await log_audit("oauth_login", user_id=user.id, username=user.username, ip_address=_client_ip())
await log_audit("oauth_login", user_id=user.id, username=user.username, ip_address=client_ip())
return redirect("/")
+32
View File
@@ -6,6 +6,7 @@ from quart import Blueprint, jsonify, request
from grimoire.auth import login_required, get_current_user_id
from grimoire.routes.utils import not_found, parse_iso_date, parse_pagination
from grimoire.services import record_refs
from grimoire.services.access import can_write_note
from grimoire.services.notes import (
build_note_graph,
@@ -194,6 +195,37 @@ async def resolve_title_route():
return jsonify(note.to_dict())
@notes_bp.route("/resolve-refs", methods=["POST"])
@login_required
async def resolve_refs_route():
"""What the record references in a rendered body point at.
Body: {"notes": [ids], "milestones": [ids], "rules": [ids]}. Answers the
same three keys, each a map of id -> {title, kind fields}, holding only the
records the caller may read. An id left out of the answer is drawn as a
reference that leads nowhere. The web UI calls this once per rendered body
to give each `#N`, `milestone N` and `rule N` link its route and its title.
"""
uid = get_current_user_id()
data = await request.get_json(silent=True) or {}
spaces: dict[str, list[int]] = {}
for key in ("notes", "milestones", "rules"):
raw = data.get(key) or []
if not isinstance(raw, list):
return jsonify({"error": f"{key} must be a list of ids"}), 400
try:
spaces[key] = [int(i) for i in raw]
except (TypeError, ValueError):
return jsonify({"error": f"{key} must be a list of ids"}), 400
if sum(len(v) for v in spaces.values()) > record_refs.RESOLVE_LIMIT:
return jsonify({
"error": f"at most {record_refs.RESOLVE_LIMIT} references per call",
}), 400
resolved = await record_refs.resolve_refs(uid, **spaces)
# JSON object keys are strings; say so here rather than in every caller.
return jsonify({k: {str(i): v for i, v in m.items()} for k, m in resolved.items()})
@notes_bp.route("/duplicates", methods=["GET"])
@login_required
async def find_duplicate_records_route():
+89 -2
View File
@@ -8,6 +8,8 @@ fmcp_<key>` API key (a read-scoped key suffices for this GET).
"""
from __future__ import annotations
import json
from quart import Blueprint, g, jsonify, request
from grimoire.auth import admin_required, get_current_user_id, login_required
@@ -18,9 +20,12 @@ from grimoire.services import plugin_context as plugin_ctx_svc
from grimoire.services import reply_shapes as reply_shapes_svc
from grimoire.services import repo_bindings as repo_bindings_svc
from grimoire.services import report_check as report_check_svc
from grimoire.services import rule_deliveries as rule_deliveries_svc
from grimoire.services import rule_moment_judgments as judgments_svc
from grimoire.services import shape_check as shape_check_svc
from grimoire.services import task_claims as task_claims_svc
from grimoire.services import write_scope as write_scope_svc
from grimoire.services.access import can_read_project
from grimoire.services.embeddings import memoized_query_embeddings
from grimoire.services.settings import get_admin_setting, set_setting
@@ -32,6 +37,22 @@ plugin_bp = Blueprint("plugin", __name__, url_prefix="/api/plugin")
_MARKETPLACE_KEY = "plugin_marketplace_url"
@plugin_bp.before_request
async def _bind_delivery_session() -> None:
"""Bind the session this request delivers to, for the delivery record.
A hook names it as `session_id` in the query, or carries it in the event
it posts (`/moment` sends the PreToolUse event whole). A request that
names none records no deliveries and reads no delivery history.
"""
sid = request.args.get("session_id") or ""
if not sid and request.method == "POST":
body = await request.get_json(silent=True)
if isinstance(body, dict):
sid = str(body.get("session_id") or "")
rule_deliveries_svc.bind_session(sid)
def _int_list(raw: str | None) -> list[int]:
"""A comma-separated id list from the query string; non-ints dropped."""
return [int(p) for p in (raw or "").split(",") if p.strip().isdigit()]
@@ -332,7 +353,10 @@ async def rule_opened():
"""A session opened a rule shortly after these acts.
Body: `{"rule_id", "session_id", "acts": [<PreToolUse event>, ...]}` —
the calls the plugin saw in the window before the `get_rule`. Each is
the calls the plugin saw in the window before the `get_rule`. Every open
is first stamped on this session's latest delivery of the rule, which is
how the open rate per delivery is measured; `acts` is empty when the
rule was one a hook had just named, which explains the open by itself. Each is
resolved to its moments, and the open is counted as evidence that the
rule belongs on them; once a pair has repeated across enough distinct
sessions, `context` carries the line asking the reader to offer the
@@ -345,8 +369,13 @@ async def rule_opened():
rule_id = int(data.get("rule_id") or 0)
except (TypeError, ValueError):
rule_id = 0
if rule_id > 0:
# The open, against the delivery it followed — whatever the acts say.
await rule_deliveries_svc.mark_opened(
g.user.id, str(data.get("session_id") or ""), rule_id,
)
acts = data.get("acts")
if rule_id <= 0 or not isinstance(acts, list):
if rule_id <= 0 or not isinstance(acts, list) or not acts:
return jsonify({"moments": [], "context": ""})
project_id, _repo, _unbound = await _project_scope()
return jsonify(await judgments_svc.opened_after(
@@ -626,6 +655,64 @@ async def claim_session():
return jsonify({"claim": claim})
@plugin_bp.get("/write-scope")
@login_required
async def write_scope():
"""May this session do this act? Asked by `grimoire_project_fence.sh`
before a file edit, a git command or a Grimoire write.
A session belongs to the project its starting directory resolves to
(`repo` / `project_id`, as every plugin endpoint reads them), or when
that resolves to none, to `fallback_project_id`: the first project the
session entered. The act is
either a directory (`target_repo` / `target_project_id`) or an MCP call
(`tool`, with `input` as a JSON object of the call's short arguments: the
ids, kind and status that say where it writes). `act` words the act for the
reason, e.g. "git push in".
Returns `{allowed, session_project, targets, issue, reason}` from
services/write_scope.check_act. A GET, so a read-scoped key still fences
file edits and git commands.
"""
session_project, _repo, _unbound = await _project_scope()
if not session_project:
# A session that started outside any project belongs to the first one
# it entered; the hook remembers it.
try:
session_project = int(request.args.get("fallback_project_id") or 0)
except ValueError:
session_project = 0
if session_project and not await can_read_project(g.user.id, session_project):
session_project = 0
tool = (request.args.get("tool") or "").strip()
if tool.startswith("mcp__"):
tool = tool.rsplit("__", 1)[-1]
args: dict = {}
if tool:
try:
parsed = json.loads(request.args.get("input") or "{}")
except ValueError:
return jsonify({"error": "input must be a JSON object"}), 400
if not isinstance(parsed, dict):
return jsonify({"error": "input must be a JSON object"}), 400
args = parsed
target_project = 0
if not tool:
try:
target_project = int(request.args.get("target_project_id") or 0)
except ValueError:
target_project = 0
target_repo = (request.args.get("target_repo") or "").strip()
if not target_project and target_repo:
target_project = await repo_bindings_svc.resolve_project(g.user.id, target_repo) or 0
result = await write_scope_svc.check_act(
g.user.id, session_project, tool=tool, args=args,
target_project=target_project, act=(request.args.get("act") or "")[:80],
)
result["session_project"] = session_project or None
return jsonify(result)
@plugin_bp.get("/release-session")
@login_required
async def release_session():
+27 -2
View File
@@ -18,6 +18,18 @@ from grimoire.services.rule_usage import (
rulebooks_bp = Blueprint("rulebooks", __name__, url_prefix="/api")
def _declared_or_refusal(data: dict):
"""The request's enforcement and salience, validated before any write, so
a bad value is a 400 naming the choices rather than a half-made rule."""
try:
return (
rulebooks_svc.require_enforcement(data.get("enforcement"), data.get("kind")),
rulebooks_svc.require_salience(data.get("salience")),
), None
except ValueError as exc:
return None, (jsonify({"error": str(exc)}), 400)
def _moments_or_refusal(data: dict):
"""The request's `moments`, validated BEFORE any write — so an unknown
name is a 400 and not a rule created without the mounts it asked for.
@@ -184,6 +196,10 @@ async def create_rule(topic_id: int):
moments, refused = _moments_or_refusal(data)
if refused:
return refused
declared, refused = _declared_or_refusal(data)
if refused:
return refused
enforcement, salience = declared
try:
rule = await rulebooks_svc.create_rule(
topic_id=topic_id,
@@ -202,6 +218,7 @@ async def create_rule(topic_id: int):
arose_from_id=data.get("arose_from_id", 0) or 0,
verify_with=data.get("verify_with", ""),
expires_when=data.get("expires_when", ""),
enforcement=enforcement, salience=salience,
)
except ValueError as exc:
return jsonify({"error": str(exc)}), 404
@@ -234,7 +251,7 @@ async def update_rule(rule_id: int):
k: v for k, v in data.items()
if k in ("title", "statement", "why", "how_to_apply", "order_index",
"when_to_apply", "kind", "arose_from_id",
"verify_with", "expires_when")
"verify_with", "expires_when", "enforcement", "salience")
}
# No clear_fields here: a form sends "" for an emptied input, and the
# service normalises "" to NULL for every nullable text column. The MCP
@@ -243,7 +260,10 @@ async def update_rule(rule_id: int):
moments, refused = _moments_or_refusal(data)
if refused:
return refused
rule = await rulebooks_svc.update_rule(rule_id, uid, **fields)
try:
rule = await rulebooks_svc.update_rule(rule_id, uid, **fields)
except ValueError as exc:
return jsonify({"error": str(exc)}), 400
if rule is None:
return jsonify({"error": "rule not found"}), 404
return jsonify(await rulebooks_svc.rule_detail(
@@ -425,6 +445,10 @@ async def create_project_rule(project_id: int):
moments, refused = _moments_or_refusal(data)
if refused:
return refused
declared, refused = _declared_or_refusal(data)
if refused:
return refused
enforcement, salience = declared
try:
rule = await rulebooks_svc.create_project_rule(
project_id=project_id,
@@ -443,6 +467,7 @@ async def create_project_rule(project_id: int):
arose_from_id=data.get("arose_from_id", 0) or 0,
verify_with=data.get("verify_with", ""),
expires_when=data.get("expires_when", ""),
enforcement=enforcement, salience=salience,
)
except ValueError as exc:
return jsonify({"error": str(exc)}), 404
File diff suppressed because it is too large Load Diff
+63 -3
View File
@@ -4,8 +4,9 @@ Two kinds of destination, both instance-wide and set by an admin:
- **folder**: a directory inside the container, usually a mounted share. A
backup service that watches the share (or a person) takes it from there.
- **s3**: any S3-compatible bucket, addressed by path. Grimoire only puts and
lists, so an append-only key is enough.
- **s3**: any S3-compatible bucket, addressed by path. Grimoire puts and
lists, and reads one back for a restore, so a key that can add and read
objects is enough; it never needs to delete.
Either way Grimoire ADDS one dated file per run and never removes one: keeping
and thinning the history is the destination's job (services/backup_file.py
@@ -28,7 +29,7 @@ from datetime import datetime
from pathlib import Path
from grimoire.services import backup_file
from grimoire.services.backup_s3 import S3Error, S3Target, list_objects, put_file
from grimoire.services.backup_s3 import S3Error, S3Target, get_file, list_objects, put_file
from grimoire.services.secrets import seal, unseal
from grimoire.services.settings import get_admin_setting, set_admin_setting
@@ -260,3 +261,62 @@ async def check_destination(
def _count_backups(folder: Path) -> int:
return sum(1 for name in os.listdir(folder) if backup_file.is_backup_name(name))
@dataclass(frozen=True)
class StoredBackup:
name: str
size_bytes: int
def _taken_order(name: str) -> str:
# The timestamp after the prefix, so grimoire- and scribe- names interleave
# by when they were taken.
return name.split("-", 1)[-1]
async def list_backups(config: BackupConfig, secret: str | None, limit: int = 50) -> list[StoredBackup]:
"""The backups at the destination, newest first."""
if config.destination == "folder":
folder = Path(config.folder_path)
if not folder.is_dir():
raise DestinationError(f"{folder} isn't there, or isn't a folder.")
def scan() -> list[StoredBackup]:
return [
StoredBackup(entry.name, entry.stat().st_size)
for entry in os.scandir(folder)
if entry.is_file() and backup_file.is_backup_name(entry.name)
]
found = await asyncio.to_thread(scan)
else:
problems = config.problems(has_secret=bool(secret))
if problems:
raise DestinationError(" ".join(problems))
try:
objects = await list_objects(s3_target(config, secret or ""))
except S3Error as exc:
raise DestinationError(str(exc)) from None
found = [StoredBackup(o.key, o.size) for o in objects if backup_file.is_backup_name(o.key)]
return sorted(found, key=lambda b: _taken_order(b.name), reverse=True)[:limit]
async def open_backup(config: BackupConfig, secret: str | None, name: str, staging: Path) -> Path:
"""A local path to the backup `name` at the destination: the file itself
in a folder, or a download into `staging` from a bucket. Only a name the
scheduled backup writes is accepted, so the request can't reach any other
file or object."""
if Path(name).name != name or not backup_file.is_backup_name(name):
raise DestinationError(f"{name!r} isn't the name of a Grimoire backup.")
if config.destination == "folder":
path = Path(config.folder_path) / name
if not path.is_file():
raise DestinationError(f"{name} isn't in {config.folder_path}.")
return path
target = s3_target(config, secret or "")
path = staging / name
try:
await get_file(target, name, path)
except S3Error as exc:
raise DestinationError(str(exc)) from None
return path
+66
View File
@@ -24,11 +24,14 @@ import os
import time
from datetime import datetime, timedelta, timezone
from pathlib import Path
from apscheduler.triggers.cron import CronTrigger
from grimoire.services.backup_destination import (
DestinationError, deliver, load_config, load_secret,
)
from grimoire.services.backup_file import write_archive
from grimoire.services.scheduler import ScheduledJob
from grimoire.services.settings import get_admin_setting, set_admin_setting
@@ -45,6 +48,9 @@ STALE_AFTER = timedelta(hours=26)
# has none, and a run that never returns holds the lock — every later backup
# would be skipped as "already running", silently, forever.
RUN_DEADLINE = timedelta(minutes=60)
# Under DATA_DIR: where a rollback keeps the backup of what it replaced when
# no backup destination takes it.
PRE_RESTORE_DIR = "pre-restore"
_LOCK = asyncio.Lock()
_TASKS: set[asyncio.Task] = set()
@@ -155,6 +161,66 @@ async def _export_and_deliver(config, secret, started):
)
async def save_state_before_restore() -> dict:
"""Back up the store as it is now, before a rollback replaces it, and say
where the file went: the backup destination when backups are on and it
takes the file, otherwise DATA_DIR/pre-restore. Raises when neither takes
it, so a rollback never runs without a way back."""
from grimoire.config import Config
from grimoire.services.backup import export_full_backup
at = datetime.now(timezone.utc)
app_version = os.environ.get("APP_VERSION", "dev")
payload = await export_full_backup()
note = None
config = await load_config()
if config.enabled:
secret, _ = await load_secret()
try:
delivered = await asyncio.wait_for(
deliver(payload, config, secret, at, app_version=app_version),
RUN_DEADLINE.total_seconds(),
)
return {"file": delivered.name, "size_bytes": delivered.size_bytes,
"where": delivered.where}
except (DestinationError, TimeoutError, asyncio.TimeoutError) as exc:
note = (f"The backup destination didn't take it ({exc or 'it timed out'}), "
"so it was kept on the instance instead.")
folder = Path(Config.DATA_DIR) / PRE_RESTORE_DIR
path = await asyncio.to_thread(write_archive, payload, folder, at, app_version=app_version)
saved = {"file": path.name, "size_bytes": path.stat().st_size, "where": str(folder)}
if note:
saved["note"] = note
return saved
async def rollback_to_backup(data: dict) -> dict:
"""Roll the store back to a full backup, after backing up what it
replaces. Refuses (RestoreRefused) before writing anything when the backup
can't be applied here, and raises BackupBusy while a backup is running:
a backup taken during a rollback would mix the two states."""
from grimoire.services.backup import check_replace, replace_from_backup
await check_replace(data)
if _LOCK.locked():
raise BackupBusy()
async with _LOCK:
safety = await save_state_before_restore()
result = await replace_from_backup(data)
result["safety_backup"] = safety
logger.info("rollback: the state it replaced is in %s/%s", safety["where"], safety["file"])
return result
def start_reindex_after_restore() -> None:
"""Rebuild the search vectors a rollback cleared, in the background."""
from grimoire.services.backup import reindex_after_restore
task = asyncio.get_running_loop().create_task(reindex_after_restore())
_TASKS.add(task)
task.add_done_callback(_TASKS.discard)
def start_backup_now() -> None:
"""Start a manual backup in the background (the request returns at once;
the page reads progress from `is_running` and the run list). Raises
+32 -3
View File
@@ -4,9 +4,10 @@ path-style addressing (endpoint/bucket/key), and the two calls a backup needs.
The signing is checked against AWS's published SigV4 examples in
tests/test_services_backup_s3.py.
Grimoire puts and lists; it never deletes. The bucket keeps the history and
thins it on its own policy, so a key that may only add objects is enough —
and is the safer key to hand a service, because a stolen one cannot wipe the
Grimoire puts and lists, and reads a backup back when an admin restores from
the bucket; it never deletes. The bucket keeps the history and thins it on
its own policy, so a key that may only add and read objects is enough — and
is the safer key to hand a service, because a stolen one cannot wipe the
history it writes into.
Written by hand rather than with boto3: two calls don't justify a large
@@ -120,6 +121,12 @@ def _says(response: httpx.Response) -> str:
"AccessDenied": "the key isn't allowed to do that",
}
said = hints.get(code) or message or response.reason_phrase
if not code and 400 <= response.status_code < 500:
# S3 refuses with an <Error><Code> body. A 4xx without one came from
# something else at that address — most often a web server on the
# default port, when the S3 service listens on a port of its own.
said = ("the address answered, but not as S3 — check the scheme and "
"the port (an S3 service usually listens on its own port)")
return f"HTTP {response.status_code}{f' {code}' if code else ''}: {said}."
@@ -165,6 +172,28 @@ async def put_file(target: S3Target, key: str, path: Path, *,
raise S3Error(f"Upload of {key} refused: {_says(response)}")
async def get_file(target: S3Target, key: str, path: Path, *,
transport: httpx.AsyncBaseTransport | None = None,
now: datetime | None = None) -> None:
"""Download one object to `path`, streamed to disk."""
url = target.url(key)
headers = sign("GET", url, {}, EMPTY_SHA256, target.access_key, target.secret_key,
target.region, now or datetime.now(timezone.utc))
try:
async with httpx.AsyncClient(verify=target.verify_tls,
timeout=UPLOAD_TIMEOUT_SECONDS,
transport=transport) as client:
async with client.stream("GET", url, headers=headers) as response:
if response.status_code != 200:
await response.aread()
raise S3Error(f"Reading {key} refused: {_says(response)}")
with open(path, "wb") as f:
async for chunk in response.aiter_bytes(CHUNK):
f.write(chunk)
except httpx.HTTPError as exc:
raise _reach_error(target, exc) from None
async def list_objects(target: S3Target, prefix: str = "", limit: int = 1000, *,
transport: httpx.AsyncBaseTransport | None = None,
now: datetime | None = None) -> list[StoredObject]:
+46
View File
@@ -0,0 +1,46 @@
"""This instance's id lineage (models/instance.py says what it means)."""
from __future__ import annotations
import uuid
from sqlalchemy import select
from sqlalchemy.dialects.postgresql import insert
from sqlalchemy.ext.asyncio import AsyncSession
from grimoire.models import async_session
from grimoire.models.instance import InstanceIdentity
async def _read_or_make(session: AsyncSession) -> str:
current = (await session.execute(select(InstanceIdentity.instance_id))).scalar_one_or_none()
if current:
return current
# The migration makes the row; this covers a schema built some other way.
await session.execute(
insert(InstanceIdentity)
.values(id=1, instance_id=str(uuid.uuid4()))
.on_conflict_do_nothing(index_elements=["id"])
)
return (await session.execute(select(InstanceIdentity.instance_id))).scalar_one()
async def get_instance_id(session: AsyncSession | None = None) -> str:
"""This instance's id. Inside `session` when given, so a caller's
transaction sees the same value it may be about to change."""
if session is not None:
return await _read_or_make(session)
async with async_session() as own:
value = await _read_or_make(own)
await own.commit()
return value
async def adopt_instance_id(session: AsyncSession, value: str) -> None:
"""Take a backup's id as this instance's own, inside the caller's
transaction: after a restore that kept the backup's original ids, this
store and the one the backup came from number their rows the same way."""
await session.execute(
insert(InstanceIdentity)
.values(id=1, instance_id=value)
.on_conflict_do_update(index_elements=["id"], set_={"instance_id": value})
)
+4 -1
View File
@@ -24,11 +24,14 @@ logger = logging.getLogger(__name__)
def _io() -> rp.MomentIO:
"""Resolved at CALL time, so a test patching either module's name is seen."""
from grimoire.services import rule_usage, rulebooks
from grimoire.services import rule_deliveries, rule_usage, rulebooks
bound = rule_deliveries.bound()
return rp.MomentIO(
lookup=rulebooks.rules_on_moments,
record_rule_surfaced=rule_usage.record_rule_surfaced,
history=rule_deliveries.history if bound else None,
record_delivery=rule_deliveries.record if bound else None,
)
+81 -18
View File
@@ -986,33 +986,80 @@ async def get_notes_by_ids(user_id: int, note_ids: list[int]) -> dict[int, Note]
async def get_backlinks(user_id: int, note_id: int) -> list[dict]:
note = await get_note(user_id, note_id)
if note is None:
return []
"""The records that link to this one, among those the caller may read.
title = note.title
if not title:
Two ways to link: a `[[title]]` wikilink, and a `#N` reference in a body or
in a task's work log (most cross-references agents write are the second).
Each row says which one it was in `via`. A record reached both ways is
listed once, as a wikilink.
"""
from grimoire.models.task_log import TaskLog
from grimoire.services.access import readable_notes_clause
from grimoire.services.record_refs import referenced
found = await get_note_for_user(user_id, note_id)
if found is None:
return []
note, _ = found
readable = readable_notes_clause(user_id)
rows: dict[int, dict] = {}
def _row(n: Note, via: str) -> dict:
return {
"type": "task" if n.is_task else "note",
"id": n.id,
"title": n.title,
"is_task": n.is_task,
"note_type": n.note_type or "note",
"via": via,
}
async with async_session() as session:
escaped = title.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
pattern = f"%[[{escaped}]]%"
pattern_alias = f"%[[{escaped}|%"
if note.title:
escaped = note.title.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
linking = (await session.execute(
select(Note).where(
readable,
Note.id != note_id,
Note.deleted_at.is_(None),
or_(Note.body.like(f"%[[{escaped}]]%"),
Note.body.like(f"%[[{escaped}|%")),
)
)).scalars().all()
for n in linking:
rows[n.id] = _row(n, "wikilink")
results = await session.execute(
select(Note.id, Note.title, Note.status).where(
Note.user_id == user_id,
# LIKE narrows to bodies holding the digits after a `#`; `referenced`
# then reads each one the way the renderer does, so `#12` does not
# count as a link to 1, and "PR #12" is not a link at all.
needle = f"%#{note_id}%"
citing = (await session.execute(
select(Note).where(
readable,
Note.id != note_id,
Note.deleted_at.is_(None),
or_(Note.body.like(pattern), Note.body.like(pattern_alias)),
Note.body.like(needle),
)
)
backlinks: list[dict] = []
for row in results.fetchall():
link_type = "task" if row[2] is not None else "note"
backlinks.append({"type": link_type, "id": row[0], "title": row[1]})
)).scalars().all()
for n in citing:
if n.id not in rows and note_id in referenced(n.body)["notes"]:
rows[n.id] = _row(n, "reference")
return backlinks
logged = (await session.execute(
select(Note, TaskLog.content)
.join(TaskLog, TaskLog.task_id == Note.id)
.where(
readable,
Note.id != note_id,
Note.deleted_at.is_(None),
TaskLog.content.like(needle),
)
)).all()
for n, content in logged:
if n.id not in rows and note_id in referenced(content)["notes"]:
rows[n.id] = _row(n, "reference")
return list(rows.values())
_WIKILINK_RE = re.compile(r'\[\[([^\]|]+)(?:\|[^\]]+)?\]\]')
@@ -1071,6 +1118,22 @@ async def build_note_graph(
edge_set.add(pair)
edges.append({"source": n.id, "target": target_id, "type": "wikilink"})
# `#N` reference edges, read the way the renderer links them. Only between
# records already on the graph: a reference to something outside it (another
# project, a record the caller cannot read) has no node to end at.
from grimoire.services.record_refs import referenced
on_graph = {n.id for n in notes}
for n in notes:
if not n.body:
continue
for target_id in sorted(referenced(n.body)["notes"]):
if target_id in on_graph and target_id != n.id:
pair = (n.id, target_id)
if pair not in edge_set:
edge_set.add(pair)
edges.append({"source": n.id, "target": target_id, "type": "reference"})
# Build tag nodes + note→tag edges
if include_shared_tags:
tag_to_ids: dict[str, list[int]] = {}
+54
View File
@@ -143,6 +143,11 @@ WRITEPATH_ENABLED_KEY = "kb_writepath_enabled"
WRITEPATH_THRESHOLD_KEY = SURFACES["write_path"].floor_key
WRITEPATH_DEFAULT_ENABLED = True
WRITEPATH_DEFAULT_THRESHOLD = SURFACES["write_path"].floor_default
# How far past the write-path floor a snippet must resemble a NEW definition
# before the hint asks whether the code is a copy of it. A margin, not a second
# floor, so it moves when the operator tunes the write-path floor: at the
# default 0.68 the copy bar is 0.80.
WRITEPATH_COPY_MARGIN = 0.12
# The standing-rule arms get their own bar, for a third corpus: 0.68 above is
# calibrated on code against note PROSE, not code against RULE TEXT.
@@ -969,10 +974,15 @@ def _rule_io() -> rp.RuleIO:
the pipeline reports to whatever this module's `semantic_search_rules`,
`record_retrieval` and `record_rule_surfaced` are at the moment it runs.
"""
from grimoire.services import rule_deliveries
bound = rule_deliveries.bound()
return rp.RuleIO(
search=semantic_search_rules,
record_retrieval=record_retrieval,
record_rule_surfaced=record_rule_surfaced,
history=rule_deliveries.history if bound else None,
record_delivery=rule_deliveries.record if bound else None,
)
@@ -1444,6 +1454,9 @@ async def build_write_path_hint(
note.title, note.note_type, note.data, note.body,
),
"seen": int(note.id) in excluded,
# Read by the copy check, which asks for more
# resemblance than the menu does.
"score": float(score),
# Carried, not re-read off the rendered marker. The
# marker is prose assembled for a human and it already
# varies by kind, language and the `seen` flag — a
@@ -1498,6 +1511,29 @@ async def build_write_path_hint(
derive = [d for d in found if d.get("key") not in skip]
except Exception:
logger.warning("write-time derive check failed", exc_info=True)
# The COPY check: the derive check matches by name, so a renamed copy
# of a recorded snippet passes it and shows only as "similar" prior art.
# When this write introduces a definition and an unseen snippet on the
# menu resembles it well past the menu's own floor, say that a copy is
# the moment to extract. Only a recorded snippet can be seen this way —
# the ledger keeps no bodies to compare an unrecorded sibling against.
copies: list[dict] = []
copy_bar = cfg["threshold"] + WRITEPATH_COPY_MARGIN
strong = [
it for _m, it in menu
if it.get("kind") == "snippet" and not it.get("seen")
and it.get("score", 0.0) >= copy_bar
]
if strong and stamp_shapes and project_id:
named = {d["symbol"] for d in derive} | {s["symbol"] for s in suggested}
try:
fresh = await shape_ledger_svc.new_shapes_at(project_id, path, stamp_shapes)
copies = [
{"symbol": n, "kind": k, "snippet": strong[0]}
for k, n in fresh if n not in named
]
except Exception:
logger.warning("write-time copy check failed", exc_info=True)
staleness: list[str] = []
# The design arm is decided HERE, above the guard, so a UI write
@@ -1681,6 +1717,8 @@ async def build_write_path_hint(
lines.append(_divergence_line(path, divergence))
if derive:
lines.append(_derive_line(path, derive))
if copies:
lines.append(_copy_line(copies))
# Split by arm, which is the whole reason this table exists. The place arm
# carries no score and so has no home in retrieval_logs, yet it fires on
@@ -2008,6 +2046,22 @@ def _divergence_line(path: str, divergence: list[dict]) -> str:
)
def _copy_line(copies: list[dict]) -> str:
"""A new definition that closely resembles a recorded snippet under
another name: the derive check cannot see a renamed copy, so this says
it — as a question for the writer, since resemblance is not identity."""
snip = copies[0]["snippet"]
names = ", ".join(
f"`{'.' if c['kind'] == 'css' else ''}{c['symbol']}`" for c in copies
)
return (
f"> {names} {'is' if len(copies) == 1 else 'are'} new in this file and "
f"this code resembles snippet #{snip['id']} `{snip.get('name') or snip['title']}` "
f"(similar {snip['score']:.2f}). If it copies that shape, reuse #{snip['id']} "
"or extract the shared shape now, before another copy is written."
)
def _suggest_line(path: str, suggested: list[dict]) -> str:
"""One line naming the recorded shape this code looks like, as evidence
for the judgment the agent gives at the end of the turn — not a record of
+129
View File
@@ -0,0 +1,129 @@
"""The reverse-proxy hop count an admin saves in Settings → Config.
How many proxies stand in front of the app decides which address every rate
limit and audit line sees, and whether a request counts as HTTPS
(grimoire/proxy.py). Behind Cloudflare's proxied DNS the right count is 2; at
the default of 1 every visitor reads as a Cloudflare edge address and they
share one sign-in rate limit. So the count is set where an admin can find it
and check it against their own request, not only in the environment.
Precedence: the saved count, then `TRUSTED_PROXY_HOPS` from the environment,
then 1. Saving None removes the saved count, so the environment's applies
again.
It is one instance-wide value, kept on the first admin account like the other
instance settings. Every worker holds it in proxy.py, loads it at startup and
re-reads it every REFRESH_SECONDS, so a save in one worker reaches the others
within that interval; the worker that saved applies it at once.
"""
from __future__ import annotations
import asyncio
import logging
from sqlalchemy import delete, select
from grimoire import proxy
from grimoire.config import Config
from grimoire.models import async_session
from grimoire.models.setting import Setting
from grimoire.models.user import User
logger = logging.getLogger(__name__)
SETTING_KEY = "trusted_proxy_hops"
REFRESH_SECONDS = 30
# The load at startup runs inside the lifespan hook, and a hook that does not
# return is a worker that never serves (db_maintenance_scheduler explains the
# outage that taught this). One indexed row answers in milliseconds, so the
# deadline only fires when the database is already in trouble.
STARTUP_READ_TIMEOUT = 3.0
def parse_hops(raw) -> int | None:
"""A hop count from 0 to proxy.MAX_HOPS, or None for anything else. A
bool is refused, though Python counts it as an int."""
if isinstance(raw, bool):
return None
if isinstance(raw, str):
raw = raw.strip()
if not raw.isdigit():
return None
raw = int(raw)
if not isinstance(raw, int) or not 0 <= raw <= proxy.MAX_HOPS:
return None
return raw
def _admin_rows():
return (
select(Setting)
.join(User, Setting.user_id == User.id)
.where(User.role == "admin", Setting.key == SETTING_KEY)
)
async def saved_hops() -> int | None:
"""The count saved in Settings, or None when there is none (or what is
stored can't be read as one)."""
async with async_session() as session:
row = (await session.execute(_admin_rows().order_by(Setting.user_id))).scalars().first()
return parse_hops(row.value) if row else None
async def save_hops(hops: int | None) -> None:
"""Save the count, or remove it with None. Any copy on another admin's
account goes too, so exactly one value is ever read back."""
async with async_session() as session:
admin_ids = select(User.id).where(User.role == "admin")
await session.execute(
delete(Setting).where(Setting.key == SETTING_KEY, Setting.user_id.in_(admin_ids))
)
if hops is not None:
first_admin = (
await session.execute(select(User.id).where(User.role == "admin").order_by(User.id))
).scalars().first()
if first_admin is None:
raise ValueError("there is no admin account to keep the setting on")
session.add(Setting(user_id=first_admin, key=SETTING_KEY, value=str(hops)))
await session.commit()
proxy.set_saved_hops(hops)
async def refresh() -> None:
"""Load the saved count into this worker. A failed read keeps the value
it already had: an unreachable database must not switch the trust rule."""
try:
proxy.set_saved_hops(await saved_hops())
except Exception:
logger.debug("could not re-read the saved proxy hop count", exc_info=True)
async def load_at_startup() -> None:
"""`refresh`, bounded for the lifespan hook. On a timeout the environment's
count stays in force until the next refresh reaches the database."""
try:
await asyncio.wait_for(refresh(), timeout=STARTUP_READ_TIMEOUT)
except (TimeoutError, asyncio.TimeoutError):
logger.warning(
"reading the saved proxy hop count exceeded %.1fs; starting with %d "
"from the environment until the database answers",
STARTUP_READ_TIMEOUT, Config.TRUSTED_PROXY_HOPS,
)
_refresh_task = None
def start_refresh_loop() -> None:
global _refresh_task
if _refresh_task is None or _refresh_task.done():
from grimoire.services.background import start_periodic
_refresh_task = start_periodic(REFRESH_SECONDS, refresh, label="proxy_hops_refresh")
def source() -> str:
"""Where the count in force came from: "setting", "env" or "default"."""
if proxy.saved_hops_in_force() is not None:
return "setting"
return "env" if Config.TRUSTED_PROXY_HOPS_FROM_ENV else "default"
+124 -1
View File
@@ -1,4 +1,4 @@
"""Record references written into prose: refusing guessed ids, resolving placeholders, reading the ids a message names.
"""Record references written into prose: refusing guessed ids, resolving placeholders, reading the ids a message names, and saying what a body links to.
THE DEFECT THIS EXISTS FOR
@@ -41,6 +41,7 @@ restores and internal writers that legitimately carry numbers from elsewhere.
from __future__ import annotations
import re
from collections.abc import Iterable
from sqlalchemy import func, select
@@ -209,6 +210,128 @@ def _prev_word(before: str) -> str:
return m.group(1).lower() if m else ""
# ── References written into a record's prose ───────────────────────────────
#
# What a body, a work log or a plan names, read the way the web UI links it.
# `frontend/src/utils/recordRefs.ts` holds the same patterns and the same word
# list, and tests/test_record_ref_links.py reads that file and fails when its
# patterns or words differ from these.
#
# Three id spaces, three forms:
# `#N` a note, task, lesson or snippet (one sequence, the notes table)
# `milestone N` a milestone — what `{{ref:milestone}}` renders as
# `rule N` a rule; `preference N` too, since preferences are rules
# A `#N` after a word that names another numbering ("PR #198", "rule #34",
# "step #3") is not a note: `_OTHER_SPACE` above decides, exactly as it does for
# the numbers an operator names in a message.
PROSE_REF_RE = re.compile(r"(?<![\w/])\b(milestone|rule|preference)\s+#?(\d+)\b", re.IGNORECASE)
# Fenced and inline code: a pasted log or a snippet of source names nothing.
_CODE_RE = re.compile(r"```[\s\S]*?```|`[^`\n]+`")
def referenced(*texts: str | None) -> dict[str, set[int]]:
"""Every record these texts link to, by id space: notes, milestones, rules."""
out: dict[str, set[int]] = {"notes": set(), "milestones": set(), "rules": set()}
for text in texts:
if not text:
continue
text = _CODE_RE.sub(" ", text)
for m in PROSE_REF_RE.finditer(text):
space = "milestones" if m.group(1).lower() == "milestone" else "rules"
out[space].add(int(m.group(2)))
for m in REF_RE.finditer(text):
if _prev_word(text[:m.start()]) not in _OTHER_SPACE:
out["notes"].add(int(m.group(1)))
return out
# How many references one resolve call answers. A long plan cites a few dozen;
# past this the caller is listing, not rendering, and gets a 400 at the door.
RESOLVE_LIMIT = 200
async def resolve_refs(
user_id: int,
*,
notes: Iterable[int] = (),
milestones: Iterable[int] = (),
rules: Iterable[int] = (),
) -> dict[str, dict[int, dict]]:
"""What each referenced id IS, for the records this user may read.
An id that is missing, trashed or not readable is simply absent, and the
caller shows it as a reference that leads nowhere. The answer never says
which of the three it was: "not shared with you" and "does not exist" must
read the same, or the resolver becomes a way to probe other people's ids.
No pull is recorded. Hovering a link is not choosing to read the record;
the view it opens records that, the same as any other way of arriving.
"""
from grimoire.models.milestone import Milestone
from grimoire.services import rulebooks as rulebooks_svc
from grimoire.services.access import can_read_project, readable_notes_clause
out: dict[str, dict[int, dict]] = {"notes": {}, "milestones": {}, "rules": {}}
note_ids = sorted({int(i) for i in notes})
milestone_ids = sorted({int(i) for i in milestones})
rule_ids = sorted({int(i) for i in rules})
async with async_session() as session:
if note_ids:
rows = (await session.execute(
select(Note).where(
Note.id.in_(note_ids),
Note.deleted_at.is_(None),
readable_notes_clause(user_id),
)
)).scalars().all()
for n in rows:
out["notes"][n.id] = {
"id": n.id,
"title": n.title or "",
"is_task": n.is_task,
"note_type": n.note_type or "note",
"status": n.status,
"task_kind": n.task_kind if n.is_task else None,
}
if milestone_ids:
rows = (await session.execute(
select(Milestone).where(
Milestone.id.in_(milestone_ids), Milestone.deleted_at.is_(None),
)
)).scalars().all()
readable_projects: dict[int, bool] = {}
for ms in rows:
if ms.user_id != user_id:
pid = ms.project_id
if pid is None:
continue
if pid not in readable_projects:
readable_projects[pid] = await can_read_project(user_id, pid)
if not readable_projects[pid]:
continue
out["milestones"][ms.id] = {
"id": ms.id,
"title": ms.title or "",
"project_id": ms.project_id,
"status": ms.status,
}
# One lookup per rule: readability runs through rulebook ownership and
# project ownership, which `get_rule` already resolves. A body names a few.
for rid in rule_ids:
rule = await rulebooks_svc.get_rule(rid, user_id)
if rule is not None:
out["rules"][rule.id] = {
"id": rule.id,
"title": rule.title or "",
"kind": getattr(rule, "kind", None) or "rule",
}
return out
def _next_word(after: str) -> str:
m = _NEXT_WORD_RE.match(after)
return m.group(1).lower() if m else ""
+70 -2
View File
@@ -35,6 +35,7 @@ import time
from dataclasses import dataclass, field
from typing import Any, Callable
from grimoire.services import rule_order
from grimoire.services.lessons import LESSON_NOTE_TYPE, claim_line
logger = logging.getLogger(__name__)
@@ -576,6 +577,12 @@ class RuleIO:
record_retrieval: Callable[..., Any]
record_rule_surfaced: Callable[..., Any]
history: Callable[..., Any] | None = None
"""`rule_deliveries.history`: `{rule_id: open rate}` for (rule, at) pairs.
None leaves every rule's history unknown."""
record_delivery: Callable[..., Any] | None = None
"""`rule_deliveries.record`: each line shown, against the session the
door bound. None records nothing."""
@dataclass(frozen=True)
@@ -773,6 +780,30 @@ async def _reserve_slot_for_preference(
# ── The pipeline ─────────────────────────────────────────────────────────
def _record_delivery(io, moment: RuleMoment, source: str, shown: list[tuple[int, str, bool]]) -> None:
"""Record each line shown — `(rule_id, at, was_a_repeat)` — as a delivery."""
if io.record_delivery is None or not shown:
return
try:
io.record_delivery(moment.user_id, None, source, [
(rid, at, "repeat" if repeat else "full") for rid, at, repeat in shown
])
except Exception: # noqa: BLE001 - observation never breaks the observed
_telemetry_failed(source)
async def _history(io, moment: RuleMoment, pairs: list[tuple[int, str]]) -> dict[int, float]:
"""Each rule's open rate where it is about to be delivered; {} when the
door has no history to read or the read fails — unknown, never an error."""
if io.history is None or not pairs:
return {}
try:
return await io.history(moment.user_id, pairs) or {}
except Exception: # noqa: BLE001 - history orders lines, it never withholds them
logger.debug("rule delivery history unreadable", exc_info=True)
return {}
async def run_rule_arm(
arm: RuleArm, moment: RuleMoment, *, floor: float, budget: int, io: RuleIO,
checkpoint_floor: float = 0.0,
@@ -801,6 +832,19 @@ async def run_rule_arm(
# still has something to say, it just says it differently.
if not shown:
return RuleResult()
# Into the one delivery order: a rule that holds outranks one that
# informs whatever their scores, and score breaks the last tie.
history = await _history(io, moment, [(rule.id, arm.source) for _s, rule in shown])
shown = [
c.extra for c in rule_order.ordered(
rule_order.Candidate(
rule=rule, specificity=rule_order.BY_RESEMBLANCE,
opened_rate=history.get(rule.id), similarity=score,
seen=rule.id in moment.exclude, extra=(score, rule),
)
for score, rule in shown
)
]
lines = [
_rule_hint_line(
@@ -836,6 +880,11 @@ async def run_rule_arm(
)
except Exception: # noqa: BLE001 - observation never breaks the observed
_telemetry_failed(source)
# A stop-only arm shows its lines to nobody: only a hold speaks.
if not arm.stop_only:
_record_delivery(io, moment, source, [
(rule.id, source, rule.id in moment.exclude) for _s, rule in shown
])
return RuleResult(
lines=lines, rule_ids=rule_ids,
shown_rule_ids=[rule.id for _score, rule in shown],
@@ -1597,6 +1646,10 @@ class MomentIO:
"""`rulebooks.rules_on_moments`, or a stand-in with its signature."""
record_rule_surfaced: Callable[..., Any]
history: Callable[..., Any] | None = None
"""As on `RuleIO`."""
record_delivery: Callable[..., Any] | None = None
"""As on `RuleIO`."""
def _reached_by(hit: dict) -> str:
@@ -1626,8 +1679,20 @@ async def run_moment_arm(
if not pairs:
return RuleResult()
by_moment = {hit["moment"]: hit for hit in reached}
# Stable: catalog order within each half, fresh half first.
shown = sorted(pairs, key=lambda pair: pair[0].id in moment.exclude)[:limit]
# The one delivery order (services/rule_order.py), then the cap — so
# what a crowded moment drops is the lowest-ranked, not the last
# mounted. Ties keep catalog order.
history = await _history(io, moment, [(rule.id, at) for rule, at in pairs])
shown = [
c.extra for c in rule_order.ordered(
rule_order.Candidate(
rule=rule, specificity=rule_order.BY_MOUNT,
opened_rate=history.get(rule.id),
seen=rule.id in moment.exclude, extra=(rule, at),
)
for rule, at in pairs
)
][:limit]
lines = []
for rule, at in shown:
@@ -1651,6 +1716,9 @@ async def run_moment_arm(
)
except Exception: # noqa: BLE001 - observation never breaks the observed
_telemetry_failed(MOMENT_RULE_SOURCE)
_record_delivery(io, moment, MOMENT_RULE_SOURCE, [
(rule.id, at, rule.id in moment.exclude) for rule, at in shown
])
return RuleResult(
lines=lines, rule_ids=rule_ids,
shown_rule_ids=[rule.id for rule, _at in shown],
+180
View File
@@ -0,0 +1,180 @@
"""Each rule line a session is shown, whether it was opened after, and what
that history says about where a rule is worth delivering.
Three calls, one table (`rule_deliveries`):
- `record` — fire-and-forget, from the plugin doors that know the session:
every line an arm put in front of it, full or repeat.
- `mark_opened` — the session opened a rule: the latest unopened delivery of
it in that session gets the stamp. An open with no delivery behind it (the
agent looked a rule up unprompted) stamps nothing.
- `history` — for the ordering function: each rule's smoothed open rate at
the place it is about to be delivered, over the last `HISTORY_DAYS`.
Deliveries are kept `RETAIN_DAYS` and pruned daily: enough history to rank on
and to read adherence from, without a row per tool call accumulating forever.
"""
from __future__ import annotations
import logging
import re
from contextvars import ContextVar
from datetime import datetime, timedelta, timezone
from sqlalchemy import and_, case, delete, func, select, tuple_, update
from grimoire.models import async_session
from grimoire.models.rule_delivery import FORMS, FULL, RuleDelivery
from grimoire.services import rule_order
from grimoire.services.background import spawn
logger = logging.getLogger(__name__)
HISTORY_DAYS = 90
RETAIN_DAYS = 180
# An open counts against a delivery made within this window before it; an
# older one was read by a context that is long gone.
OPEN_WINDOW = timedelta(hours=6)
_SESSION_MAX = 200
_UNSAFE = re.compile(r"[^A-Za-z0-9._-]")
# The session a plugin request is delivering to, bound once per request by the
# plugin routes so the arms several calls deep record against it without every
# signature between carrying it. Unbound (the MCP door, a test) records nothing.
_session: ContextVar[str] = ContextVar("rule_delivery_session", default="")
def bind_session(session_id: str | None) -> None:
_session.set(_clean_session(session_id))
def bound() -> bool:
"""Whether this request delivers to a known session — the doors that
record deliveries are the ones that read their history back."""
return bool(_session.get())
def _clean_session(session_id: str | None) -> str:
# The plugin's own filename-safe form of the id, so a hook that sends the
# raw id and one that sends the safe one name the same session.
return _UNSAFE.sub("_", (session_id or "").strip())[:_SESSION_MAX]
def record(
user_id: int, session_id: str | None, source: str,
lines: list[tuple[int, str, str]],
) -> None:
"""Record delivered lines: `(rule_id, at, form)` each. Fire-and-forget,
and a no-op without a session, since an open could never be tied back.
`session_id` None means the one bound for this request."""
sid = _clean_session(_session.get() if session_id is None else session_id)
if not sid or not lines:
return
try:
rows = [
{"user_id": int(user_id), "session_id": sid, "rule_id": int(rid),
"source": source, "at": str(at or source), "form": form if form in FORMS else FULL}
for rid, at, form in lines
]
except Exception: # noqa: BLE001 - observation never breaks the observed
logger.debug("rule delivery payload build failed", exc_info=True)
return
spawn(_insert(rows), site="rule_delivery_write")
async def _insert(rows: list[dict]) -> None:
async with async_session() as session:
session.add_all(RuleDelivery(**row) for row in rows)
await session.commit()
async def mark_opened(user_id: int, session_id: str | None, rule_id: int) -> bool:
"""Stamp the latest unopened delivery of this rule in this session.
Returns whether a delivery was stamped. Only that one: a rule delivered
five times and opened once was opened after the fifth line, and the four
before it were passed over.
"""
sid = _clean_session(session_id)
if not sid or not rule_id:
return False
now = datetime.now(timezone.utc)
async with async_session() as session:
latest = (await session.execute(
select(RuleDelivery.id)
.where(
RuleDelivery.user_id == user_id,
RuleDelivery.session_id == sid,
RuleDelivery.rule_id == rule_id,
RuleDelivery.opened_at.is_(None),
RuleDelivery.delivered_at >= now - OPEN_WINDOW,
)
.order_by(RuleDelivery.delivered_at.desc(), RuleDelivery.id.desc())
.limit(1)
)).scalar_one_or_none()
if latest is None:
return False
await session.execute(
update(RuleDelivery).where(RuleDelivery.id == latest).values(opened_at=now)
)
await session.commit()
return True
async def history(user_id: int, pairs: list[tuple[int, str]]) -> dict[int, float]:
"""`{rule_id: smoothed open rate}` at each pair's place, for this user.
A rule with no delivery there is left out, which the ordering reads as
unknown rather than as never opened.
"""
wanted = list(dict.fromkeys((int(rid), str(at)) for rid, at in pairs))
if not wanted:
return {}
since = datetime.now(timezone.utc) - timedelta(days=HISTORY_DAYS)
async with async_session() as session:
rows = (await session.execute(
select(
RuleDelivery.rule_id, RuleDelivery.at,
func.count(RuleDelivery.id),
func.sum(case((RuleDelivery.opened_at.is_not(None), 1), else_=0)),
)
.where(
RuleDelivery.user_id == user_id,
RuleDelivery.delivered_at >= since,
tuple_(RuleDelivery.rule_id, RuleDelivery.at).in_(wanted),
)
.group_by(RuleDelivery.rule_id, RuleDelivery.at)
)).all()
return {
int(rid): rule_order.opened_rate(int(delivered), int(opened or 0))
for rid, _at, delivered, opened in rows
}
async def prune(retain_days: int = RETAIN_DAYS) -> int:
cutoff = datetime.now(timezone.utc) - timedelta(days=retain_days)
async with async_session() as session:
result = await session.execute(
delete(RuleDelivery).where(and_(RuleDelivery.delivered_at < cutoff))
)
await session.commit()
return int(result.rowcount or 0)
_prune_task = None
async def _prune_tick() -> None:
try:
removed = await prune()
if removed:
logger.info("Rule delivery retention: deleted %d row(s)", removed)
except Exception:
logger.exception("Rule delivery retention failed")
def start_prune_loop() -> None:
global _prune_task
if _prune_task is None or _prune_task.done():
from grimoire.services.background import start_periodic
_prune_task = start_periodic(86400, _prune_tick, label="rule_delivery_retention") # daily
+80 -17
View File
@@ -43,7 +43,7 @@ from __future__ import annotations
import logging
from datetime import datetime, timezone
from sqlalchemy import exists, func, not_, select
from sqlalchemy import exists, func, not_, or_, select
from sqlalchemy.exc import IntegrityError
from grimoire.models import async_session
@@ -274,6 +274,11 @@ async def pending(user_id: int, rule_id: int | None = None, limit: int = 200) ->
Each rule carries what it is mounted on now, so a proposal is read beside
the mounts it would add to.
A signal pair is a proposal only once it has crossed the bar and asked
(`proposed_at` in its evidence). Below the bar it is a row gathering
evidence, and listing it would bury the few pairs the signal stands
behind under every rule that was once opened after a moment.
"""
from grimoire.services.rulebooks import _owned_rules_clause
@@ -282,7 +287,13 @@ async def pending(user_id: int, rule_id: int | None = None, limit: int = 200) ->
stmt = (
select(RuleMomentJudgment, Rule)
.join(Rule, Rule.id == RuleMomentJudgment.rule_id)
.where(RuleMomentJudgment.state == SUGGESTED, _owned_rules_clause(user_id))
.where(
RuleMomentJudgment.state == SUGGESTED, _owned_rules_clause(user_id),
or_(
RuleMomentJudgment.source != "signal",
RuleMomentJudgment.evidence["proposed_at"].astext.isnot(None),
),
)
)
if rule_id:
stmt = stmt.where(Rule.id == int(rule_id))
@@ -483,17 +494,50 @@ def _keep(row: RuleMomentJudgment, note: str, now: datetime) -> None:
# ── The signal ───────────────────────────────────────────────────────────────
# How many distinct actions a signal pair remembers as having reached its
# moment. Enough to show the operator what the opens followed.
_SIGNAL_ACTIONS_CAP = 5
def _reached_phrase(evidence: dict) -> str:
reached = (evidence or {}).get("reached_by") or {}
if not isinstance(reached, dict) or not reached:
return ""
top = sorted(reached.items(), key=lambda kv: (-int(kv[1] or 0), kv[0]))[:3]
return " (reached by " + ", ".join(f"`{match}`" for match, _n in top) + ")"
def _signal_note(moment: str, evidence: dict) -> str:
"""The `why` a signal proposal shows the operator: what the opens followed."""
counts = lesson_rules.evidence_summary(evidence)
return (
f"Opened just after `{moment}`{_reached_phrase(evidence)} in "
f"{counts['situations']} distinct sessions, each time without a hook having "
f"shown the rule first. Co-occurrence only: confirm it if the rule governs "
f"that point in the work whatever the work is about."
)
def _proposal_line(rule: Rule, moment: str, evidence: dict) -> str:
"""The line an open past the bar returns to the session.
It says what the evidence is, and makes offering it conditional on the
reader's own reading: a session relays an unqualified "offer this" as a
recommendation, and co-occurrence is not one.
"""
counts = lesson_rules.evidence_summary(evidence)
kind = rule.kind or "rule"
return (
f"> {kind.capitalize()} #{rule.id} \"{rule.title}\" has been opened just after "
f"`{moment}` in {counts['situations']} distinct sessions — it may belong on "
f"that moment, where it would arrive without being searched for. Offer the "
f"operator the mount in one line; on their yes, `judge_rule_moments("
f"[{{\"rule_id\": {rule.id}, \"moment\": \"{moment}\", \"verdict\": \"confirm\", "
f"\"note\": \"why\"}}])` mounts it; on a no, `\"reject\"` with their why stops "
f"the asking."
f"> {kind.capitalize()} #{rule.id} \"{rule.title}\" was opened just after "
f"`{moment}`{_reached_phrase(evidence)} in {counts['situations']} distinct "
f"sessions, each time without a hook having shown it first. That is "
f"co-occurrence, not a recommendation. Read the {kind}'s trigger against what "
f"`{moment}` means (`list_moments`): only if the {kind} governs that point in "
f"the work whatever the work is about, ask the operator whether to mount it, "
f"with your reason; if it is about a subject, leave it. On their yes, "
f"`judge_rule_moments([{{\"rule_id\": {rule.id}, \"moment\": \"{moment}\", "
f"\"verdict\": \"confirm\", \"note\": \"why\"}}])` mounts it; on a no, "
f"`\"reject\"` with their why stops the asking."
)
@@ -510,24 +554,39 @@ def signal_moments(moments) -> list[str]:
async def co_occurred(
user_id: int, rule_id: int, moments, *, situation: str,
project_id: int | None = None,
project_id: int | None = None, reached: dict | None = None,
) -> str:
"""Record that a rule was opened shortly after these moments fired, and
return a proposal line once a (rule, moment) pair has earned one.
`situation` is what makes two opens distinct — the session, so a rule
opened after every push in one long session counts once. A pair already
mounted or judged gathers nothing. One proposal per open at most. Fails
open: this rides a hook, and bookkeeping must never break the read.
judged gathers nothing, and neither does a rule already mounted anywhere:
it arrives by lookup at its own moments, so an open of it is far likelier
to follow that delivery than to reveal a missing moment. `reached` maps a
moment to the action that reached it, kept as the proposal's evidence.
One proposal per open at most. Fails open: this rides a hook, and
bookkeeping must never break the read.
"""
try:
return await _co_occurred(user_id, rule_id, moments, situation, project_id)
return await _co_occurred(user_id, rule_id, moments, situation, project_id,
reached or {})
except Exception:
logger.warning("rule/moment co-occurrence could not be recorded", exc_info=True)
return ""
async def _co_occurred(user_id, rule_id, moments, situation, project_id) -> str:
def _add_reached(evidence: dict, match: str) -> dict:
"""`evidence` with one more open counted against the action that reached
the moment, keeping at most _SIGNAL_ACTIONS_CAP distinct actions."""
reached = dict(evidence.get("reached_by") or {})
match = (match or "").strip()[:80]
if match and (match in reached or len(reached) < _SIGNAL_ACTIONS_CAP):
reached[match] = int(reached.get(match) or 0) + 1
return {**evidence, "reached_by": reached}
async def _co_occurred(user_id, rule_id, moments, situation, project_id, reached) -> str:
wanted = signal_moments(moments)
key = lesson_rules.situation_key("s", situation)
rid = _int(rule_id)
@@ -540,11 +599,10 @@ async def _co_occurred(user_id, rule_id, moments, situation, project_id) -> str:
rule = owned.get(rid)
if rule is None:
return ""
mounted = (await _mounts(session, [rid])).get(rid, set())
if (await _mounts(session, [rid])).get(rid):
return ""
existing = await _rows(session, [rid])
for moment in wanted:
if moment in mounted:
continue
row = existing.get((rid, moment))
if row is not None and row.state != SUGGESTED:
continue
@@ -552,11 +610,13 @@ async def _co_occurred(user_id, rule_id, moments, situation, project_id) -> str:
row = RuleMomentJudgment(rule_id=rid, moment=moment, state=SUGGESTED, source="signal")
session.add(row)
ev = lesson_rules.add_evidence(row.evidence, key, project_id, now)
ev = _add_reached(ev, reached.get(moment, ""))
if proposal is None and lesson_rules.proposal_due(ev, now):
ev["proposed_at"] = now.isoformat()
ev["proposed_count"] = int(ev.get("proposed_count") or 0) + 1
proposal = (moment, ev)
row.evidence = ev
row.note = _signal_note(moment, ev)
try:
await session.commit()
except IntegrityError:
@@ -588,6 +648,7 @@ async def opened_after(
from grimoire.services.moment_actions import moments_for
reached: list[str] = []
reached_by: dict[str, str] = {}
for act in list(acts or [])[:_ACTS_CAP]:
if not isinstance(act, dict):
continue
@@ -604,11 +665,13 @@ async def opened_after(
name = hit.get("moment") if isinstance(hit, dict) else None
if name and name not in reached:
reached.append(name)
reached_by[name] = str(hit.get("match") or tool)
moments = signal_moments(reached)
context = ""
if moments and (session_id or "").strip():
context = await co_occurred(
user_id, rule_id, moments, situation=session_id.strip(), project_id=project_id,
reached=reached_by,
)
return {"moments": moments, "context": context}
+80
View File
@@ -0,0 +1,80 @@
"""The one order in which rules reach a moment.
Every arm that puts rules in front of a session — the rules mounted on a
moment, the rules a typed trigger matched, the rules a semantic search found —
ranks what it has the same way, so a crowded moment drops the same rules
whichever arm brought them:
1. **enforcement** — `enforce`, then `hold`, then `inform`. A rule that stops
the work is never the one cut to make room for a line beside it.
2. **salience** — `high`, `normal`, `low`, as the rule's author declared it.
3. **specificity** — how narrowly the rule was reached. A trigger that named
this command or this path says more than a mount on the whole moment, and a
mount says more than a resemblance.
4. **news** — at the same rank, a rule this session has not been shown yet
comes before one it has, so a cap cuts a reminder rather than a first
mention.
5. **history** — how often this rule was opened when delivered at this
moment before. A rule sessions keep opening here outranks one they keep
passing over.
6. **similarity** — the search score, when there is one. Last, because it is
the one signal that says what the work resembles rather than what it is.
Each key is a declared or recorded fact, read in that order, so the outcome
can be explained line by line: "it outranked that one because it holds".
"""
from __future__ import annotations
from collections.abc import Iterable
from dataclasses import dataclass
from typing import Any
ENFORCEMENT_RANK = {"enforce": 0, "hold": 1, "inform": 2}
SALIENCE_RANK = {"high": 0, "normal": 1, "low": 2}
# How narrowly a rule was reached, larger is narrower.
BY_RESEMBLANCE = 0
BY_MOUNT = 1
BY_TRIGGER = 2
# A rule with no delivery history at a moment ranks as if half its deliveries
# there were opened: unknown is neither proof of use nor of neglect.
UNKNOWN_HISTORY = 0.5
@dataclass(frozen=True)
class Candidate:
"""One rule an arm could deliver, with what it knows about how it got here."""
rule: Any
specificity: int = BY_RESEMBLANCE
opened_rate: float | None = None
"""Share of this rule's earlier deliveries at this moment that were opened."""
similarity: float | None = None
seen: bool = False
"""Already shown to this session."""
extra: Any = None
"""Whatever the arm needs back with the rule — the moment it was mounted
on, its score pair — carried through the sort untouched."""
def order_key(c: Candidate) -> tuple:
rule = c.rule
return (
ENFORCEMENT_RANK.get(getattr(rule, "enforcement", None) or "inform", 2),
SALIENCE_RANK.get(getattr(rule, "salience", None) or "normal", 1),
-c.specificity,
c.seen,
-(UNKNOWN_HISTORY if c.opened_rate is None else c.opened_rate),
-(c.similarity or 0.0),
)
def ordered(candidates: Iterable[Candidate]) -> list[Candidate]:
"""The candidates in delivery order. Stable: ties keep the arm's own order."""
return sorted(candidates, key=order_key)
def opened_rate(delivered: int, opened: int) -> float:
"""A smoothed open rate, so one delivery opened once does not read as certainty."""
return (opened + 1) / (delivered + 2)
+60 -3
View File
@@ -273,6 +273,38 @@ RELATION_KINDS = ("co_surfaces", "overrides", "elaborates")
# Migration 0098's CHECK. `rule` binds; `preference` is how the operator
# wants work done — see the model comment for why both live on one table.
KINDS = ("rule", "preference")
# Migration 0128's CHECKs, strongest first — the order the ordering function
# ranks them in (services/rule_order.py).
ENFORCEMENTS = ("enforce", "hold", "inform")
SALIENCES = ("high", "normal", "low")
def require_enforcement(enforcement: str | None, kind: str | None) -> str:
"""The enforcement a rule of this kind may carry, or a refusal naming the choices.
Unlike `kind`, an unknown enforcement is refused rather than mapped: there is no
safe direction to fall in. Mapped up, a typo turns a line into a stop;
mapped down, it turns a stop into a line. A preference is always `inform`
— it says how work is liked done, and a stop would claim a force it does
not have.
"""
clean = (enforcement or "inform").strip().lower()
if clean not in ENFORCEMENTS:
raise ValueError(f"enforcement must be one of {', '.join(ENFORCEMENTS)}, got {enforcement!r}")
if (kind or "rule") == "preference" and clean != "inform":
raise ValueError(
"a preference's enforcement is always `inform`: it says how work is liked "
"done, and holding or enforcing it would make it a rule. Record it "
"as a rule if it must stop the work."
)
return clean
def require_salience(salience: str | None) -> str:
clean = (salience or "normal").strip().lower()
if clean not in SALIENCES:
raise ValueError(f"salience must be one of {', '.join(SALIENCES)}, got {salience!r}")
return clean
# The rule columns that are nullable, and therefore the ones where EMPTY has
@@ -339,8 +371,14 @@ def rule_brief(rule: Rule, **extra) -> dict:
# one, and the assumption it would reach for — "this binds" — is the
# expensive one to get wrong in the other direction. Say it outright.
"kind": rule.kind or "rule",
# Unconditional for the same reason as `kind`: whether a rule stops
# the work is never something a reader should have to assume.
"enforcement": rule.enforcement or "inform",
"updated_at": rule.updated_at.date().isoformat() if rule.updated_at else None,
}
# Salience is attached only when the author raised or lowered it.
if (rule.salience or "normal") != "normal":
out["salience"] = rule.salience
# Attached only when present: never a null key that reads as a
# capability the record doesn't have.
if rule.when_to_apply:
@@ -506,8 +544,12 @@ async def create_rule(
why: str = "", how_to_apply: str = "", order_index: int = 0,
when_to_apply: str = "", arose_from_id: int = 0,
verify_with: str = "", expires_when: str = "", kind: str = "rule",
enforcement: str = "inform", salience: str = "normal",
) -> Rule:
_require_trigger(when_to_apply)
kind = _valid_kind(kind)
enforcement = require_enforcement(enforcement, kind)
salience = require_salience(salience)
async with async_session() as session:
await _assert_topic_owned(session, topic_id, user_id)
rule = Rule(
@@ -515,7 +557,7 @@ async def create_rule(
title=title,
statement=statement,
when_to_apply=when_to_apply or None,
kind=_valid_kind(kind),
kind=kind, enforcement=enforcement, salience=salience,
why=why or None,
how_to_apply=how_to_apply or None,
verify_with=verify_with or None,
@@ -535,6 +577,7 @@ async def create_project_rule(
why: str = "", how_to_apply: str = "", order_index: int = 0,
when_to_apply: str = "", arose_from_id: int = 0,
verify_with: str = "", expires_when: str = "", kind: str = "rule",
enforcement: str = "inform", salience: str = "normal",
) -> Rule:
"""Create a rule scoped to a single project (no rulebook ceremony).
@@ -544,6 +587,9 @@ async def create_project_rule(
constraint enforces exactly-one of (topic_id, project_id).
"""
_require_trigger(when_to_apply)
kind = _valid_kind(kind)
enforcement = require_enforcement(enforcement, kind)
salience = require_salience(salience)
async with async_session() as session:
await _assert_project_owned(session, project_id, user_id)
rule = Rule(
@@ -551,7 +597,7 @@ async def create_project_rule(
title=title,
statement=statement,
when_to_apply=when_to_apply or None,
kind=_valid_kind(kind),
kind=kind, enforcement=enforcement, salience=salience,
why=why or None,
how_to_apply=how_to_apply or None,
verify_with=verify_with or None,
@@ -691,7 +737,7 @@ async def update_rule(
allowed = {
"title", "statement", "why", "how_to_apply", "order_index",
"when_to_apply", "kind", "arose_from_id",
"verify_with", "expires_when",
"verify_with", "expires_when", "enforcement", "salience",
}
check_before = rule.verify_with
# A create-time guard is worth nothing if an edit can undo it, and
@@ -719,6 +765,11 @@ async def update_rule(
continue
if key == "kind":
value = _valid_kind(value)
elif key == "salience":
value = require_salience(value)
elif key == "enforcement":
# Checked against the kind after the loop, which may change it.
value = (value or "").strip().lower() or "inform"
elif key in NULLABLE_RULE_TEXT:
value = value or None
elif key == "arose_from_id":
@@ -731,6 +782,12 @@ async def update_rule(
# rule wrongly vouched for costs the thing the sweep exists to catch.
if rule.verify_with != check_before:
rule.verified_at = None
# A rule turned into a preference without naming an enforcement drops to
# `inform`, since a preference carries no other. Named explicitly
# alongside the new kind, a stronger enforcement is refused instead.
if rule.kind == "preference" and "enforcement" not in fields:
rule.enforcement = "inform"
rule.enforcement = require_enforcement(rule.enforcement, rule.kind)
if trigger_before and not (rule.when_to_apply or "").strip():
raise ValueError(
"when_to_apply cannot be cleared: it is how this rule arrives, "
+214 -31
View File
@@ -23,9 +23,10 @@ from __future__ import annotations
import difflib
import logging
import posixpath
import re
from datetime import datetime, timedelta, timezone
from typing import Iterable, NamedTuple
from typing import Iterable, Mapping, NamedTuple
from sqlalchemy import select
@@ -257,6 +258,46 @@ def _event(row: CodeShape, event: str, at: datetime, *, commit: str = "") -> Cod
)
async def provisional_row(
session, *, project_id: int, repo_key: str, path: str, symbol: str, kind: str,
) -> CodeShape:
"""The row for a shape a caller met before any live row for it existed:
a shape being written this turn, or one judged ahead of the sync.
The identity (project, repo, path, symbol, kind) is unique, so "no live
row" does not mean "no row". A VANISHED row under the identity is revived
and keeps its standing judgment, as a sync revives a shape that comes
back. The next sync then confirms it, or stamps it vanished again until
the code reaches the bound ref. With no row at all, a provisional one is
inserted inside a savepoint. If a concurrent request inserts the same
identity first, the savepoint rolls back and that request's row is used.
The caller's transaction survives either way.
"""
from sqlalchemy.exc import IntegrityError
def _same():
return select(CodeShape).where(
CodeShape.project_id == project_id, CodeShape.repo_key == repo_key,
CodeShape.path == path, CodeShape.symbol == symbol, CodeShape.kind == kind,
)
row = (await session.execute(_same())).scalars().first()
if row is None:
try:
async with session.begin_nested():
row = CodeShape(project_id=project_id, repo_key=repo_key,
path=path, symbol=symbol, kind=kind)
session.add(row)
await session.flush()
return row
except IntegrityError:
row = (await session.execute(_same())).scalars().one()
if row.vanished_at is not None:
row.vanished_at = None
session.add(_event(row, "reappeared", datetime.now(timezone.utc)))
return row
async def _judge(
session, row: CodeShape, *, status: str, snippet_id: int | None,
by: str | None, reason: str | None, at: datetime, reason_code: str | None = None,
@@ -320,6 +361,31 @@ async def record_uses(
return n
async def replace_reference_uses(
session, row: CodeShape, snippet_ids, *, evidence: str | None = None,
) -> int:
"""Make the row's mechanical `reference` edges exactly ``snippet_ids``.
`record_uses` only adds, so a by-name rule that tightens would otherwise
leave every edge the looser rule wrote. Only `reference` edges are
dropped: a judgment, or the write-path hook's evidence, outlives a
re-read of the body. Returns the number of edges written or refreshed."""
wanted = {int(x) for x in (snippet_ids or []) if x}
if row.id is not None:
stale = (
await session.execute(
select(CodeShapeUse).where(
CodeShapeUse.shape_id == row.id,
CodeShapeUse.basis == "reference",
)
)
).scalars().all()
for edge in stale:
if edge.snippet_id not in wanted:
await session.delete(edge)
return await record_uses(session, row, wanted, basis="reference", evidence=evidence)
async def uses_of(shape_ids) -> dict[int, list[CodeShapeUse]]:
"""{shape_id: [edges]} for a set of rows — the read side of record_uses."""
ids = [int(x) for x in shape_ids if x]
@@ -700,11 +766,10 @@ async def classify_shapes(
if not matches and repo_key and item.get("status") != "unclassified":
path = (item.get("path") or "").strip()
symbol = (item.get("symbol") or "").strip()
row = CodeShape(
project_id=project_id, repo_key=repo_key, path=path,
row = await provisional_row(
session, project_id=project_id, repo_key=repo_key, path=path,
symbol=symbol, kind=kind or snippet_kind(symbol, ""),
)
session.add(row)
by_key.setdefault((path, symbol), []).append(row)
matches = [row]
provisional += 1
@@ -1553,8 +1618,19 @@ async def suggest_write_path_instances(
continue
fields = snippet_fields(note)
symbol = fields.get("symbol") or ""
kind = snippet_kind(symbol, fields.get("language") or "")
if references_symbol(code, symbol, kind):
language = (fields.get("language") or "").strip().lower()
kind = snippet_kind(symbol, language)
canon = Canon(
int(sid), kind, symbol,
tuple(((loc.get("path") or ""), (loc.get("symbol") or ""))
for loc in fields.get("locations") or []),
"", "", int(note.project_id or 0), language,
)
# A redefinition of the pulled name in this payload is the copy the
# hint exists to catch, so the payload's own names are not "local".
if (kind != "sym" or same_family(path, language)) and names_canon(
kind, path, code, canon, project_id=project_id,
):
rank, why = 2, _REFERENCE_REASON.format(
sid=sid, symbol=_norm_symbol(symbol)
)
@@ -1618,13 +1694,13 @@ async def suggest_write_path_instances(
if row is None:
if not repo_key:
continue
row = CodeShape(
project_id=project_id, repo_key=repo_key,
# It may be a vanished row coming back, with its judgment.
row = await provisional_row(
session, project_id=project_id, repo_key=repo_key,
path=path, symbol=name, kind=kind,
)
session.add(row)
by_key[(name, kind)] = row
elif not (row.status in _MECHANICAL_TODO or row.classified_by == "hook"):
if not (row.status in _MECHANICAL_TODO or row.classified_by == "hook"):
continue # a judgment — or the canon itself — stands
# A proposal, never a status: the writer decides.
row.proposed_snippet_id = sid
@@ -1762,7 +1838,7 @@ def _semantic_priority(row) -> tuple:
# were examined under, so a tightened rule re-examines everything once. A
# change that does not alter what is proposed needs no bump. A stale "miss"
# basis on an old row is inert: a miss is not evidence (see _SEMANTIC_LIMIT).
_PROPOSER_VERSION = 6
_PROPOSER_VERSION = 9
# Signature resemblance floor, name blanked (difflib ratio) — and a length
# floor, because `def NAME():` resembles `def NAME(x):` at 0.95 while saying
# nothing; a family shape has parameters to resemble.
@@ -1805,6 +1881,13 @@ _FAMILY_BY_LANG = {
"css": "css", "scss": "css", "sass": "css", "less": "css",
"bash": "sh", "sh": "sh", "shell": "sh", "zsh": "sh",
"sql": "sql",
"go": "go", "golang": "go",
"rust": "rs", "rs": "rs",
"java": "jvm", "kotlin": "jvm", "kt": "jvm",
"swift": "swift", "dart": "dart",
"c": "c", "cpp": "c", "c++": "c", "h": "c",
"csharp": "cs", "c#": "cs", "cs": "cs",
"ruby": "rb", "rb": "rb", "php": "php",
}
_FAMILY_BY_EXT = {
".py": "py", ".pyi": "py",
@@ -1812,6 +1895,11 @@ _FAMILY_BY_EXT = {
".css": "css", ".scss": "css", ".sass": "css", ".less": "css",
".sh": "sh", ".bash": "sh", ".zsh": "sh",
".sql": "sql",
".go": "go", ".rs": "rs",
".java": "jvm", ".kt": "jvm", ".kts": "jvm",
".swift": "swift", ".dart": "dart",
".c": "c", ".h": "c", ".cc": "c", ".cpp": "c", ".hpp": "c",
".cs": "cs", ".rb": "rb", ".php": "php",
}
@@ -1877,10 +1965,79 @@ def text_contains(body: str, code: str) -> bool:
return a in b or b in a
def reference_canons(kind: str, path: str, symbol: str, body: str, canons: Iterable[Canon]) -> list[int]:
def _in_canon_home(canon: Canon, path: str) -> bool:
"""Is ``path`` in the canon's own package? A location that names a file
makes its directory home, exactly (a Go package is one directory); a
location that names a directory is home with everything under it."""
from grimoire.services.snippets import _path_touches
here = posixpath.dirname((path or "").strip("/"))
for lp, _ls in canon.locations:
lp = (lp or "").strip("/")
if not lp:
continue
if "." in lp.rsplit("/", 1)[-1]:
if posixpath.dirname(lp) == here:
return True
elif _path_touches(lp, path):
return True
return False
def names_canon(
kind: str, path: str, body: str, canon: Canon, *,
project_id: int = 0, defined_at: Mapping[str, frozenset[str]] | None = None,
) -> bool:
"""Does this body name THIS canon, rather than merely contain its word?
The by-name test behind the reference basis and every uses edge the
proposer writes. ``defined_at`` maps each name to the repo paths that
define it. A mention counts only when it can resolve to the canon:
- never across projects: one repo does not call a function defined in
another's, however alike the names are;
- never a name the file defines itself (a module's own `_run` helper),
unless the canon is recorded in this very file;
- when the repo also defines the name somewhere the canon is not
recorded (`sftpRun.file` beside the canon `importRun.file`), only from
the canon's own package: elsewhere the name says nothing about which
definition a call reaches;
- never a generic verb, with or without a leading underscore;
- a bare lowercase word (`file`, `seen`, `seal`) only where it is called
as `word(`, because as a plain word it is everyone's variable. No space
is allowed before the parenthesis: formatted code never has one, and
prose does ("a file (not a directory)").
Same kind and language family are checked by the callers' loops."""
sym = _norm_symbol(canon.symbol or "")
if not sym:
return False
if project_id and canon.project_id and canon.project_id != project_id:
return False
if sym.lstrip("_").lower() in _REFERENCE_STOPLIST:
return False
where = (defined_at or {}).get(sym, frozenset())
if where:
from grimoire.services.snippets import _path_touches
def at_canon(p: str) -> bool:
return any(lp and _path_touches(lp, p) for lp, _ls in canon.locations)
if path in where and not at_canon(path):
return False
if canon.locations and not all(at_canon(p) for p in where) \
and not _in_canon_home(canon, path):
return False
if kind == "sym" and re.fullmatch(r"[a-z]+", sym):
return re.search(rf"(?<![\w$]){re.escape(sym)}\(", body or "") is not None
return references_symbol(body, sym, kind)
def reference_canons(
kind: str, path: str, symbol: str, body: str, canons: Iterable[Canon], *,
project_id: int = 0, defined_at: Mapping[str, frozenset[str]] | None = None,
) -> list[int]:
"""Every canon this body NAMES — the uses edges the proposer can
write mechanically: same kind, same language family, symbol not in the
generic-verb stoplist, and not the shape's own name."""
write mechanically: same kind, same language family, not the shape's own
name, and named in the sense `names_canon` gives."""
norm_sym = _norm_symbol(symbol)
out: list[int] = []
for c in canons:
@@ -1890,9 +2047,7 @@ def reference_canons(kind: str, path: str, symbol: str, body: str, canons: Itera
continue
if _norm_symbol(c.symbol) == norm_sym:
continue
if _norm_symbol(c.symbol).lower() in _REFERENCE_STOPLIST:
continue
if references_symbol(body, c.symbol, kind):
if names_canon(kind, path, body, c, project_id=project_id, defined_at=defined_at):
out.append(c.snippet_id)
return out
@@ -1900,6 +2055,7 @@ def reference_canons(kind: str, path: str, symbol: str, body: str, canons: Itera
def match_canon(
kind: str, path: str, symbol: str, signature: str, body: str,
canons: Iterable[Canon], *, project_id: int = 0,
defined_at: Mapping[str, frozenset[str]] | None = None,
) -> tuple[int, str, float] | None:
"""The strongest (snippet_id, basis, score) a shape earns against the
canon catalog, by the non-semantic bases — or None. Strongest by
@@ -1924,11 +2080,7 @@ def match_canon(
if not any(location_covers(lp, ls, path, symbol) for lp, ls in c.locations):
offer("symbol", 1.0, c)
continue # its own location is canonical territory, not a proposal
if (
c.symbol
and _norm_symbol(c.symbol).lower() not in _REFERENCE_STOPLIST
and references_symbol(body, c.symbol, kind)
):
if names_canon(kind, path, body, c, project_id=project_id, defined_at=defined_at):
offer("reference", 0.9, c)
if c.code_norm and text_contains(body, c.code_norm):
offer("text", 0.95, c)
@@ -2064,6 +2216,14 @@ async def propose_for_repo(
if canons is None:
canons = await canon_catalog(user_id)
by_key = {(d[0], d[1], d[2]): d for d in definitions}
# Where the repo defines each name: a mention resolves to the definition
# in its own file, and a name defined in several packages only from the
# canon's own (see names_canon).
paths_by_name: dict[str, set[str]] = {}
for d in definitions:
if d[1] == "sym":
paths_by_name.setdefault(_norm_symbol(d[2]), set()).add(d[0])
defined_at = {n: frozenset(p) for n, p in paths_by_name.items()}
# The semantic arm is the widest net and, across projects, is noise: it
# is held to the shape's own project and language family. The precise
# bases (symbol/text) still reach family canon in other projects.
@@ -2107,10 +2267,10 @@ async def propose_for_repo(
# are a fact about the body, judged or not: the consumer map
# of a canon must include the call sites someone already
# classified. Mark it examined so the scan runs once per body.
used = reference_canons(row.kind, row.path, row.symbol, body, canons)
if used:
await record_uses(session, row, used, basis="reference",
evidence="proposer: body names the canon's symbol")
used = reference_canons(row.kind, row.path, row.symbol, body, canons,
project_id=project_id, defined_at=defined_at)
await replace_reference_uses(session, row, used,
evidence="proposer: body names the canon's symbol")
row.proposed_at = now
row.proposed_sha = examined_as
continue
@@ -2118,7 +2278,7 @@ async def propose_for_repo(
group = row.proposal_group # derive grouping is reassigned below
hit = match_canon(
row.kind, row.path, row.symbol, signature, body, canons,
project_id=project_id,
project_id=project_id, defined_at=defined_at,
)
_clear_proposal(row)
row.proposal_group = group
@@ -2126,10 +2286,10 @@ async def propose_for_repo(
row.proposed_sha = examined_as
# Consumption is recorded for every canon the body names,
# whatever the row is then judged to be.
used = reference_canons(row.kind, row.path, row.symbol, body, canons)
if used:
await record_uses(session, row, used, basis="reference",
evidence="proposer: body names the canon's symbol")
used = reference_canons(row.kind, row.path, row.symbol, body, canons,
project_id=project_id, defined_at=defined_at)
await replace_reference_uses(session, row, used,
evidence="proposer: body names the canon's symbol")
if hit:
row.proposed_snippet_id, row.proposal_basis, row.proposal_score = hit
row.proposal_group = None
@@ -2706,6 +2866,29 @@ async def write_time_derive(
return out
async def new_shapes_at(
project_id: int, path: str, shapes: list[tuple[str, str]]
) -> list[tuple[str, str]]:
"""The (kind, name) shapes the hook named at ``path`` that the ledger has
no live row for there — definitions this write introduces, as opposed to
ones it edits inside. Order follows ``shapes``."""
wanted = [(k, n) for k, n in shapes if n]
if not wanted:
return []
async with async_session() as session:
rows = (
await session.execute(
select(CodeShape.kind, CodeShape.symbol).where(
CodeShape.project_id == project_id,
CodeShape.path == path,
CodeShape.vanished_at.is_(None),
)
)
).all()
here = {(k, _norm_symbol(s)) for k, s in rows}
return [(k, n) for k, n in wanted if (k, _norm_symbol(n)) not in here]
async def flag_divergence(project_id: int, *, since: datetime | None) -> int:
"""Flag shapes created after ``since`` (the previous refresh) that sit
where a canon dominates and were not proposed as that canon. With no
+338
View File
@@ -0,0 +1,338 @@
"""Which project a write lands in, so a session can be held to its own.
A Claude Code session belongs to one project: the one its starting directory
is bound to. Toward any other project it may read anything and file an issue,
and every other write waits for the operator. The plugin's PreToolUse hook
enforces that, because only the hook knows which session is acting: the MCP
endpoint is stateless and sees nothing but the caller's key. This module
answers the hook's one question: given the session's project and a pending
act, which projects would the act change, and may it go ahead?
An act is either a directory (a file edit or a git command; the hook resolves
it to a repo or a `.grimoire` marker) or an MCP tool call. For a tool call,
`WRITE_TARGETS` says, for every write tool, which of its arguments locate the
write. That means the record or project the write changes, never one it only
mentions: `arose_from_id` on a new task points at another task without
changing it. tests/test_write_scope.py holds the table to the registered tools,
so a new write tool can't be added without saying where it writes.
"""
from __future__ import annotations
from sqlalchemy import or_, select
# How an argument locates the project a write lands in.
PROJECT = "project" # a project id
NOTE = "note" # a task, note, lesson, snippet or process: its project
MILESTONE = "milestone" # a milestone: its project
SYSTEM = "system" # a System: its project
RULE = "rule" # a project rule: its project. A global rule: none
RELATION = "relation" # a rule relation: the projects of its two rules
TRASH = "trash" # a deleted batch: every project its rows belong to
REPO = "repo" # a repo remote: the project it is bound to
DECISION = "decision" # a family decision: its project, else its idea's home
LOCATORS = frozenset({PROJECT, NOTE, MILESTONE, SYSTEM, RULE, RELATION, TRASH, REPO, DECISION})
# Every write tool, and the arguments that locate its write. An empty entry is
# a write that lands in no project:
# - install-level settings (moment mappings, retrieval dials);
# - user-level records (processes, design systems, rulebooks, topics, global
# rules and preferences);
# - judgments the system asks a session for in any project (a rule's outcome,
# a lesson-to-rule link, moment proposals, a menu verdict). Those describe how
# the corpus is retrieved; they don't change another project's work.
WRITE_TARGETS: dict[str, dict[str, str]] = {
# notes, tasks, planning
"create_note": {"project_id": PROJECT},
"update_note": {"note_id": NOTE, "project_id": PROJECT},
"delete_note": {"note_id": NOTE},
"mark_note_verified": {"note_id": NOTE},
"create_lesson": {"project_id": PROJECT},
"update_lesson": {"lesson_id": NOTE},
"delete_lesson": {"lesson_id": NOTE},
"judge_lesson_link": {},
"create_task": {"project_id": PROJECT, "milestone_id": MILESTONE, "parent_id": NOTE},
"update_task": {"task_id": NOTE, "project_id": PROJECT, "milestone_id": MILESTONE},
"delete_task": {"task_id": NOTE},
"add_task_log": {"task_id": NOTE},
"create_records": {"project_id": PROJECT, "milestone_id": MILESTONE},
"start_planning": {"project_id": PROJECT},
"create_milestone": {"project_id": PROJECT},
"update_milestone": {"milestone_id": MILESTONE, "project_id": PROJECT},
"delete_milestone": {"milestone_id": MILESTONE},
# projects, Systems, repos
"create_project": {},
"update_project": {"project_id": PROJECT},
"delete_project": {"project_id": PROJECT},
"decide_project_inception": {"project_id": PROJECT},
"set_project_platforms": {"project_id": PROJECT},
"create_system": {"project_id": PROJECT},
"update_system": {"system_id": SYSTEM},
"delete_system": {"system_id": SYSTEM},
"map_system_to_canonical": {"system_id": SYSTEM},
# Binding a repo changes the project it's bound to and, when it was bound
# elsewhere, the project it leaves.
"bind_repo": {"project_id": PROJECT, "repo_url": REPO},
"unbind_repo": {"repo_url": REPO},
# family canon. An idea is a record in its home project; an adoption is a
# project's answer; a conflict is between the two projects it names.
"propose_family_idea": {"note_id": NOTE},
"promote_family_idea": {"note_id": NOTE},
"retire_family_idea": {"note_id": NOTE},
"revise_family_idea": {"note_id": NOTE},
"set_family_references": {"note_id": NOTE},
"set_family_topic": {"note_id": NOTE},
"undo_family_decision": {"decision_id": DECISION},
"assess_family_adoption": {"project_id": PROJECT},
"resolve_family_conflict": {"canon_project_id": PROJECT, "other_project_id": PROJECT},
# snippets, processes, the shape ledger
"create_snippet": {"project_id": PROJECT},
"update_snippet": {"snippet_id": NOTE, "project_id": PROJECT},
"delete_snippet": {"snippet_id": NOTE},
"verify_snippet": {"snippet_id": NOTE},
"merge_snippets": {"target_id": NOTE, "source_ids": NOTE},
"unmerge_snippet": {"survivor_id": NOTE, "source_id": NOTE},
"create_process": {},
"update_process": {"process_id": NOTE},
"delete_process": {"process_id": NOTE},
"classify_shapes": {"project_id": PROJECT},
"classify_shapes_by_rule": {"project_id": PROJECT},
"confirm_shape_proposals": {"project_id": PROJECT},
"refresh_pattern_coverage": {"project_id": PROJECT},
"move_path": {"project_id": PROJECT},
# design systems belong to their owner, not to a project; choosing one for
# a project is that project's write.
"create_design_system": {},
"update_design_system": {},
"delete_design_system": {},
"create_design_token": {},
"update_design_token": {},
"delete_design_token": {},
"set_project_design_system": {"project_id": PROJECT},
# rules
"create_rulebook": {},
"update_rulebook": {},
"delete_rulebook": {},
"create_topic": {},
"update_topic": {},
"delete_topic": {},
"create_rule": {},
"create_preference": {},
"create_project_rule": {"project_id": PROJECT},
"update_rule": {"rule_id": RULE},
"update_preference": {"rule_id": RULE},
"move_rule": {"rule_id": RULE, "project_id": PROJECT},
"delete_rule": {"rule_id": RULE},
"mark_rule_verified": {"rule_id": RULE},
"relate_rules": {"from_rule_id": RULE, "to_rule_id": RULE},
"unrelate_rules": {"relation_id": RELATION},
"rule_outcome": {},
# moments and retrieval: install-level, and judgments asked for anywhere
"tune_retrieval": {},
"migrate_retrieval_floor": {},
"map_action": {},
"unmap_action": {},
"propose_rule_moments": {},
"judge_rule_moments": {},
"rule_misfired": {},
"judge_menu": {},
# trash: a batch can hold rows from several projects
"restore": {"deleted_batch_id": TRASH},
"purge_trash": {"deleted_batch_id": TRASH},
}
# Argument names that would locate a write wherever they appear. The guard test
# requires every write tool parameter with one of these names to be declared
# above, or listed in REFERENCES below, so a tool that gains one can't write
# past the fence unnoticed.
LOCATOR_NAMES = frozenset({
"project_id", "task_id", "note_id", "lesson_id", "snippet_id", "process_id",
"milestone_id", "system_id", "rule_id", "deleted_batch_id",
})
# Arguments with a locating name that only point at a record, with why each one
# doesn't say where the write lands.
REFERENCES: dict[str, dict[str, str]] = {
"classify_shapes_by_rule": {
"snippet_id": "the canon the shapes are judged against; the rows written are project_id's",
},
"confirm_shape_proposals": {
"snippet_id": "narrows which proposals to confirm; the rows written are project_id's",
},
"judge_lesson_link": {
"lesson_id": "a judgment on a lesson-to-rule pairing the system asked for",
"rule_id": "a judgment on a lesson-to-rule pairing the system asked for",
},
"rule_outcome": {
"rule_id": "telemetry on what a rule changed in this session's own work",
},
"rule_misfired": {
"rule_id": "telemetry on a moment that fired a rule in this session",
"project_id": "the project the misfire happened in, recorded with the report",
},
}
# Tool-name prefixes the plugin's fence answers without asking the server: every
# tool named this way reads. tests/test_write_scope.py holds the hook's copy of
# this list equal to it, and holds every write tool to a name outside it.
READ_PREFIXES = (
"get_", "list_", "search", "find_", "enter_project", "what_might_apply",
"resolve_design_system",
)
# The one write a session may make in another project: filing an issue there,
# as a new open task outside any plan of theirs.
ISSUE_STATUSES = frozenset({"", "todo"})
def is_issue_filing(tool: str, args: dict) -> bool:
"""True for create_task(kind="issue") that opens a fresh, unplanned issue."""
if tool != "create_task":
return False
if str(args.get("kind") or "") != "issue":
return False
if str(args.get("status") or "") not in ISSUE_STATUSES:
return False
return not _positive_ints(args.get("milestone_id")) and not _positive_ints(args.get("parent_id"))
def _positive_ints(value) -> list[int]:
"""The ids an argument names. 0 and negative values mean "none" or "leave
unchanged" across the tools (update_task's project_id=-1 clears), so only
positive ids locate anything."""
values = value if isinstance(value, (list, tuple)) else [value]
out = []
for v in values:
try:
n = int(v)
except (TypeError, ValueError):
continue
if n > 0:
out.append(n)
return out
async def _projects_of(user_id: int, kind: str, value) -> set[int]:
"""The projects the argument `value` of locator `kind` lands in."""
from grimoire.models import async_session
from grimoire.models.family import FamilyDecision
from grimoire.models.milestone import Milestone
from grimoire.models.note import Note
from grimoire.models.rulebook import Rule, RuleRelation
from grimoire.models.system import System
from grimoire.services import repo_bindings
if kind == REPO:
found = await repo_bindings.resolve_project(user_id, str(value or ""))
return {found} if found else set()
if kind == TRASH:
batch = str(value or "").strip()
if not batch:
return set()
async with async_session() as session:
found: set[int] = set()
for model in (Note, Milestone, System, Rule):
rows = await session.execute(
select(model.project_id).where(model.deleted_batch_id == batch)
)
found.update(p for p in rows.scalars() if p)
return found
ids = _positive_ints(value)
if not ids:
return set()
if kind == PROJECT:
return set(ids)
async with async_session() as session:
if kind == RELATION:
rows = await session.execute(
select(Rule.project_id)
.join(RuleRelation, or_(RuleRelation.from_rule_id == Rule.id,
RuleRelation.to_rule_id == Rule.id))
.where(RuleRelation.id.in_(ids))
)
return {p for p in rows.scalars() if p}
if kind == DECISION:
rows = await session.execute(
select(FamilyDecision.project_id, Note.project_id)
.join(Note, Note.id == FamilyDecision.idea_id)
.where(FamilyDecision.id.in_(ids))
)
return {own or home for own, home in rows.all() if own or home}
model = {NOTE: Note, MILESTONE: Milestone, SYSTEM: System, RULE: Rule}[kind]
rows = await session.execute(select(model.project_id).where(model.id.in_(ids)))
return {p for p in rows.scalars() if p}
async def tool_targets(user_id: int, tool: str, args: dict) -> set[int]:
"""Every project the MCP call `tool(**args)` would change. Empty for a
read, a write that lands in no project, and a tool this server doesn't
have."""
found: set[int] = set()
for name, kind in WRITE_TARGETS.get(tool, {}).items():
if name in args:
found |= await _projects_of(user_id, kind, args[name])
return found
async def _titles(ids: list[int]) -> dict[int, str]:
from grimoire.models import async_session
from grimoire.models.project import Project
if not ids:
return {}
async with async_session() as session:
rows = await session.execute(select(Project.id, Project.title).where(Project.id.in_(ids)))
return {pid: title for pid, title in rows.all()}
def _named(project_id: int, titles: dict[int, str]) -> str:
title = titles.get(project_id)
return f"{title} (project {project_id})" if title else f"project {project_id}"
async def check_act(
user_id: int, session_project: int, *, tool: str = "", args: dict | None = None,
target_project: int = 0, act: str = "",
) -> dict:
"""May a session in `session_project` do this act?
The act is an MCP call (`tool` with `args`) or a directory already
resolved to `target_project`; `act` words it for the reason ("git push
in", "Editing a file in"). Returns:
- `allowed`: False when the act would change another project and isn't the
one cross-project write allowed;
- `targets`: the other projects, as {id, title};
- `issue`: the act is that allowed write, filing an issue;
- `reason`: what the operator reads in the prompt, and the session after.
A session with no project is held to nothing. A target the caller can't
read is left out: the write itself is refused there, so there is nothing
to ask about, and naming it would tell the caller where a record lives.
"""
from grimoire.services.access import can_read_project
args = args or {}
if tool:
landing = await tool_targets(user_id, tool, args)
else:
landing = {target_project} if target_project else set()
others = [
p for p in sorted(landing)
if p != session_project and await can_read_project(user_id, p)
]
if not session_project or not others:
return {"allowed": True, "targets": [], "issue": False, "reason": ""}
titles = await _titles([session_project, *others])
targets = [{"id": p, "title": titles.get(p, "")} for p in others]
if tool and is_issue_filing(tool, args):
return {"allowed": True, "targets": targets, "issue": True, "reason": ""}
there = ", ".join(_named(p, titles) for p in others)
what = act.strip() or (f"{tool} changes" if tool else "This changes")
first = others[0]
reason = (
f"This session belongs to {_named(session_project, titles)}. {what} {there}, "
f"a different project. From here, the one change to make there is filing an "
f"issue: create_task(project_id={first}, kind=\"issue\") with how it was found "
f"and the evidence. Approve only if this session should change {there} itself."
)
return {"allowed": False, "targets": targets, "issue": False, "reason": reason}
+6 -2
View File
@@ -1,11 +1,15 @@
import re
_CODE_FENCE_RE = re.compile(r"```[\s\S]*?```|`[^`\n]+`")
_TAG_RE = re.compile(r"(?<!\w)#([\w][\w-]*(?:/[\w][\w-]*)*)")
# A `#` token made only of digits is a record reference (`#3127` names note
# 3127, see services/record_refs.py), never a tag. Digits followed by more of a
# tag (`#2fa`, `#123-notes`) is still a tag. frontend/src/utils/tags.ts holds the
# same pattern.
_TAG_RE = re.compile(r"(?<!\w)#(?!\d+(?![\w/-]))([\w][\w-]*(?:/[\w][\w-]*)*)")
def extract_tags(body: str) -> list[str]:
"""Extract #tags from body text, ignoring code blocks."""
"""Extract #tags from body text, ignoring code blocks and record references."""
cleaned = _CODE_FENCE_RE.sub("", body)
tags = _TAG_RE.findall(cleaned)
return sorted(set(tags))
+3
View File
@@ -290,6 +290,9 @@ def fake_rule(**attrs) -> MagicMock:
# claim to carry a check and rule_brief would stamp a MagicMock date
# onto all of them. Most rules have none — that is the default here.
"verify_with": None, "expires_when": None, "verified_at": None,
# A MagicMock here would read as a declared enforcement and a raised
# salience on every stand-in; the defaults are what a new rule gets.
"enforcement": "inform", "salience": "normal",
"order_index": 0, "created_at": _now(), "updated_at": _now(),
}, attrs)
+17
View File
@@ -90,6 +90,23 @@ def test_after_write_names_what_bash_just_wrote_then_stays_quiet_until_the_next_
assert seen[0]["exclude_derive"] == ["dup:483a"]
assert set(seen[0]["shapes"][0].split(",")) == {"css:log-empty", "css:other"}
def test_after_write_records_every_definition_for_the_turn_but_queries_only_the_first_four_files(tmp_path):
"""The end-of-turn ledger hears every file and every definition a Bash call
wrote; the prior-art arms stay bounded to four files and twelve names."""
with http_sink(SINK_REPLY) as (port, seen):
env = _env(tmp_path, url=f"http://127.0.0.1:{port}")
repo = _repo(tmp_path, env)
for n in range(6):
body = "".join(f"def f{n}_{i:02d}():\n return {i}\n\n" for i in range(15))
(repo / f"gen{n}.py").write_text(body)
_run(repo, env, session="s-many")
ledger = (tmp_path / "grimoire-priorart" / "s-many.written.ids").read_text().splitlines()
assert len(ledger) == 6 * 15
assert "gen5.py\tsym\tf5_14" in ledger
assert len(seen) == 4
assert all(len(q["shapes"][0].split(",")) == 12 for q in seen)
def test_after_write_is_silent_where_it_has_nothing_to_say(tmp_path):
env = _env(tmp_path)
repo = _repo(tmp_path, env)
@@ -5,7 +5,8 @@ the real `restore_full_backup`.
The unit lane already shows the tar hands back the dict it was given. What
only this lane shows is that the dict it hands back is one the restore
accepts — every id remapped to the restored rows, nothing dropped — and that
the command-line restore refuses a database that already has accounts.
the command-line restore refuses, on a live instance, a backup that doesn't
record this instance as its source.
"""
import pytest
import pytest_asyncio
@@ -97,10 +98,11 @@ async def test_the_tar_restores_with_every_id_remapped(written):
assert note.status == "todo"
async def test_the_command_refuses_a_database_with_accounts(written):
"""The source user exists, so this database is not empty: the command
must stop before restoring anything."""
assert await run(written) == 3
async def test_the_command_refuses_a_backup_from_no_known_instance(written):
"""This database is live and the backup names no instance it came from,
so it can't be rolled back to: the command stops before restoring
anything, even with --yes."""
assert await run(written, yes=True) == 3
async with async_session() as s:
restored = (await s.execute(select(User).where(User.username == RESTORED))).scalars().all()
assert restored == []

Some files were not shown because too many files have changed in this diff Show More