attraverso 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +33 -6
- package/assets/migrations/0016_brave_squadron_sinister.sql +77 -0
- package/assets/migrations/meta/0016_snapshot.json +1844 -0
- package/assets/migrations/meta/_journal.json +7 -0
- package/lib/index.js +577 -18
- package/migrations/0016_brave_squadron_sinister.sql +77 -0
- package/migrations/meta/0016_snapshot.json +1844 -0
- package/migrations/meta/_journal.json +7 -0
- package/package.json +1 -1
- package/server.js +1037 -102
- package/viewer/assets/favicon-DAARTY8o.svg +24 -0
- package/viewer/assets/{index-t0yugwqv.js → index-BlJrlICb.js} +27 -20
- package/viewer/assets/index-D4LIwbZD.css +1 -0
- package/viewer/index.html +3 -3
- package/viewer/assets/favicon-BUxCK25s.svg +0 -13
- package/viewer/assets/index-CNwAsUDo.css +0 -1
package/server.js
CHANGED
|
@@ -8,7 +8,7 @@ import { appendFile, mkdir, readFile, readdir, rename, rm, stat, writeFile } fro
|
|
|
8
8
|
import { existsSync, readdirSync, watch } from "node:fs";
|
|
9
9
|
import { homedir } from "node:os";
|
|
10
10
|
import { createServer } from "node:http";
|
|
11
|
-
import { spawn } from "node:child_process";
|
|
11
|
+
import { execFile, spawn } from "node:child_process";
|
|
12
12
|
// \0rolldown/runtime.js
|
|
13
13
|
var __create = Object.create;
|
|
14
14
|
var __defProp = Object.defineProperty;
|
|
@@ -21963,7 +21963,7 @@ var StdioServerTransport = class {
|
|
|
21963
21963
|
};
|
|
21964
21964
|
// package.json
|
|
21965
21965
|
var name = "attraverso";
|
|
21966
|
-
var version$1 = "0.
|
|
21966
|
+
var version$1 = "0.7.0";
|
|
21967
21967
|
var description = "Durable, structured project memory that Claude reads and writes over MCP, stored as version-controlled YAML.";
|
|
21968
21968
|
var license = "Apache-2.0";
|
|
21969
21969
|
var repository = {
|
|
@@ -27562,6 +27562,7 @@ var schema_exports = /* @__PURE__ */ __exportAll({
|
|
|
27562
27562
|
projectNext: () => projectNext,
|
|
27563
27563
|
projects: () => projects,
|
|
27564
27564
|
scopedDependencies: () => scopedDependencies,
|
|
27565
|
+
sourceReferences: () => sourceReferences,
|
|
27565
27566
|
users: () => users
|
|
27566
27567
|
});
|
|
27567
27568
|
/**
|
|
@@ -27844,6 +27845,41 @@ var layoutPositions = pgTable("layout_positions", {
|
|
|
27844
27845
|
x: integer("x").notNull(),
|
|
27845
27846
|
y: integer("y").notNull()
|
|
27846
27847
|
}, (t) => [primaryKey({ columns: [t.projectId, t.node] })]);
|
|
27848
|
+
/**
|
|
27849
|
+
* Source references (`CTX-13`): where a claim in some prose came from. The text carries a pointer after the claim,
|
|
27850
|
+
* `[ref r7k2]`, and this table carries everything else - one row per *source*, the rows sharing a `key` making one
|
|
27851
|
+
* reference, so a claim gathers sources over time ("elevated whenever it has additional sources") without a
|
|
27852
|
+
* second table holding what they share. Text with no pointer is the agent's own reasoning, and has no row.
|
|
27853
|
+
*
|
|
27854
|
+
* - **The owner is an item or a context section**, exactly one, by foreign key, so deleting either cascades its
|
|
27855
|
+
* references away. Repeated on each of a reference's rows, and kept to one owner per key by the trigger rather
|
|
27856
|
+
* than an index, since several rows share a key.
|
|
27857
|
+
* - **`quoted_text` is the text this source vouched for when it was added**: a record of a moment, like an event
|
|
27858
|
+
* payload, never kept in sync, and how "text changed since" is told without storing a flag.
|
|
27859
|
+
* - **`source` is an open vocabulary**, like every other one here (`user`, `test`, `search`, `docs` today), validated
|
|
27860
|
+
* by the domain layer rather than a database enum.
|
|
27861
|
+
* - **Retired, never deleted**, so what a claim was once backed by stays legible.
|
|
27862
|
+
*
|
|
27863
|
+
* Not `references`: that is a reserved word in SQL.
|
|
27864
|
+
*/
|
|
27865
|
+
var sourceReferences = pgTable("source_references", {
|
|
27866
|
+
id: text$1("id").primaryKey().$defaultFn(uuidv7),
|
|
27867
|
+
projectId: text$1("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
|
|
27868
|
+
key: text$1("key").notNull(),
|
|
27869
|
+
itemId: text$1("item_id").references(() => items.id, { onDelete: "cascade" }),
|
|
27870
|
+
sectionId: text$1("section_id").references(() => contextSections.id, { onDelete: "cascade" }),
|
|
27871
|
+
source: text$1("source").notNull(),
|
|
27872
|
+
detail: text$1("detail").notNull(),
|
|
27873
|
+
quotedText: text$1("quoted_text").notNull(),
|
|
27874
|
+
actor: text$1("actor").notNull(),
|
|
27875
|
+
recordedAt: text$1("recorded_at").notNull().$defaultFn(timestamp),
|
|
27876
|
+
retiredAt: text$1("retired_at")
|
|
27877
|
+
}, (t) => [
|
|
27878
|
+
check("source_references_one_owner", sql`(${t.itemId} IS NULL) <> (${t.sectionId} IS NULL)`),
|
|
27879
|
+
index("source_references_project_key").on(t.projectId, t.key),
|
|
27880
|
+
index("source_references_item").on(t.itemId),
|
|
27881
|
+
index("source_references_section").on(t.sectionId)
|
|
27882
|
+
]);
|
|
27847
27883
|
var events = pgTable("events", {
|
|
27848
27884
|
id: text$1("id").primaryKey().$defaultFn(uuidv7),
|
|
27849
27885
|
projectId: text$1("project_id").references(() => projects.id, { onDelete: "cascade" }),
|
|
@@ -42866,6 +42902,8 @@ var _0013_kind_bloodscream_default = "CREATE TABLE \"scoped_dependencies\" (\n \
|
|
|
42866
42902
|
var _0014_past_chronomancer_default = "ALTER TABLE \"items\" ADD COLUMN \"start_on\" text;--> statement-breakpoint\nALTER TABLE \"items\" ADD COLUMN \"due_on\" text;--> statement-breakpoint\nCREATE INDEX \"items_project_due\" ON \"items\" USING btree (\"project_id\",\"due_on\");";
|
|
42867
42903
|
// src/db/migrations/0015_stormy_blindfold.sql?raw
|
|
42868
42904
|
var _0015_stormy_blindfold_default = "CREATE TABLE \"layout_positions\" (\n \"project_id\" text NOT NULL,\n \"node\" text NOT NULL,\n \"x\" integer NOT NULL,\n \"y\" integer NOT NULL,\n CONSTRAINT \"layout_positions_project_id_node_pk\" PRIMARY KEY(\"project_id\",\"node\")\n);\n--> statement-breakpoint\nALTER TABLE \"layout_positions\" ADD CONSTRAINT \"layout_positions_project_id_projects_id_fk\" FOREIGN KEY (\"project_id\") REFERENCES \"public\".\"projects\"(\"id\") ON DELETE cascade ON UPDATE no action;";
|
|
42905
|
+
// src/db/migrations/0016_brave_squadron_sinister.sql?raw
|
|
42906
|
+
var _0016_brave_squadron_sinister_default = "CREATE TABLE \"source_references\" (\n \"id\" text PRIMARY KEY NOT NULL,\n \"project_id\" text NOT NULL,\n \"key\" text NOT NULL,\n \"item_id\" text,\n \"section_id\" text,\n \"source\" text NOT NULL,\n \"detail\" text NOT NULL,\n \"quoted_text\" text NOT NULL,\n \"actor\" text NOT NULL,\n \"recorded_at\" text NOT NULL,\n \"retired_at\" text,\n CONSTRAINT \"source_references_one_owner\" CHECK ((\"source_references\".\"item_id\" IS NULL) <> (\"source_references\".\"section_id\" IS NULL))\n);\n--> statement-breakpoint\nALTER TABLE \"source_references\" ADD CONSTRAINT \"source_references_project_id_projects_id_fk\" FOREIGN KEY (\"project_id\") REFERENCES \"public\".\"projects\"(\"id\") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint\nALTER TABLE \"source_references\" ADD CONSTRAINT \"source_references_item_id_items_id_fk\" FOREIGN KEY (\"item_id\") REFERENCES \"public\".\"items\"(\"id\") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint\nALTER TABLE \"source_references\" ADD CONSTRAINT \"source_references_section_id_context_sections_id_fk\" FOREIGN KEY (\"section_id\") REFERENCES \"public\".\"context_sections\"(\"id\") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint\nCREATE INDEX \"source_references_project_key\" ON \"source_references\" USING btree (\"project_id\",\"key\");--> statement-breakpoint\nCREATE INDEX \"source_references_item\" ON \"source_references\" USING btree (\"item_id\");--> statement-breakpoint\nCREATE INDEX \"source_references_section\" ON \"source_references\" USING btree (\"section_id\");--> statement-breakpoint\n-- CTX-13: every live source reference's pointer is in its owner's text, and a key has one owner. Hand-written: a\n-- trigger is beyond what drizzle-kit generates. Deferred to commit, so a reference and its pointer can arrive in\n-- either order within one transaction. Each firing checks only the item, section or key that changed. Loading a\n-- plan file sets attraverso.loading_plan for its transaction and is let through: a hand edit that broke a\n-- pointer must still load (stale is a state a plan loads in, never a refusal to load), and apm:check reports it.\n-- A pointer is \"[ref key]\" or the expanded \"[ref key: ...]\", matched exactly so r7k2 never matches r7k29.\nCREATE FUNCTION \"source_references_check\"() RETURNS trigger LANGUAGE plpgsql AS $$\nDECLARE\n bad text;\nBEGIN\n IF current_setting('attraverso.loading_plan', true) = 'on' THEN\n RETURN NULL;\n END IF;\n IF TG_TABLE_NAME = 'items' THEN\n SELECT r.key INTO bad FROM source_references r JOIN items i ON i.id = r.item_id\n WHERE r.item_id = NEW.id AND r.retired_at IS NULL\n AND position('[ref ' || r.key || ']' IN coalesce(i.body, '')) = 0\n AND position('[ref ' || r.key || ':' IN coalesce(i.body, '')) = 0\n LIMIT 1;\n ELSIF TG_TABLE_NAME = 'context_sections' THEN\n SELECT r.key INTO bad FROM source_references r JOIN context_sections c ON c.id = r.section_id\n WHERE r.section_id = NEW.id AND r.retired_at IS NULL\n AND position('[ref ' || r.key || ']' IN c.content) = 0\n AND position('[ref ' || r.key || ':' IN c.content) = 0\n LIMIT 1;\n ELSE\n SELECT r.key INTO bad FROM source_references r\n LEFT JOIN items i ON i.id = r.item_id LEFT JOIN context_sections c ON c.id = r.section_id\n WHERE r.project_id = NEW.project_id AND r.key = NEW.key AND r.retired_at IS NULL\n AND position('[ref ' || r.key || ']' IN coalesce(i.body, c.content, '')) = 0\n AND position('[ref ' || r.key || ':' IN coalesce(i.body, c.content, '')) = 0\n LIMIT 1;\n IF bad IS NULL THEN\n SELECT r.key INTO bad FROM source_references r\n WHERE r.project_id = NEW.project_id AND r.key = NEW.key AND r.retired_at IS NULL\n GROUP BY r.key HAVING count(DISTINCT coalesce(r.item_id, r.section_id)) > 1;\n IF bad IS NOT NULL THEN\n RAISE EXCEPTION 'source reference % has more than one owner', bad USING ERRCODE = 'check_violation';\n END IF;\n END IF;\n END IF;\n IF bad IS NOT NULL THEN\n RAISE EXCEPTION 'source reference % is live but its pointer is not in the text', bad USING ERRCODE = 'check_violation';\n END IF;\n RETURN NULL;\nEND\n$$;\n--> statement-breakpoint\nCREATE CONSTRAINT TRIGGER \"source_references_on_items\" AFTER UPDATE OF \"body\" ON \"items\"\n DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION \"source_references_check\"();\n--> statement-breakpoint\nCREATE CONSTRAINT TRIGGER \"source_references_on_sections\" AFTER UPDATE OF \"content\" ON \"context_sections\"\n DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION \"source_references_check\"();\n--> statement-breakpoint\nCREATE CONSTRAINT TRIGGER \"source_references_on_rows\" AFTER INSERT OR UPDATE ON \"source_references\"\n DEFERRABLE INITIALLY DEFERRED FOR EACH ROW EXECUTE FUNCTION \"source_references_check\"();\n";
|
|
42869
42907
|
// src/db/migrations/meta/_journal.json
|
|
42870
42908
|
var version = "7";
|
|
42871
42909
|
var dialect = "postgresql";
|
|
@@ -42981,6 +43019,13 @@ var entries = [
|
|
|
42981
43019
|
"when": 1794545387434,
|
|
42982
43020
|
"tag": "0015_stormy_blindfold",
|
|
42983
43021
|
"breakpoints": true
|
|
43022
|
+
},
|
|
43023
|
+
{
|
|
43024
|
+
"idx": 16,
|
|
43025
|
+
"version": "7",
|
|
43026
|
+
"when": 1794774084272,
|
|
43027
|
+
"tag": "0016_brave_squadron_sinister",
|
|
43028
|
+
"breakpoints": true
|
|
42984
43029
|
}
|
|
42985
43030
|
];
|
|
42986
43031
|
var _journal_default = {
|
|
@@ -43006,7 +43051,8 @@ var files = /* #__PURE__ */ Object.assign({
|
|
|
43006
43051
|
"./migrations/0012_smiling_butterfly.sql": _0012_smiling_butterfly_default,
|
|
43007
43052
|
"./migrations/0013_kind_bloodscream.sql": _0013_kind_bloodscream_default,
|
|
43008
43053
|
"./migrations/0014_past_chronomancer.sql": _0014_past_chronomancer_default,
|
|
43009
|
-
"./migrations/0015_stormy_blindfold.sql": _0015_stormy_blindfold_default
|
|
43054
|
+
"./migrations/0015_stormy_blindfold.sql": _0015_stormy_blindfold_default,
|
|
43055
|
+
"./migrations/0016_brave_squadron_sinister.sql": _0016_brave_squadron_sinister_default
|
|
43010
43056
|
});
|
|
43011
43057
|
/** The breakpoint drizzle-kit writes between statements, and that drizzle's reader splits on. */
|
|
43012
43058
|
var BREAKPOINT = "--> statement-breakpoint";
|
|
@@ -43126,6 +43172,12 @@ var dataDirFor = (storePath) => join(storePath, "..", isLegacyStore(storePath) ?
|
|
|
43126
43172
|
* because positions change on every drag and every new item, and the plan file is the one a reviewer reads.
|
|
43127
43173
|
*/
|
|
43128
43174
|
var layoutPathFor = (storePath) => join(dataDirFor(storePath), "layout.yaml");
|
|
43175
|
+
/**
|
|
43176
|
+
* Where a plan's source references live (`CTX-13`): beside it in its data folder, like its layout, because a source
|
|
43177
|
+
* carries a verbatim quote or a URL and a copy of the claim it vouched for - bulk a reader of the plan never reads,
|
|
43178
|
+
* and which would bury the items in it. Unlike the layout it is real data, so a save guards it like the plan.
|
|
43179
|
+
*/
|
|
43180
|
+
var referencesPathFor = (storePath) => join(dataDirFor(storePath), "references.yaml");
|
|
43129
43181
|
// src/domain/measurements.ts
|
|
43130
43182
|
/**
|
|
43131
43183
|
* Recording and querying measurements (`METRIC-2`).
|
|
@@ -50228,8 +50280,10 @@ async function clearAll(tx, { keepIdentity }) {
|
|
|
50228
50280
|
* `priority` is a global integer that cannot be maintained across 157 items, and `status` says "committed or
|
|
50229
50281
|
* not" without saying in what order.
|
|
50230
50282
|
*
|
|
50231
|
-
* **
|
|
50232
|
-
*
|
|
50283
|
+
* **The ranking is the feature, not the length.** It was "five to ten refs" until `PROJ-13` (2026-11-14): the
|
|
50284
|
+
* shortness was meant to force "does this beat what is already third?". The board (`VIEW-46`) made a longer
|
|
50285
|
+
* list readable, so the length advice went; what still forces the comparison is that the list is one ordered
|
|
50286
|
+
* list per project, replaced whole, most important first.
|
|
50233
50287
|
*
|
|
50234
50288
|
* Two rules here are worth stating because neither is obvious:
|
|
50235
50289
|
*
|
|
@@ -50500,6 +50554,23 @@ var attachmentSchema = object({
|
|
|
50500
50554
|
at: string(),
|
|
50501
50555
|
actor: string()
|
|
50502
50556
|
});
|
|
50557
|
+
/**
|
|
50558
|
+
* One source behind a source reference (`CTX-13`). References are written where their pointer is - under the item
|
|
50559
|
+
* whose body holds it, keyed by the pointer's key - so reading the file shows a claim's sources beside the item,
|
|
50560
|
+
* as comments are. The row's `id` rides along like a comment's, so a round trip keeps it and an edit can address it.
|
|
50561
|
+
* `text` is the exact text this source vouched for; `retired` is set when its pointer was removed.
|
|
50562
|
+
*/
|
|
50563
|
+
var referenceSchema = object({
|
|
50564
|
+
source: string(),
|
|
50565
|
+
detail: string(),
|
|
50566
|
+
text: string(),
|
|
50567
|
+
id: string(),
|
|
50568
|
+
at: string(),
|
|
50569
|
+
actor: string(),
|
|
50570
|
+
retired: string().optional()
|
|
50571
|
+
});
|
|
50572
|
+
/** Pointer key -> its sources, oldest first. */
|
|
50573
|
+
var referencesSchema = record(string().regex(/^[a-z0-9]+$/, "a reference key is lowercase letters and digits"), array(referenceSchema));
|
|
50503
50574
|
/** One project's layout: node id -> "x,y", whole numbers on the layout's grid. */
|
|
50504
50575
|
var layoutSchema = record(string(), string().regex(/^-?\d+,-?\d+$/, "a layout position is \"x,y\" in whole numbers"));
|
|
50505
50576
|
var itemSchema = object({
|
|
@@ -50531,7 +50602,8 @@ var itemSchema = object({
|
|
|
50531
50602
|
comments: array(commentSchema).optional(),
|
|
50532
50603
|
/** Accepted for old plan files, never written: see `readComments` (CTX-2). */
|
|
50533
50604
|
notes: array(commentSchema).optional(),
|
|
50534
|
-
attachments: array(attachmentSchema).optional()
|
|
50605
|
+
attachments: array(attachmentSchema).optional(),
|
|
50606
|
+
references: referencesSchema.optional()
|
|
50535
50607
|
});
|
|
50536
50608
|
var retiredSessionSchema = array(unknown());
|
|
50537
50609
|
var projectSchema = object({
|
|
@@ -50546,6 +50618,7 @@ var projectSchema = object({
|
|
|
50546
50618
|
updated_at: string(),
|
|
50547
50619
|
archived_at: string().optional(),
|
|
50548
50620
|
context: record(string(), string()).optional(),
|
|
50621
|
+
context_references: record(string(), referencesSchema).optional(),
|
|
50549
50622
|
areas: array(areaSchema),
|
|
50550
50623
|
items: array(itemSchema),
|
|
50551
50624
|
sessions: retiredSessionSchema.optional(),
|
|
@@ -50603,7 +50676,7 @@ function asPlan(store) {
|
|
|
50603
50676
|
return {
|
|
50604
50677
|
...rest,
|
|
50605
50678
|
next: project.next?.filter((ref) => actionable.has(ref)),
|
|
50606
|
-
items: live.map(({ body: _body, comments: _comments, notes: _notes, attachments: _attachments, ...item }) => ({
|
|
50679
|
+
items: live.map(({ body: _body, comments: _comments, notes: _notes, attachments: _attachments, references: _references, ...item }) => ({
|
|
50607
50680
|
...item,
|
|
50608
50681
|
deps: item.deps?.filter((ref) => splitScope(ref) !== null || present.has(ref)),
|
|
50609
50682
|
parent: item.parent !== void 0 && present.has(item.parent) ? item.parent : void 0
|
|
@@ -50665,6 +50738,28 @@ async function exportStore(db, ownerId) {
|
|
|
50665
50738
|
actor: a.actor
|
|
50666
50739
|
})) : void 0;
|
|
50667
50740
|
const layoutRows = await db.select().from(layoutPositions).where(eq(layoutPositions.projectId, p.id)).orderBy(asc(layoutPositions.node));
|
|
50741
|
+
const referenceRows = await db.select().from(sourceReferences).where(eq(sourceReferences.projectId, p.id)).orderBy(asc(sourceReferences.key), asc(sourceReferences.recordedAt), asc(sourceReferences.id));
|
|
50742
|
+
const sectionHeading = new Map(sectionRows.map((s) => [s.id, s.heading]));
|
|
50743
|
+
const referencesByItem = /* @__PURE__ */ new Map();
|
|
50744
|
+
const referencesBySection = /* @__PURE__ */ new Map();
|
|
50745
|
+
for (const r of referenceRows) {
|
|
50746
|
+
const [owners, owner] = r.itemId !== null ? [referencesByItem, r.itemId] : [referencesBySection, sectionHeading.get(r.sectionId)];
|
|
50747
|
+
const byKey = owners.get(owner) ?? owners.set(owner, {}).get(owner);
|
|
50748
|
+
(byKey[r.key] ??= []).push({
|
|
50749
|
+
source: r.source,
|
|
50750
|
+
detail: r.detail,
|
|
50751
|
+
text: r.quotedText,
|
|
50752
|
+
id: r.id,
|
|
50753
|
+
at: r.recordedAt,
|
|
50754
|
+
actor: r.actor,
|
|
50755
|
+
retired: opt(r.retiredAt)
|
|
50756
|
+
});
|
|
50757
|
+
}
|
|
50758
|
+
const contextReferences = {};
|
|
50759
|
+
for (const s of sectionRows) {
|
|
50760
|
+
const refs = referencesBySection.get(s.heading);
|
|
50761
|
+
if (refs !== void 0) contextReferences[s.heading] = refs;
|
|
50762
|
+
}
|
|
50668
50763
|
const fmtComments = (rows) => rows.length > 0 ? rows.map((n) => ({
|
|
50669
50764
|
body: n.body,
|
|
50670
50765
|
audience: n.audience,
|
|
@@ -50684,6 +50779,7 @@ async function exportStore(db, ownerId) {
|
|
|
50684
50779
|
updated_at: p.updatedAt,
|
|
50685
50780
|
archived_at: opt(p.archivedAt),
|
|
50686
50781
|
context: sectionRows.length > 0 ? context : void 0,
|
|
50782
|
+
context_references: Object.keys(contextReferences).length > 0 ? contextReferences : void 0,
|
|
50687
50783
|
comments: fmtComments(projectComments),
|
|
50688
50784
|
attachments: fmtAttachments(projectAttachments),
|
|
50689
50785
|
areas: areaRows.map((a) => ({
|
|
@@ -50714,7 +50810,8 @@ async function exportStore(db, ownerId) {
|
|
|
50714
50810
|
closed_at: opt(i.closedAt),
|
|
50715
50811
|
deleted_at: opt(i.deletedAt),
|
|
50716
50812
|
comments: fmtComments(commentsByItem.get(i.id) ?? []),
|
|
50717
|
-
attachments: fmtAttachments(attachmentsByItem.get(i.id) ?? [])
|
|
50813
|
+
attachments: fmtAttachments(attachmentsByItem.get(i.id) ?? []),
|
|
50814
|
+
references: referencesByItem.get(i.id)
|
|
50718
50815
|
};
|
|
50719
50816
|
}),
|
|
50720
50817
|
layout: layoutRows.length > 0 ? Object.fromEntries(layoutRows.map((row) => [row.node, `${row.x},${row.y}`])) : void 0
|
|
@@ -50742,6 +50839,7 @@ async function replaceStore(db, store) {
|
|
|
50742
50839
|
});
|
|
50743
50840
|
}
|
|
50744
50841
|
async function insertStore(tx, store, owner) {
|
|
50842
|
+
await tx.execute(sql`select set_config('attraverso.loading_plan', 'on', true)`);
|
|
50745
50843
|
const ownerId = owner ?? (await ensureUserIn(tx, LOCAL_IDENTITY)).id;
|
|
50746
50844
|
for (const p of store.projects) {
|
|
50747
50845
|
await tx.insert(projects).values({
|
|
@@ -50830,12 +50928,43 @@ async function insertStore(tx, store, owner) {
|
|
|
50830
50928
|
});
|
|
50831
50929
|
if (layoutValues.length > 0) await tx.insert(layoutPositions).values(layoutValues);
|
|
50832
50930
|
const contextEntries = Object.entries(p.context ?? {});
|
|
50833
|
-
|
|
50931
|
+
const headingToId = /* @__PURE__ */ new Map();
|
|
50932
|
+
if (contextEntries.length > 0) {
|
|
50933
|
+
const inserted = await tx.insert(contextSections).values(contextEntries.map(([heading, content], index) => ({
|
|
50934
|
+
projectId: p.id,
|
|
50935
|
+
heading,
|
|
50936
|
+
content,
|
|
50937
|
+
sortOrder: index
|
|
50938
|
+
}))).returning({
|
|
50939
|
+
id: contextSections.id,
|
|
50940
|
+
heading: contextSections.heading
|
|
50941
|
+
});
|
|
50942
|
+
for (const row of inserted) headingToId.set(row.heading, row.id);
|
|
50943
|
+
}
|
|
50944
|
+
const referenceValues = [...p.items.flatMap((i) => Object.entries(i.references ?? {}).map(([key, rows]) => ({
|
|
50945
|
+
key,
|
|
50946
|
+
rows,
|
|
50947
|
+
itemId: refToId.get(i.ref) ?? null,
|
|
50948
|
+
sectionId: null
|
|
50949
|
+
}))), ...Object.entries(p.context_references ?? {}).flatMap(([heading, refs]) => Object.entries(refs).map(([key, rows]) => ({
|
|
50950
|
+
key,
|
|
50951
|
+
rows,
|
|
50952
|
+
itemId: null,
|
|
50953
|
+
sectionId: headingToId.get(heading) ?? null
|
|
50954
|
+
})))].flatMap(({ key, rows, itemId, sectionId }) => itemId === null && sectionId === null ? [] : rows.map((r) => ({
|
|
50955
|
+
id: r.id,
|
|
50834
50956
|
projectId: p.id,
|
|
50835
|
-
|
|
50836
|
-
|
|
50837
|
-
|
|
50957
|
+
key,
|
|
50958
|
+
itemId,
|
|
50959
|
+
sectionId,
|
|
50960
|
+
source: r.source,
|
|
50961
|
+
detail: r.detail,
|
|
50962
|
+
quotedText: r.text,
|
|
50963
|
+
actor: r.actor,
|
|
50964
|
+
recordedAt: r.at,
|
|
50965
|
+
retiredAt: r.retired ?? null
|
|
50838
50966
|
})));
|
|
50967
|
+
if (referenceValues.length > 0) await tx.insert(sourceReferences).values(referenceValues);
|
|
50839
50968
|
const commentValues = [...readComments(p).map((c) => ({
|
|
50840
50969
|
comment: c,
|
|
50841
50970
|
itemId: null
|
|
@@ -50909,6 +51038,67 @@ var stringifyLayout = (layouts) => (0, import_dist.stringify)(layouts, YAML_FORM
|
|
|
50909
51038
|
function parseLayout(text) {
|
|
50910
51039
|
return layoutFileSchema.parse((0, import_dist.parse)(text) ?? {});
|
|
50911
51040
|
}
|
|
51041
|
+
/**
|
|
51042
|
+
* A plan's source references (`CTX-13`), kept in their own file beside it (`references.yaml`): per project key, its
|
|
51043
|
+
* items' references by ref and its context sections' by heading, each a pointer key to its sources. Keyed the way
|
|
51044
|
+
* the plan names things, by key, ref and heading, so the file reads beside the plan it explains.
|
|
51045
|
+
*/
|
|
51046
|
+
var referencesFileSchema = record(string(), object({
|
|
51047
|
+
items: record(string(), referencesSchema).optional(),
|
|
51048
|
+
context: record(string(), referencesSchema).optional()
|
|
51049
|
+
}));
|
|
51050
|
+
/** A plan, with its source references taken out to be written to their own file. Everything else stays as it was. */
|
|
51051
|
+
function splitReferences(store) {
|
|
51052
|
+
const references = {};
|
|
51053
|
+
return {
|
|
51054
|
+
plan: { projects: store.projects.map(({ context_references, ...project }) => {
|
|
51055
|
+
const items = {};
|
|
51056
|
+
const stripped = project.items.map(({ references: refs, ...item }) => {
|
|
51057
|
+
if (refs !== void 0) items[item.ref] = refs;
|
|
51058
|
+
return item;
|
|
51059
|
+
});
|
|
51060
|
+
const entry = {
|
|
51061
|
+
...Object.keys(items).length > 0 ? { items } : {},
|
|
51062
|
+
...context_references !== void 0 ? { context: context_references } : {}
|
|
51063
|
+
};
|
|
51064
|
+
if (Object.keys(entry).length > 0) references[project.key] = entry;
|
|
51065
|
+
return {
|
|
51066
|
+
...project,
|
|
51067
|
+
items: stripped
|
|
51068
|
+
};
|
|
51069
|
+
}) },
|
|
51070
|
+
references
|
|
51071
|
+
};
|
|
51072
|
+
}
|
|
51073
|
+
/**
|
|
51074
|
+
* Put a references file's sources back into the plan they belong to. **The file wins** for a project it names, over
|
|
51075
|
+
* references still inline in the plan (a plan saved before they had a file of their own), since every save since
|
|
51076
|
+
* has gone to the file; a project it does not name keeps what it had, so an inline plan loads, and its next save
|
|
51077
|
+
* moves them out. An entry naming an item or a heading the plan does not have is left out here and reported by
|
|
51078
|
+
* `apm:check` (`orphanedReferences`), rather than refusing the load.
|
|
51079
|
+
*/
|
|
51080
|
+
var mergeReferences = (store, references) => ({ projects: store.projects.map((project) => {
|
|
51081
|
+
const entry = references[project.key];
|
|
51082
|
+
if (entry === void 0) return project;
|
|
51083
|
+
const items = project.items.map(({ references: _inline, ...item }) => {
|
|
51084
|
+
const refs = entry.items?.[item.ref];
|
|
51085
|
+
return refs === void 0 ? item : {
|
|
51086
|
+
...item,
|
|
51087
|
+
references: refs
|
|
51088
|
+
};
|
|
51089
|
+
});
|
|
51090
|
+
const context = Object.fromEntries(Object.entries(entry.context ?? {}).filter(([heading]) => heading in (project.context ?? {})));
|
|
51091
|
+
return {
|
|
51092
|
+
...project,
|
|
51093
|
+
items,
|
|
51094
|
+
context_references: Object.keys(context).length > 0 ? context : void 0
|
|
51095
|
+
};
|
|
51096
|
+
}) });
|
|
51097
|
+
var stringifyReferences = (references) => (0, import_dist.stringify)(references, YAML_FORMAT);
|
|
51098
|
+
/** A references file's contents. An empty file is no references. */
|
|
51099
|
+
function parseReferences(text) {
|
|
51100
|
+
return referencesFileSchema.parse((0, import_dist.parse)(text) ?? {});
|
|
51101
|
+
}
|
|
50912
51102
|
function parseStore(text) {
|
|
50913
51103
|
return storeSchema.parse((0, import_dist.parse)(text));
|
|
50914
51104
|
}
|
|
@@ -51088,10 +51278,10 @@ async function writeAtomic(path, text) {
|
|
|
51088
51278
|
*/
|
|
51089
51279
|
async function saveStore(db, path, only) {
|
|
51090
51280
|
const { id: ownerId } = await ensureUser(db, LOCAL_IDENTITY);
|
|
51091
|
-
const { plan,
|
|
51281
|
+
const { plan, sides } = splitSides(restrict(await exportStore(db, ownerId), only));
|
|
51092
51282
|
const text = stringifyStore(plan);
|
|
51283
|
+
for (const kind of SIDE_KINDS) if (!kind.empty(sides.get(kind))) await writeAtomic(kind.pathFor(path), kind.stringify(sides.get(kind)));
|
|
51093
51284
|
await writeAtomic(path, text);
|
|
51094
|
-
if (Object.keys(layouts).length > 0) await writeAtomic(layoutPathFor(path), stringifyLayout(layouts));
|
|
51095
51285
|
return hashOf$1(text);
|
|
51096
51286
|
}
|
|
51097
51287
|
/** The store narrowed to some project ids, preserving `exportStore`'s order so the result stays deterministic. */
|
|
@@ -51121,11 +51311,61 @@ async function stampOf(path) {
|
|
|
51121
51311
|
return null;
|
|
51122
51312
|
}
|
|
51123
51313
|
}
|
|
51314
|
+
var LAYOUT = {
|
|
51315
|
+
name: "layout",
|
|
51316
|
+
pathFor: layoutPathFor,
|
|
51317
|
+
guarded: false,
|
|
51318
|
+
parse: parseLayout,
|
|
51319
|
+
stringify: (side) => stringifyLayout(side),
|
|
51320
|
+
split: (store) => {
|
|
51321
|
+
const { plan, layouts } = splitLayout(store);
|
|
51322
|
+
return {
|
|
51323
|
+
plan,
|
|
51324
|
+
side: layouts
|
|
51325
|
+
};
|
|
51326
|
+
},
|
|
51327
|
+
merge: (store, side) => mergeLayout(store, side),
|
|
51328
|
+
empty: (side) => Object.keys(side).length === 0
|
|
51329
|
+
};
|
|
51330
|
+
var REFERENCES = {
|
|
51331
|
+
name: "references",
|
|
51332
|
+
pathFor: referencesPathFor,
|
|
51333
|
+
guarded: true,
|
|
51334
|
+
parse: parseReferences,
|
|
51335
|
+
stringify: (side) => stringifyReferences(side),
|
|
51336
|
+
split: (store) => {
|
|
51337
|
+
const { plan, references } = splitReferences(store);
|
|
51338
|
+
return {
|
|
51339
|
+
plan,
|
|
51340
|
+
side: references
|
|
51341
|
+
};
|
|
51342
|
+
},
|
|
51343
|
+
merge: (store, side) => mergeReferences(store, side),
|
|
51344
|
+
empty: (side) => Object.keys(side).length === 0
|
|
51345
|
+
};
|
|
51346
|
+
/** References first: `save` writes them before the plan, so a save cut short leaves sources whose pointers are not
|
|
51347
|
+
* written yet (loaded as they are, and retired, never lost, by the next edit) rather than pointers with nothing
|
|
51348
|
+
* behind them. */
|
|
51349
|
+
var SIDE_KINDS = [REFERENCES, LAYOUT];
|
|
51350
|
+
/** A plan with every side file's part taken out, and each part by kind. */
|
|
51351
|
+
function splitSides(store) {
|
|
51352
|
+
const sides = /* @__PURE__ */ new Map();
|
|
51353
|
+
let plan = store;
|
|
51354
|
+
for (const kind of SIDE_KINDS) {
|
|
51355
|
+
const split = kind.split(plan);
|
|
51356
|
+
plan = split.plan;
|
|
51357
|
+
sides.set(kind, split.side);
|
|
51358
|
+
}
|
|
51359
|
+
return {
|
|
51360
|
+
plan,
|
|
51361
|
+
sides
|
|
51362
|
+
};
|
|
51363
|
+
}
|
|
51124
51364
|
/**
|
|
51125
|
-
* A
|
|
51126
|
-
*
|
|
51365
|
+
* A side file as read from disk, or null when there is none. Parse failures throw, naming the file: a half-merged
|
|
51366
|
+
* layout or references file should fail as loudly as a half-merged plan rather than quietly dropping its part.
|
|
51127
51367
|
*/
|
|
51128
|
-
async function
|
|
51368
|
+
async function readSideFile(kind, path) {
|
|
51129
51369
|
let text;
|
|
51130
51370
|
try {
|
|
51131
51371
|
text = await readFile(path, "utf8");
|
|
@@ -51134,12 +51374,12 @@ async function readLayoutFile(path) {
|
|
|
51134
51374
|
}
|
|
51135
51375
|
try {
|
|
51136
51376
|
return {
|
|
51137
|
-
|
|
51377
|
+
side: kind.parse(text),
|
|
51138
51378
|
hash: hashOf$1(text),
|
|
51139
51379
|
stamp: await stampOf(path)
|
|
51140
51380
|
};
|
|
51141
51381
|
} catch (cause) {
|
|
51142
|
-
throw new Error(`${path} is not a
|
|
51382
|
+
throw new Error(`${path} is not a ${kind.name} file: ${cause instanceof Error ? cause.message : String(cause)}`);
|
|
51143
51383
|
}
|
|
51144
51384
|
}
|
|
51145
51385
|
/**
|
|
@@ -51176,30 +51416,31 @@ function createStoreFile(where) {
|
|
|
51176
51416
|
file.keys = new Set(store.projects.map((project) => project.key));
|
|
51177
51417
|
};
|
|
51178
51418
|
/**
|
|
51179
|
-
* The
|
|
51180
|
-
* by path rather than hung off each plan file, because two plan
|
|
51181
|
-
* `*.apm.yaml` side by side share `.apm/`) and so share one
|
|
51419
|
+
* The side files (the layout, `VIEW-23.2`; the references, `CTX-13`), one of each kind per data folder, with the
|
|
51420
|
+
* version this process last read or wrote. Keyed by path rather than hung off each plan file, because two plan
|
|
51421
|
+
* files can share a data folder (legacy `*.apm.yaml` side by side share `.apm/`) and so share one of each.
|
|
51182
51422
|
*/
|
|
51183
|
-
const
|
|
51184
|
-
for (const file of files) {
|
|
51185
|
-
const path =
|
|
51186
|
-
const entry =
|
|
51423
|
+
const sideFiles = /* @__PURE__ */ new Map();
|
|
51424
|
+
for (const kind of SIDE_KINDS) for (const file of files) {
|
|
51425
|
+
const path = kind.pathFor(file.path);
|
|
51426
|
+
const entry = sideFiles.get(path) ?? {
|
|
51427
|
+
kind,
|
|
51187
51428
|
known: null,
|
|
51188
51429
|
stamp: null,
|
|
51189
51430
|
owners: []
|
|
51190
51431
|
};
|
|
51191
51432
|
entry.owners.push(file);
|
|
51192
|
-
|
|
51433
|
+
sideFiles.set(path, entry);
|
|
51193
51434
|
}
|
|
51194
51435
|
/**
|
|
51195
|
-
* Read every
|
|
51196
|
-
*
|
|
51197
|
-
* the map reloads it like any other change.
|
|
51436
|
+
* Read every side file from disk and lay it over the plans it belongs to, recording what was read. Runs on open
|
|
51437
|
+
* and on every rebuild, so the database's layout and references are always the files' - a branch switch that
|
|
51438
|
+
* changes only the map, or only a source, reloads it like any other change.
|
|
51198
51439
|
*/
|
|
51199
|
-
const
|
|
51440
|
+
const overlaySides = async (loaded) => {
|
|
51200
51441
|
const out = [...loaded];
|
|
51201
|
-
for (const [path, entry] of
|
|
51202
|
-
const read = await
|
|
51442
|
+
for (const [path, entry] of sideFiles) {
|
|
51443
|
+
const read = await readSideFile(entry.kind, path);
|
|
51203
51444
|
if (read === null) continue;
|
|
51204
51445
|
entry.known = read.hash;
|
|
51205
51446
|
entry.stamp = read.stamp;
|
|
@@ -51207,7 +51448,7 @@ function createStoreFile(where) {
|
|
|
51207
51448
|
const one = out[index];
|
|
51208
51449
|
if (entry.owners.includes(one.file)) out[index] = {
|
|
51209
51450
|
file: one.file,
|
|
51210
|
-
store:
|
|
51451
|
+
store: entry.kind.merge(one.store, read.side)
|
|
51211
51452
|
};
|
|
51212
51453
|
}
|
|
51213
51454
|
}
|
|
@@ -51286,7 +51527,7 @@ function createStoreFile(where) {
|
|
|
51286
51527
|
store
|
|
51287
51528
|
})));
|
|
51288
51529
|
let created = false;
|
|
51289
|
-
for (const { file, store } of await
|
|
51530
|
+
for (const { file, store } of await overlaySides(loaded)) {
|
|
51290
51531
|
claim(file, store);
|
|
51291
51532
|
await importStore(db, store);
|
|
51292
51533
|
}
|
|
@@ -51322,18 +51563,18 @@ function createStoreFile(where) {
|
|
|
51322
51563
|
stamp: current
|
|
51323
51564
|
});
|
|
51324
51565
|
}
|
|
51325
|
-
let
|
|
51326
|
-
for (const [path, entry] of
|
|
51566
|
+
let sideMoved = false;
|
|
51567
|
+
for (const [path, entry] of sideFiles) {
|
|
51327
51568
|
const current = await stampOf(path);
|
|
51328
51569
|
if (current === null || current === entry.stamp) continue;
|
|
51329
51570
|
if (await hashOnDisk(path) === entry.known) entry.stamp = current;
|
|
51330
|
-
else
|
|
51571
|
+
else sideMoved = true;
|
|
51331
51572
|
}
|
|
51332
|
-
if (fresh.size === 0 && !
|
|
51573
|
+
if (fresh.size === 0 && !sideMoved) return false;
|
|
51333
51574
|
const { id: ownerId } = await ensureUser(db, LOCAL_IDENTITY);
|
|
51334
51575
|
const loadedNow = await exportStore(db, ownerId);
|
|
51335
51576
|
const claimed = new Set(files.flatMap((file) => [...file.ids]));
|
|
51336
|
-
const union = await
|
|
51577
|
+
const union = await overlaySides(files.map((file) => {
|
|
51337
51578
|
const moved = fresh.get(file);
|
|
51338
51579
|
if (moved !== void 0) return {
|
|
51339
51580
|
file,
|
|
@@ -51362,38 +51603,56 @@ function createStoreFile(where) {
|
|
|
51362
51603
|
return true;
|
|
51363
51604
|
}),
|
|
51364
51605
|
save: (db) => exclusive(async () => {
|
|
51606
|
+
const refuse = (path, gone) => {
|
|
51607
|
+
throw new Error(`refusing to save: ${path} ${gone ? "has been deleted" : "has changed"} since this server loaded it, so writing would overwrite whatever changed it (another apm server, a git checkout, or a hand edit). This change was applied in memory but NOT saved. ` + (gone ? "Restore the file, or reconnect the apm server to start a fresh one, then make the change again." : "The next call reloads the file, which discards this change, so make it again after that."));
|
|
51608
|
+
};
|
|
51365
51609
|
for (const file of files) {
|
|
51366
51610
|
const current = await hashOnDisk(file.path);
|
|
51367
|
-
if (file.known !== null && current !== file.known)
|
|
51368
|
-
|
|
51369
|
-
|
|
51370
|
-
|
|
51611
|
+
if (file.known !== null && current !== file.known) refuse(file.path, current === null);
|
|
51612
|
+
}
|
|
51613
|
+
for (const [path, entry] of sideFiles) {
|
|
51614
|
+
if (!entry.kind.guarded || entry.known === null) continue;
|
|
51615
|
+
const current = await hashOnDisk(path);
|
|
51616
|
+
if (current !== entry.known) refuse(path, current === null);
|
|
51371
51617
|
}
|
|
51372
51618
|
const { id: ownerId } = await ensureUser(db, LOCAL_IDENTITY);
|
|
51373
51619
|
const full = await exportStore(db, ownerId);
|
|
51374
51620
|
const claimed = new Set(files.flatMap((file) => [...file.ids]));
|
|
51375
|
-
const
|
|
51621
|
+
const sidesOf = /* @__PURE__ */ new Map();
|
|
51622
|
+
const plans = [];
|
|
51376
51623
|
for (const file of files) {
|
|
51377
51624
|
const mine = full.projects.filter((p) => file.ids.has(p.id) || file === primary && !claimed.has(p.id));
|
|
51378
|
-
const { plan,
|
|
51379
|
-
|
|
51625
|
+
const { plan, sides } = splitSides({ projects: mine });
|
|
51626
|
+
sidesOf.set(file, sides);
|
|
51380
51627
|
const text = stringifyStore(plan);
|
|
51381
|
-
|
|
51628
|
+
plans.push({
|
|
51629
|
+
file,
|
|
51630
|
+
mine,
|
|
51631
|
+
text,
|
|
51632
|
+
hash: hashOf$1(text)
|
|
51633
|
+
});
|
|
51634
|
+
}
|
|
51635
|
+
const writeSides = async (kinds) => {
|
|
51636
|
+
for (const [path, entry] of sideFiles) {
|
|
51637
|
+
if (!kinds.includes(entry.kind)) continue;
|
|
51638
|
+
const side = Object.assign({}, ...entry.owners.map((owner) => sidesOf.get(owner)?.get(entry.kind) ?? {}));
|
|
51639
|
+
if (entry.kind.empty(side) && entry.known === null) continue;
|
|
51640
|
+
const text = entry.kind.stringify(side);
|
|
51641
|
+
const hash = hashOf$1(text);
|
|
51642
|
+
if (hash === entry.known) continue;
|
|
51643
|
+
await writeAtomic(path, text);
|
|
51644
|
+
entry.known = hash;
|
|
51645
|
+
entry.stamp = await stampOf(path);
|
|
51646
|
+
}
|
|
51647
|
+
};
|
|
51648
|
+
await writeSides([REFERENCES]);
|
|
51649
|
+
for (const { file, mine, text, hash } of plans) {
|
|
51382
51650
|
if (hash === file.known) continue;
|
|
51383
51651
|
await writeAtomic(file.path, text);
|
|
51384
51652
|
claim(file, { projects: mine });
|
|
51385
51653
|
await remember(file, hash);
|
|
51386
51654
|
}
|
|
51387
|
-
|
|
51388
|
-
const layouts = Object.assign({}, ...entry.owners.map((owner) => layoutsOf.get(owner) ?? {}));
|
|
51389
|
-
if (Object.keys(layouts).length === 0 && entry.known === null) continue;
|
|
51390
|
-
const text = stringifyLayout(layouts);
|
|
51391
|
-
const hash = hashOf$1(text);
|
|
51392
|
-
if (hash === entry.known) continue;
|
|
51393
|
-
await writeAtomic(path, text);
|
|
51394
|
-
entry.known = hash;
|
|
51395
|
-
entry.stamp = await stampOf(path);
|
|
51396
|
-
}
|
|
51655
|
+
await writeSides([LAYOUT]);
|
|
51397
51656
|
})
|
|
51398
51657
|
};
|
|
51399
51658
|
}
|
|
@@ -51402,6 +51661,7 @@ var accessTo = (store, db) => ({
|
|
|
51402
51661
|
refresh: () => store.refresh(db),
|
|
51403
51662
|
reloads: () => store.reloads(),
|
|
51404
51663
|
paths: () => store.paths,
|
|
51664
|
+
planFileOf: (key) => store.fileOf(key),
|
|
51405
51665
|
appendMeasurements: (records) => store.appendMeasurements(records)
|
|
51406
51666
|
});
|
|
51407
51667
|
// src/media/store.ts
|
|
@@ -51504,6 +51764,468 @@ function createUnavailableMediaStore(reason) {
|
|
|
51504
51764
|
}
|
|
51505
51765
|
};
|
|
51506
51766
|
}
|
|
51767
|
+
// scripts/references.ts
|
|
51768
|
+
/**
|
|
51769
|
+
* Source reference pointers in prose (`CTX-13`): where they are, and what text each one stands behind.
|
|
51770
|
+
*
|
|
51771
|
+
* A claim is followed by a pointer, `[ref r7k2]`, and the reference's sources live in `source_references`. This
|
|
51772
|
+
* module is the one parser every reader shares - the tools, `apm:check` and the viewer - so it is Node-free, like
|
|
51773
|
+
* `tickets.ts`: two parsers that split a body differently would make one claim stale in one place and fine in
|
|
51774
|
+
* another.
|
|
51775
|
+
*
|
|
51776
|
+
* **What a pointer covers is set by where it sits, never stored:**
|
|
51777
|
+
*
|
|
51778
|
+
* - **Inline, it covers the text before it** in the same markdown block, back to the previous pointer or the
|
|
51779
|
+
* block's start - the footnote convention, a citation after its claim. A block is a paragraph, one list item,
|
|
51780
|
+
* one table row, a heading, or a code block.
|
|
51781
|
+
* - **On its own line, it covers the whole group above it**: a paragraph, a whole list, a whole table, a code block.
|
|
51782
|
+
* Pointer-only lines in between are skipped, so two sources can stand behind one table.
|
|
51783
|
+
*
|
|
51784
|
+
* **What is not a pointer:** anything inside a code span or a fenced block, so documentation of this syntax never
|
|
51785
|
+
* trips it; an escaped `\[ref`; one followed by `(` or `:`, which markdown reads as a link or a link definition
|
|
51786
|
+
* (`[ref docs](https://...)`); and only `[ref ` followed by a key opens one, so task boxes and footnotes never do.
|
|
51787
|
+
* Indented code is not masked, deliberately: four-space list continuations are far commoner in these bodies.
|
|
51788
|
+
*
|
|
51789
|
+
* Deliberately a small line scanner rather than a markdown parser: the server has no markdown dependency at
|
|
51790
|
+
* runtime, and the few block shapes that matter here are easy to tell apart by their first characters.
|
|
51791
|
+
*/
|
|
51792
|
+
/** A key is short lowercase letters and digits, generated by the tool: never shaped like an item's ref. */
|
|
51793
|
+
var KEY = "[a-z0-9]+";
|
|
51794
|
+
/** How long an expanded pointer's detail may run: `get_item` keeps what it shows well under it, and the bound keeps a
|
|
51795
|
+
* run of unclosed `[ref k:` from costing quadratic time on hostile input. */
|
|
51796
|
+
var EXPANSION = "[^\\]\\n]{0,3000}";
|
|
51797
|
+
/** `[ref key]`, or the expanded `[ref key: ...]` that `get_item` returns and an agent may send straight back. Not
|
|
51798
|
+
* escaped, and not followed by `(` or `:`, which would make it a link or a link definition. */
|
|
51799
|
+
var POINTER = new RegExp(`(?<!\\\\)\\[ref (${KEY})(?::${EXPANSION})?\\](?![(:])`, "g");
|
|
51800
|
+
/** `[ref ` not followed by a well-formed key and its close: a pointer someone meant to write and got wrong. */
|
|
51801
|
+
var MALFORMED = new RegExp(`(?<!\\\\)\\[ref (?!${KEY}(?:\\]|:${EXPANSION}\\]))`, "g");
|
|
51802
|
+
/**
|
|
51803
|
+
* The comparison form of some covered text: whitespace collapsed, Unicode NFC, and trimmed of what surrounds a
|
|
51804
|
+
* claim rather than belonging to it - a list marker or heading hashes in front, a table's pipes, the punctuation
|
|
51805
|
+
* left at the start of a span by the previous pointer's sentence.
|
|
51806
|
+
*/
|
|
51807
|
+
function normaliseClaim(text) {
|
|
51808
|
+
return text.normalize("NFC").replace(/^[ \t]*>[ \t]?/gm, "").replace(/\s+/g, " ").replace(/^\s*(?:[-*+]|\d+[.)]|#{1,6})\s+/, "").replace(/^[\s|.,;:!?)]+/, "").replace(/[\s|]+$/, "").trim();
|
|
51809
|
+
}
|
|
51810
|
+
/** A fence marker opening a line: three or more backticks or tildes. */
|
|
51811
|
+
var fenceOf = (line) => /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
|
|
51812
|
+
/** Whether `marker` closes a block opened by `fence`: the same character, at least as many of it. */
|
|
51813
|
+
var closes = (fence, marker) => marker[0] === fence[0] && marker.length >= fence.length;
|
|
51814
|
+
/** The text with every code span and fenced block blanked to spaces, keeping offsets, so pointers in code vanish. */
|
|
51815
|
+
function maskCode(text) {
|
|
51816
|
+
const lines = text.split("\n");
|
|
51817
|
+
let fence;
|
|
51818
|
+
return lines.map((line) => {
|
|
51819
|
+
const marker = fenceOf(line);
|
|
51820
|
+
if (fence === void 0 && marker !== void 0) {
|
|
51821
|
+
fence = marker;
|
|
51822
|
+
return " ".repeat(line.length);
|
|
51823
|
+
}
|
|
51824
|
+
if (fence !== void 0) {
|
|
51825
|
+
if (marker !== void 0 && closes(fence, marker)) fence = void 0;
|
|
51826
|
+
return " ".repeat(line.length);
|
|
51827
|
+
}
|
|
51828
|
+
return line;
|
|
51829
|
+
}).join("\n").split(/(\n[ \t]*\n)/).map(maskSpans).join("");
|
|
51830
|
+
}
|
|
51831
|
+
/**
|
|
51832
|
+
* Blank the inline code spans in one paragraph: a run of backticks closed by the next run of exactly the same
|
|
51833
|
+
* length. A run with no partner is literal text, and the scan carries on after it, as CommonMark has it - so a
|
|
51834
|
+
* stray backtick in prose ("the ` key") hides nothing after it.
|
|
51835
|
+
*/
|
|
51836
|
+
function maskSpans(paragraph) {
|
|
51837
|
+
const runs = [...paragraph.matchAll(/`+/g)].map((m) => ({
|
|
51838
|
+
at: m.index,
|
|
51839
|
+
length: m[0].length
|
|
51840
|
+
}));
|
|
51841
|
+
const nextSame = new Array(runs.length).fill(-1);
|
|
51842
|
+
const seen = /* @__PURE__ */ new Map();
|
|
51843
|
+
for (let i = runs.length - 1; i >= 0; i--) {
|
|
51844
|
+
nextSame[i] = seen.get(runs[i].length) ?? -1;
|
|
51845
|
+
seen.set(runs[i].length, i);
|
|
51846
|
+
}
|
|
51847
|
+
const pieces = [];
|
|
51848
|
+
let last = 0;
|
|
51849
|
+
for (let i = 0; i < runs.length; i++) {
|
|
51850
|
+
const open = runs[i];
|
|
51851
|
+
const close = nextSame[i];
|
|
51852
|
+
if (close === -1) continue;
|
|
51853
|
+
const end = runs[close].at + open.length;
|
|
51854
|
+
pieces.push(paragraph.slice(last, open.at), " ".repeat(end - open.at));
|
|
51855
|
+
last = end;
|
|
51856
|
+
i = close;
|
|
51857
|
+
}
|
|
51858
|
+
return last === 0 ? paragraph : pieces.join("") + paragraph.slice(last);
|
|
51859
|
+
}
|
|
51860
|
+
/**
|
|
51861
|
+
* Split a text into blocks by its lines, with offsets into the original text. A paragraph runs until a blank line
|
|
51862
|
+
* or a line that opens a block of its own; a list item takes the unmarked lines after it (its lazy continuation);
|
|
51863
|
+
* a heading and a table row are one line each; a fenced block runs to its closing fence. Consecutive list items
|
|
51864
|
+
* share a group, even across a blank line, as do consecutive table rows, which is what an own-line pointer covers.
|
|
51865
|
+
*/
|
|
51866
|
+
function blocks(text) {
|
|
51867
|
+
const out = [];
|
|
51868
|
+
let group = 0;
|
|
51869
|
+
let offset = 0;
|
|
51870
|
+
let open = null;
|
|
51871
|
+
let fence;
|
|
51872
|
+
let afterBlank = false;
|
|
51873
|
+
for (const line of text.split("\n")) {
|
|
51874
|
+
const start = offset;
|
|
51875
|
+
const end = offset + line.length;
|
|
51876
|
+
offset = end + 1;
|
|
51877
|
+
const marker = fenceOf(line);
|
|
51878
|
+
if (fence !== void 0) {
|
|
51879
|
+
open.end = end;
|
|
51880
|
+
if (marker !== void 0 && closes(fence, marker)) {
|
|
51881
|
+
fence = void 0;
|
|
51882
|
+
open = null;
|
|
51883
|
+
}
|
|
51884
|
+
continue;
|
|
51885
|
+
}
|
|
51886
|
+
if (marker !== void 0) {
|
|
51887
|
+
fence = marker;
|
|
51888
|
+
open = {
|
|
51889
|
+
kind: "code",
|
|
51890
|
+
group: ++group,
|
|
51891
|
+
start,
|
|
51892
|
+
end
|
|
51893
|
+
};
|
|
51894
|
+
out.push(open);
|
|
51895
|
+
continue;
|
|
51896
|
+
}
|
|
51897
|
+
if (line.trim() === "") {
|
|
51898
|
+
open = null;
|
|
51899
|
+
afterBlank = true;
|
|
51900
|
+
continue;
|
|
51901
|
+
}
|
|
51902
|
+
const wasBlank = afterBlank;
|
|
51903
|
+
afterBlank = false;
|
|
51904
|
+
const kind = /^\s*#{1,6}\s/.test(line) ? "heading" : /^\s*\|/.test(line) ? "table" : /^\s*(?:[-*+]|\d+[.)])\s/.test(line) ? "list" : null;
|
|
51905
|
+
if (kind === null && open !== null && (open.kind === "paragraph" || open.kind === "list")) {
|
|
51906
|
+
open.end = end;
|
|
51907
|
+
continue;
|
|
51908
|
+
}
|
|
51909
|
+
const last = out[out.length - 1];
|
|
51910
|
+
const joins = kind !== null && last !== void 0 && last.kind === kind && (kind === "list" || !wasBlank);
|
|
51911
|
+
const block = {
|
|
51912
|
+
kind: kind ?? "paragraph",
|
|
51913
|
+
group: joins ? last.group : ++group,
|
|
51914
|
+
start,
|
|
51915
|
+
end
|
|
51916
|
+
};
|
|
51917
|
+
out.push(block);
|
|
51918
|
+
open = block.kind === "heading" || block.kind === "table" ? null : block;
|
|
51919
|
+
}
|
|
51920
|
+
return out;
|
|
51921
|
+
}
|
|
51922
|
+
/**
|
|
51923
|
+
* Every pointer in `text`, with what it covers, and every problem a writer should be told about: a malformed
|
|
51924
|
+
* pointer, the same key twice, and a pointer line directly under a table row, which markdown reads as another row
|
|
51925
|
+
* of the table rather than a pointer below it (the blank line nobody sees).
|
|
51926
|
+
*/
|
|
51927
|
+
function parsePointers(text) {
|
|
51928
|
+
const cached = parsed.get(text);
|
|
51929
|
+
if (cached !== void 0) return cached;
|
|
51930
|
+
const result = Object.freeze(parseUncached(text));
|
|
51931
|
+
Object.freeze(result.pointers);
|
|
51932
|
+
Object.freeze(result.problems);
|
|
51933
|
+
parsed.set(text, result);
|
|
51934
|
+
if (parsed.size > PARSE_CACHE) parsed.delete(parsed.keys().next().value);
|
|
51935
|
+
return result;
|
|
51936
|
+
}
|
|
51937
|
+
/** How many texts' answers `parsePointers` keeps: enough for a write's before and after, its tool reply, and a
|
|
51938
|
+
* read or two in between, without holding on to a whole plan's bodies. Oldest out first. */
|
|
51939
|
+
var PARSE_CACHE = 16;
|
|
51940
|
+
var parsed = /* @__PURE__ */ new Map();
|
|
51941
|
+
function parseUncached(text) {
|
|
51942
|
+
const masked = maskCode(text);
|
|
51943
|
+
const all = blocks(text);
|
|
51944
|
+
const pointers = [];
|
|
51945
|
+
const problems = [];
|
|
51946
|
+
const seen = /* @__PURE__ */ new Set();
|
|
51947
|
+
for (const match of masked.matchAll(MALFORMED)) {
|
|
51948
|
+
const snippet = text.slice(match.index, match.index + 16).split("\n")[0];
|
|
51949
|
+
problems.push({
|
|
51950
|
+
at: match.index,
|
|
51951
|
+
problem: `"${snippet}" is not a pointer: write [ref <key>], where a key is lowercase letters and digits`
|
|
51952
|
+
});
|
|
51953
|
+
}
|
|
51954
|
+
/** The original text of [from, to) with its pointers taken out, normalised: what a pointer covers. Code stays
|
|
51955
|
+
* in, since a claim can be about a command; only pointers, found in the masked copy, are removed. */
|
|
51956
|
+
const covered = (from, to) => {
|
|
51957
|
+
let out = "";
|
|
51958
|
+
let last = from;
|
|
51959
|
+
for (const m of masked.slice(from, to).matchAll(POINTER)) {
|
|
51960
|
+
out += text.slice(last, from + m.index) + " ";
|
|
51961
|
+
last = from + m.index + m[0].length;
|
|
51962
|
+
}
|
|
51963
|
+
return normaliseClaim(out + text.slice(last, to));
|
|
51964
|
+
};
|
|
51965
|
+
all.forEach((block, index) => {
|
|
51966
|
+
const inBlock = [...masked.slice(block.start, block.end).matchAll(POINTER)].map((m) => ({
|
|
51967
|
+
key: m[1],
|
|
51968
|
+
at: block.start + m.index,
|
|
51969
|
+
written: m[0]
|
|
51970
|
+
}));
|
|
51971
|
+
if (inBlock.length === 0) return;
|
|
51972
|
+
if (normaliseClaim(masked.slice(block.start, block.end).replace(POINTER, " ")) === "") {
|
|
51973
|
+
const above = all.slice(0, index).reverse().find((candidate) => candidate.kind === "code" || normaliseClaim(masked.slice(candidate.start, candidate.end).replace(POINTER, " ")) !== "");
|
|
51974
|
+
if (above !== void 0 && above.kind === "table" && !/\n\s*\n/.test(text.slice(above.end, block.start))) problems.push({
|
|
51975
|
+
at: inBlock[0].at,
|
|
51976
|
+
problem: `put a blank line between the table and [ref ${inBlock[0].key}], or markdown reads it as another row`
|
|
51977
|
+
});
|
|
51978
|
+
const covers = (above === void 0 ? [] : all.filter((candidate) => candidate.group === above.group && candidate.end <= block.start)).map((b) => covered(b.start, b.end)).filter(Boolean).join(" ");
|
|
51979
|
+
for (const p of inBlock) pointers.push({
|
|
51980
|
+
...p,
|
|
51981
|
+
covers: normaliseClaim(covers)
|
|
51982
|
+
});
|
|
51983
|
+
return;
|
|
51984
|
+
}
|
|
51985
|
+
let from = block.start;
|
|
51986
|
+
for (const p of inBlock) {
|
|
51987
|
+
const lineStart = text.lastIndexOf("\n", p.at - 1) + 1;
|
|
51988
|
+
const lineEnd = text.indexOf("\n", p.at) === -1 ? text.length : text.indexOf("\n", p.at);
|
|
51989
|
+
if (block.kind === "list" && lineStart > block.start && normaliseClaim(masked.slice(lineStart, lineEnd).replace(POINTER, " ")) === "") problems.push({
|
|
51990
|
+
at: p.at,
|
|
51991
|
+
problem: `put a blank line between the list and [ref ${p.key}], or markdown reads it as part of the last item`
|
|
51992
|
+
});
|
|
51993
|
+
pointers.push({
|
|
51994
|
+
...p,
|
|
51995
|
+
covers: covered(from, p.at)
|
|
51996
|
+
});
|
|
51997
|
+
from = p.at + p.written.length;
|
|
51998
|
+
}
|
|
51999
|
+
});
|
|
52000
|
+
for (const p of pointers) if (p.covers === "") problems.push({
|
|
52001
|
+
at: p.at,
|
|
52002
|
+
problem: `[ref ${p.key}] has nothing before it to stand behind: put it straight after its claim`
|
|
52003
|
+
});
|
|
52004
|
+
for (const p of pointers) {
|
|
52005
|
+
if (seen.has(p.key)) problems.push({
|
|
52006
|
+
at: p.at,
|
|
52007
|
+
problem: `[ref ${p.key}] appears twice: a key stands behind one claim`
|
|
52008
|
+
});
|
|
52009
|
+
seen.add(p.key);
|
|
52010
|
+
}
|
|
52011
|
+
return {
|
|
52012
|
+
pointers,
|
|
52013
|
+
problems
|
|
52014
|
+
};
|
|
52015
|
+
}
|
|
52016
|
+
/** The text with every expanded pointer reduced to its bare form, `[ref key: ...]` to `[ref key]`, outside code -
|
|
52017
|
+
* what is stored, whatever `get_item` returned and the writer sent back. */
|
|
52018
|
+
function bareForm(text) {
|
|
52019
|
+
const masked = maskCode(text);
|
|
52020
|
+
let out = "";
|
|
52021
|
+
let last = 0;
|
|
52022
|
+
for (const match of masked.matchAll(POINTER)) {
|
|
52023
|
+
out += text.slice(last, match.index) + `[ref ${match[1]}]`;
|
|
52024
|
+
last = match.index + match[0].length;
|
|
52025
|
+
}
|
|
52026
|
+
return out + text.slice(last);
|
|
52027
|
+
}
|
|
52028
|
+
/**
|
|
52029
|
+
* `path:line[-line][:column]@commit`, e.g. `packages/core/src/domain/items.ts:308-339@345a746`. Repo-relative rather
|
|
52030
|
+
* than a hosting provider's URL, so it works in a private repo, a fork and the open export alike; a viewer can still
|
|
52031
|
+
* make a link of it where it knows the host. Null when the detail is not one, which the writing tool refuses.
|
|
52032
|
+
*/
|
|
52033
|
+
function parseCodeRef(detail) {
|
|
52034
|
+
const match = /^([^\s:@][^\s:@]*):([1-9]\d*)(?:-([1-9]\d*))?(?::([1-9]\d*))?@([0-9a-f]{7,40})$/.exec(detail.trim());
|
|
52035
|
+
if (match === null) return null;
|
|
52036
|
+
if (match[1].startsWith("/") || match[1].includes("\\") || match[1].split("/").includes("..")) return null;
|
|
52037
|
+
const from = Number(match[2]);
|
|
52038
|
+
const to = match[3] === void 0 ? from : Number(match[3]);
|
|
52039
|
+
if (to < from) return null;
|
|
52040
|
+
return {
|
|
52041
|
+
path: match[1],
|
|
52042
|
+
from,
|
|
52043
|
+
to,
|
|
52044
|
+
...match[4] === void 0 ? {} : { column: Number(match[4]) },
|
|
52045
|
+
commit: match[5]
|
|
52046
|
+
};
|
|
52047
|
+
}
|
|
52048
|
+
// src/domain/references.ts
|
|
52049
|
+
/**
|
|
52050
|
+
* Source references (`CTX-13`): where a claim in some prose came from.
|
|
52051
|
+
*
|
|
52052
|
+
* The text carries a pointer after the claim, `[ref r7k2]`, and `source_references` carries one row per source
|
|
52053
|
+
* behind it. Everything here is advisory - nothing a writer does to the prose is refused over a reference - except
|
|
52054
|
+
* the one rule the database itself enforces at commit: **a live reference's pointer is in its owner's text**, so a
|
|
52055
|
+
* pointer cannot vanish while its reference still claims to stand behind something. The domain keeps that rule
|
|
52056
|
+
* true for every tool write by retiring, in the same transaction, the references whose pointers an edit removed;
|
|
52057
|
+
* the trigger is the backstop for every other path.
|
|
52058
|
+
*/
|
|
52059
|
+
/**
|
|
52060
|
+
* Retire every live reference of `owner` whose pointer `text` no longer carries, and say which keys they were.
|
|
52061
|
+
*
|
|
52062
|
+
* Called by every write that replaces an owner's prose, inside its transaction, so the commit-time check finds
|
|
52063
|
+
* nothing to object to. Retired rather than deleted: what a claim was once backed by stays legible, and the event
|
|
52064
|
+
* for the edit records which references went with it.
|
|
52065
|
+
*/
|
|
52066
|
+
async function retireRemovedPointers(tx, owner, text) {
|
|
52067
|
+
const ownedBy = "itemId" in owner ? eq(sourceReferences.itemId, owner.itemId) : eq(sourceReferences.sectionId, owner.sectionId);
|
|
52068
|
+
const live = await tx.select({ key: sourceReferences.key }).from(sourceReferences).where(and(ownedBy, isNull(sourceReferences.retiredAt)));
|
|
52069
|
+
const pointed = new Set(parsePointers(text).pointers.map((p) => p.key));
|
|
52070
|
+
const gone = [...new Set(live.map((row) => row.key))].filter((key) => !pointed.has(key)).sort();
|
|
52071
|
+
if (gone.length === 0) return [];
|
|
52072
|
+
const now = timestamp();
|
|
52073
|
+
for (const key of gone) await tx.update(sourceReferences).set({ retiredAt: now }).where(and(ownedBy, eq(sourceReferences.key, key), isNull(sourceReferences.retiredAt)));
|
|
52074
|
+
return gone;
|
|
52075
|
+
}
|
|
52076
|
+
/** Where a claim's source can come from. `agent` is the default for anything unreferenced and is never written. */
|
|
52077
|
+
var SOURCE_KINDS = [
|
|
52078
|
+
"user",
|
|
52079
|
+
"test",
|
|
52080
|
+
"search",
|
|
52081
|
+
"docs",
|
|
52082
|
+
"code"
|
|
52083
|
+
];
|
|
52084
|
+
/** A different advisory-lock namespace from ref allocation's, so the two never queue behind each other. */
|
|
52085
|
+
var REFERENCE_LOCK = 7172013;
|
|
52086
|
+
/**
|
|
52087
|
+
* Add sources to the references in `text`, after it has been written, inside the writing transaction.
|
|
52088
|
+
*
|
|
52089
|
+
* Each key must have its pointer in the text - the source stands behind *that* claim, and records the text it
|
|
52090
|
+
* covers now as what it vouched for - and must not be live under another owner. Serialised per project by an
|
|
52091
|
+
* advisory lock, because "one key, one owner" is a read-then-write: under READ COMMITTED two writers giving one
|
|
52092
|
+
* key to different items at once would both pass the check (found in the `CTX-13` spike, the same race `OPS-2`
|
|
52093
|
+
* fixed for ref allocation). The commit-time trigger would still refuse the second, but as a bare failure; the
|
|
52094
|
+
* lock turns it into a named one.
|
|
52095
|
+
*/
|
|
52096
|
+
async function addSources(tx, projectId, owner, text, sources, actor) {
|
|
52097
|
+
const keys = Object.keys(sources);
|
|
52098
|
+
if (keys.length === 0) return [];
|
|
52099
|
+
await tx.execute(sql`SELECT pg_advisory_xact_lock(${REFERENCE_LOCK}, hashtext(${projectId}))`);
|
|
52100
|
+
const covers = new Map(parsePointers(text).pointers.map((p) => [p.key, p.covers]));
|
|
52101
|
+
const ownerId = "itemId" in owner ? owner.itemId : owner.sectionId;
|
|
52102
|
+
const rows = [];
|
|
52103
|
+
for (const key of keys) {
|
|
52104
|
+
const claim = covers.get(key);
|
|
52105
|
+
if (claim === void 0) throw new Error(`no [ref ${key}] in the text: write it straight after the claim it stands behind, as [ref ${key}]`);
|
|
52106
|
+
if (claim === "") throw new Error(`[ref ${key}] has no claim before it: put it straight after the sentence it stands behind`);
|
|
52107
|
+
if ((await tx.select({
|
|
52108
|
+
itemId: sourceReferences.itemId,
|
|
52109
|
+
sectionId: sourceReferences.sectionId
|
|
52110
|
+
}).from(sourceReferences).where(and(eq(sourceReferences.projectId, projectId), eq(sourceReferences.key, key), isNull(sourceReferences.retiredAt)))).some((row) => (row.itemId ?? row.sectionId) !== ownerId)) throw new Error(`reference ${key} already stands behind a claim elsewhere in this project: choose another key`);
|
|
52111
|
+
for (const source of [sources[key]].flat()) {
|
|
52112
|
+
if (!SOURCE_KINDS.includes(source.source)) throw new Error(`"${source.source}" is not a source: use one of ${SOURCE_KINDS.join(", ")} (unreferenced text is your own reasoning)`);
|
|
52113
|
+
if (source.detail.trim() === "") throw new Error(`a ${source.source} source needs its detail: the command, URL or file, or the user's words verbatim`);
|
|
52114
|
+
if (source.source === "code" && parseCodeRef(source.detail) === null) throw new Error(`"${source.detail}" is not a code reference: write path:line or path:from-to, optionally :column, then @commit, e.g. src/db/schema.ts:120-140@345a746`);
|
|
52115
|
+
rows.push({
|
|
52116
|
+
projectId,
|
|
52117
|
+
key,
|
|
52118
|
+
itemId: "itemId" in owner ? owner.itemId : null,
|
|
52119
|
+
sectionId: "sectionId" in owner ? owner.sectionId : null,
|
|
52120
|
+
source: source.source,
|
|
52121
|
+
detail: source.detail.trim(),
|
|
52122
|
+
quotedText: claim,
|
|
52123
|
+
actor
|
|
52124
|
+
});
|
|
52125
|
+
}
|
|
52126
|
+
}
|
|
52127
|
+
if (rows.length === 0) return [];
|
|
52128
|
+
await tx.insert(sourceReferences).values(rows);
|
|
52129
|
+
return rows.map((row) => ({
|
|
52130
|
+
key: row.key,
|
|
52131
|
+
source: row.source,
|
|
52132
|
+
detail: row.detail
|
|
52133
|
+
})).sort((a, b) => a.key.localeCompare(b.key));
|
|
52134
|
+
}
|
|
52135
|
+
/** The live sources behind an owner's references, oldest first within each key. */
|
|
52136
|
+
async function liveSources(db, owner) {
|
|
52137
|
+
const ownedBy = "itemId" in owner ? eq(sourceReferences.itemId, owner.itemId) : eq(sourceReferences.sectionId, owner.sectionId);
|
|
52138
|
+
return db.select({
|
|
52139
|
+
key: sourceReferences.key,
|
|
52140
|
+
source: sourceReferences.source,
|
|
52141
|
+
detail: sourceReferences.detail,
|
|
52142
|
+
quotedText: sourceReferences.quotedText,
|
|
52143
|
+
recordedAt: sourceReferences.recordedAt
|
|
52144
|
+
}).from(sourceReferences).where(and(ownedBy, isNull(sourceReferences.retiredAt))).orderBy(asc(sourceReferences.key), asc(sourceReferences.recordedAt), asc(sourceReferences.id));
|
|
52145
|
+
}
|
|
52146
|
+
/** A command, a file or a URL longer than this is left out of an expanded pointer: a cut one is noise. */
|
|
52147
|
+
var SHORT_DETAIL = 40;
|
|
52148
|
+
/** A user's words past this are cut, with an ellipsis, rather than dropped: the quote is the evidence. */
|
|
52149
|
+
var QUOTE_SHOWN = 100;
|
|
52150
|
+
/**
|
|
52151
|
+
* How much of a source's detail an expanded pointer shows by default, by kind (`CTX-16`). One length for all of
|
|
52152
|
+
* them hid what made a source useful: every `code` location (45 to 60 characters below `packages/`) and most of
|
|
52153
|
+
* the user's words, so a reader saw "code 2026-11-16" and not which file. So a code location always shows, being
|
|
52154
|
+
* short enough and the most checkable detail there is; a quote shows up to `QUOTE_SHOWN`, cut at a word; anything
|
|
52155
|
+
* else only when it fits whole. `references: "full"` shows every detail in full.
|
|
52156
|
+
*/
|
|
52157
|
+
function detailShown(source, detail) {
|
|
52158
|
+
if (source === "code") return detail;
|
|
52159
|
+
if (source === "user") {
|
|
52160
|
+
if (detail.length <= QUOTE_SHOWN) return `"${detail}"`;
|
|
52161
|
+
const cut = detail.slice(0, QUOTE_SHOWN);
|
|
52162
|
+
return `"${cut.slice(0, Math.max(cut.lastIndexOf(" "), QUOTE_SHOWN / 2)).trimEnd()}..."`;
|
|
52163
|
+
}
|
|
52164
|
+
return detail.length <= SHORT_DETAIL ? detail : null;
|
|
52165
|
+
}
|
|
52166
|
+
/**
|
|
52167
|
+
* A detail as an expanded pointer shows it. Display only, so it is made safe for the round trip rather than kept
|
|
52168
|
+
* exact: an agent sends a body it read straight back, and `bareForm` must find where each expansion ends. A `]` or
|
|
52169
|
+
* a line break would end it early, and a backtick would open a code span that hides what follows; brackets become
|
|
52170
|
+
* parentheses, backticks quotes, and line breaks spaces. The stored detail is untouched.
|
|
52171
|
+
*/
|
|
52172
|
+
var shown = (detail) => detail.replace(/\s*[\r\n]+\s*/g, " ").replace(/\[/g, "(").replace(/\]/g, ")").replace(/`/g, "'");
|
|
52173
|
+
/**
|
|
52174
|
+
* The text a reader is given: every pointer expanded in place with its sources, so an agent sees where a claim
|
|
52175
|
+
* came from beside the claim, at the moment it reads it, without another call. Never stored - writing reduces it
|
|
52176
|
+
* back with `bareForm` - and in the reply only.
|
|
52177
|
+
*
|
|
52178
|
+
* `[ref r7k2: search 2026-08-10, test 2026-08-13 yarn cloud:check, text changed since]` - each source's kind and
|
|
52179
|
+
* date, as much of its detail as `detailShown` gives its kind (all of it, with `full`), `text changed since` when a source vouched for words the
|
|
52180
|
+
* claim no longer says, and `code changed since` when a `code` source's lines are in `codeChanged`. A pointer with
|
|
52181
|
+
* nothing behind it says so, rather than passing as backed.
|
|
52182
|
+
*/
|
|
52183
|
+
function expandPointers(text, sources, full = false, codeChanged = /* @__PURE__ */ new Set()) {
|
|
52184
|
+
const byKey = /* @__PURE__ */ new Map();
|
|
52185
|
+
for (const s of sources) byKey.set(s.key, [...byKey.get(s.key) ?? [], s]);
|
|
52186
|
+
const { pointers } = parsePointers(text);
|
|
52187
|
+
let out = "";
|
|
52188
|
+
let last = 0;
|
|
52189
|
+
for (const p of [...pointers].sort((a, b) => a.at - b.at)) {
|
|
52190
|
+
const behind = byKey.get(p.key) ?? [];
|
|
52191
|
+
const parts = behind.map((s) => {
|
|
52192
|
+
const detail = full ? s.source === "user" ? `"${shown(s.detail)}"` : shown(s.detail) : detailShown(s.source, shown(s.detail));
|
|
52193
|
+
return detail === null ? `${s.source} ${s.recordedAt.slice(0, 10)}` : `${s.source} ${s.recordedAt.slice(0, 10)} ${detail}`;
|
|
52194
|
+
});
|
|
52195
|
+
if (behind.length === 0) parts.push("no reference behind it");
|
|
52196
|
+
else if (normaliseClaim(behind[behind.length - 1].quotedText) !== p.covers) parts.push("text changed since");
|
|
52197
|
+
if (behind.some((s) => s.source === "code" && codeChanged.has(s.detail))) parts.push("code changed since");
|
|
52198
|
+
out += text.slice(last, p.at) + `[ref ${p.key}: ${parts.join(", ")}]`;
|
|
52199
|
+
last = p.at + p.written.length;
|
|
52200
|
+
}
|
|
52201
|
+
return out + text.slice(last);
|
|
52202
|
+
}
|
|
52203
|
+
/**
|
|
52204
|
+
* The sourced claims an edit touched, old text against new, so the writer sees them in the same reply rather than
|
|
52205
|
+
* finding out on the next read. Nothing is refused: a changed claim keeps its sources and will read "text changed
|
|
52206
|
+
* since"; a removed pointer has already been retired.
|
|
52207
|
+
*/
|
|
52208
|
+
function referenceChanges(before, after, sources) {
|
|
52209
|
+
const was = new Map(parsePointers(before).pointers.map((p) => [p.key, p.covers]));
|
|
52210
|
+
const now = new Map(parsePointers(after).pointers.map((p) => [p.key, p.covers]));
|
|
52211
|
+
return [...new Set(sources.map((s) => s.key))].sort().flatMap((key) => {
|
|
52212
|
+
const summary = sources.filter((s) => s.key === key).map((s) => `${s.source} ${s.recordedAt.slice(0, 10)}`).join(", ");
|
|
52213
|
+
if (!now.has(key)) return was.has(key) ? [{
|
|
52214
|
+
key,
|
|
52215
|
+
kind: "retired",
|
|
52216
|
+
sources: summary
|
|
52217
|
+
}] : [];
|
|
52218
|
+
const before = was.get(key);
|
|
52219
|
+
const after = now.get(key);
|
|
52220
|
+
return before !== void 0 && before !== after ? [{
|
|
52221
|
+
key,
|
|
52222
|
+
kind: "changed",
|
|
52223
|
+
sources: summary,
|
|
52224
|
+
before,
|
|
52225
|
+
after
|
|
52226
|
+
}] : [];
|
|
52227
|
+
});
|
|
52228
|
+
}
|
|
51507
52229
|
// src/domain/context.ts
|
|
51508
52230
|
/**
|
|
51509
52231
|
* Context sections (CTX): the project's living narrative as named prose blocks - "Goals", "Assumptions",
|
|
@@ -51548,6 +52270,7 @@ async function orderAfter(tx, projectId, after, movingHeading) {
|
|
|
51548
52270
|
return index * 16 + 8;
|
|
51549
52271
|
}
|
|
51550
52272
|
async function setSection(db, input, actor) {
|
|
52273
|
+
const content = bareForm(input.content);
|
|
51551
52274
|
return mutate(db, actor, async (tx) => {
|
|
51552
52275
|
const existing = maybeOne(await tx.select().from(contextSections).where(and(eq(contextSections.projectId, input.projectId), eq(contextSections.heading, input.heading))));
|
|
51553
52276
|
const now = timestamp();
|
|
@@ -51555,27 +52278,38 @@ async function setSection(db, input, actor) {
|
|
|
51555
52278
|
const after = one(await tx.insert(contextSections).values({
|
|
51556
52279
|
projectId: input.projectId,
|
|
51557
52280
|
heading: input.heading,
|
|
51558
|
-
content
|
|
52281
|
+
content,
|
|
51559
52282
|
sortOrder: order,
|
|
51560
52283
|
createdAt: now,
|
|
51561
52284
|
updatedAt: now
|
|
51562
52285
|
}).onConflictDoUpdate({
|
|
51563
52286
|
target: [contextSections.projectId, contextSections.heading],
|
|
51564
52287
|
set: {
|
|
51565
|
-
content
|
|
52288
|
+
content,
|
|
51566
52289
|
sortOrder: order,
|
|
51567
52290
|
updatedAt: now
|
|
51568
52291
|
}
|
|
51569
52292
|
}).returning());
|
|
52293
|
+
const sourcesBefore = existing ? await liveSources(tx, { sectionId: after.id }) : [];
|
|
52294
|
+
const retiredReferences = existing ? await retireRemovedPointers(tx, { sectionId: after.id }, content) : [];
|
|
52295
|
+
const addedSources = input.sources === void 0 ? [] : await addSources(tx, input.projectId, { sectionId: after.id }, content, input.sources, actor);
|
|
51570
52296
|
return {
|
|
51571
|
-
result:
|
|
52297
|
+
result: {
|
|
52298
|
+
...after,
|
|
52299
|
+
referenceChanges: existing ? referenceChanges(existing.content, content, sourcesBefore) : [],
|
|
52300
|
+
addedSources
|
|
52301
|
+
},
|
|
51572
52302
|
event: {
|
|
51573
52303
|
projectId: input.projectId,
|
|
51574
52304
|
entityType: "context_section",
|
|
51575
52305
|
entityId: after.id,
|
|
51576
52306
|
kind: existing ? "updated" : "created",
|
|
51577
52307
|
before: existing ?? void 0,
|
|
51578
|
-
after
|
|
52308
|
+
after: {
|
|
52309
|
+
...after,
|
|
52310
|
+
...retiredReferences.length > 0 ? { retiredReferences } : {},
|
|
52311
|
+
...addedSources.length > 0 ? { addedSources } : {}
|
|
52312
|
+
}
|
|
51579
52313
|
}
|
|
51580
52314
|
};
|
|
51581
52315
|
});
|
|
@@ -51593,6 +52327,7 @@ async function deleteSection(db, projectId, heading, actor) {
|
|
|
51593
52327
|
return mutate(db, actor, async (tx) => {
|
|
51594
52328
|
const existing = maybeOne(await tx.select().from(contextSections).where(and(eq(contextSections.projectId, projectId), eq(contextSections.heading, heading))));
|
|
51595
52329
|
if (existing === null) throw new Error(`no context section "${heading}"`);
|
|
52330
|
+
const references = await tx.select().from(sourceReferences).where(eq(sourceReferences.sectionId, existing.id));
|
|
51596
52331
|
await tx.delete(contextSections).where(eq(contextSections.id, existing.id));
|
|
51597
52332
|
return {
|
|
51598
52333
|
result: existing,
|
|
@@ -51601,7 +52336,10 @@ async function deleteSection(db, projectId, heading, actor) {
|
|
|
51601
52336
|
entityType: "context_section",
|
|
51602
52337
|
entityId: existing.id,
|
|
51603
52338
|
kind: "deleted",
|
|
51604
|
-
before:
|
|
52339
|
+
before: references.length > 0 ? {
|
|
52340
|
+
...existing,
|
|
52341
|
+
references
|
|
52342
|
+
} : existing
|
|
51605
52343
|
}
|
|
51606
52344
|
};
|
|
51607
52345
|
});
|
|
@@ -51776,6 +52514,122 @@ async function metricsForFeed(db, ownerId) {
|
|
|
51776
52514
|
}
|
|
51777
52515
|
return out;
|
|
51778
52516
|
}
|
|
52517
|
+
// src/mcp/codeDrift.ts
|
|
52518
|
+
/**
|
|
52519
|
+
* Whether the code a `code` source pinned has changed since (`CTX-13`): the lines at the pinned commit against the
|
|
52520
|
+
* same lines of the file as it is now.
|
|
52521
|
+
*
|
|
52522
|
+
* **Only where it is cheap and possible, and only when one item or section is read** - `get_item`, `get_context`
|
|
52523
|
+
* and the pane opening an item; never a listing, a search or `get_project`, and at most `MAX_CODE_CHECKS` a read. The pinned lines are fetched for every
|
|
52524
|
+
* source in one `git cat-file --batch` process (measured 2026-11-15: about 0.25 ms a file batched, 2 ms spawning git
|
|
52525
|
+
* per file), so a read with a few code references pays a few milliseconds. A host with no checkout - the hosted
|
|
52526
|
+
* server - never calls this, and in a checkout without the pinned commit (a shallow clone: CI, a cloud session) the
|
|
52527
|
+
* source is simply not reported: unknown is not changed. The reference still says exactly what a claim rests on, so
|
|
52528
|
+
* an agent relying on it can run the `git show` itself.
|
|
52529
|
+
*
|
|
52530
|
+
* **Moved is not changed.** The pinned lines are looked for anywhere in the file now, not only at their old line
|
|
52531
|
+
* numbers, so an import added above them does not flag every reference below it. Only text that is no longer in the
|
|
52532
|
+
* file at all reads as changed, which is the signal worth having; a reference whose line numbers drifted still
|
|
52533
|
+
* names a commit where they were right.
|
|
52534
|
+
*
|
|
52535
|
+
* Node-only, so it lives with the server rather than beside the shared parser.
|
|
52536
|
+
*/
|
|
52537
|
+
/** Run git and take its output as bytes: `cat-file` sizes its objects in bytes, so a text decode would misalign. */
|
|
52538
|
+
var run = (args, cwd, input) => new Promise((resolve, reject) => {
|
|
52539
|
+
const child = execFile("git", args, {
|
|
52540
|
+
cwd,
|
|
52541
|
+
encoding: "buffer",
|
|
52542
|
+
maxBuffer: 67108864,
|
|
52543
|
+
timeout: 2e3
|
|
52544
|
+
}, (error, stdout) => error ? reject(error) : resolve(stdout));
|
|
52545
|
+
if (input !== void 0) child.stdin?.end(input);
|
|
52546
|
+
});
|
|
52547
|
+
/**
|
|
52548
|
+
* How many `code` sources one read checks. A read is one item or one section, so this is a body that leans on a lot
|
|
52549
|
+
* of code; past it the rest are not checked and so not reported, which is what an unchecked source always means
|
|
52550
|
+
* here - unknown, never changed. Keeps a heavily referenced body from costing a large batch and a scan of each file
|
|
52551
|
+
* on every read.
|
|
52552
|
+
*/
|
|
52553
|
+
var MAX_CODE_CHECKS = 20;
|
|
52554
|
+
/** Each plan file's checkout, looked up once a process: a plan file does not move between repos while it runs. */
|
|
52555
|
+
var checkouts = /* @__PURE__ */ new Map();
|
|
52556
|
+
/** The checkout a plan file sits in, or null when it is not in one (or git is not there to ask). */
|
|
52557
|
+
function checkoutOf(planPath) {
|
|
52558
|
+
let found = checkouts.get(planPath);
|
|
52559
|
+
if (found === void 0) {
|
|
52560
|
+
found = run(["rev-parse", "--show-toplevel"], dirname(planPath)).then((out) => out.toString("utf8").trim() || null, () => null);
|
|
52561
|
+
checkouts.set(planPath, found);
|
|
52562
|
+
}
|
|
52563
|
+
return found;
|
|
52564
|
+
}
|
|
52565
|
+
/**
|
|
52566
|
+
* `git cat-file --batch` output for `commit:path` objects, by request: the file's text, or null for each one git
|
|
52567
|
+
* does not have or that is not a file. Every object's bytes are stepped over whatever its type, since a `tree` or a
|
|
52568
|
+
* `commit` is followed by its content just as a blob is, and losing count there would file every later blob under
|
|
52569
|
+
* the wrong request.
|
|
52570
|
+
*/
|
|
52571
|
+
async function blobsAt(root, refs) {
|
|
52572
|
+
const requests = refs.map((ref) => `${ref.commit}:${ref.path}`);
|
|
52573
|
+
const out = await run(["cat-file", "--batch"], root, requests.join("\n") + "\n");
|
|
52574
|
+
const blobs = [];
|
|
52575
|
+
let at = 0;
|
|
52576
|
+
for (let i = 0; i < requests.length; i++) {
|
|
52577
|
+
const end = out.indexOf(10, at);
|
|
52578
|
+
if (end === -1) break;
|
|
52579
|
+
const header = out.subarray(at, end).toString();
|
|
52580
|
+
at = end + 1;
|
|
52581
|
+
const object = /^\S+ (\S+) (\d+)$/.exec(header);
|
|
52582
|
+
if (object === null) {
|
|
52583
|
+
blobs.push(null);
|
|
52584
|
+
continue;
|
|
52585
|
+
}
|
|
52586
|
+
const size = Number(object[2]);
|
|
52587
|
+
blobs.push(object[1] === "blob" ? out.subarray(at, at + size).toString("utf8") : null);
|
|
52588
|
+
at += size + 1;
|
|
52589
|
+
}
|
|
52590
|
+
return blobs;
|
|
52591
|
+
}
|
|
52592
|
+
/** A file's lines with trailing whitespace dropped, so a reformatted line end never reads as a change. A final
|
|
52593
|
+
* newline ends the last line rather than starting an empty one. */
|
|
52594
|
+
var linesOf = (text) => text.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n").map((line) => line.trimEnd());
|
|
52595
|
+
/** Lines `from` to `to` (1-based, inclusive) of the file, or null when the file is shorter. */
|
|
52596
|
+
function pinned(all, from, to) {
|
|
52597
|
+
return to > all.length ? null : all.slice(from - 1, to);
|
|
52598
|
+
}
|
|
52599
|
+
/** Whether `lines` appear, consecutively and in order, anywhere in `file`. */
|
|
52600
|
+
function contains(file, lines) {
|
|
52601
|
+
for (let start = 0; start + lines.length <= file.length; start++) if (lines.every((line, offset) => file[start + offset] === line)) return true;
|
|
52602
|
+
return false;
|
|
52603
|
+
}
|
|
52604
|
+
/**
|
|
52605
|
+
* The details of the `code` sources whose pinned lines are no longer in the file, in the checkout holding
|
|
52606
|
+
* `planFile` - the plan file that owns what is being read, so a plan spread over several repos checks each against
|
|
52607
|
+
* its own. Empty when there is no plan file (the hosted server passes none), no checkout or no code source; never
|
|
52608
|
+
* throws, since a read must not fail over an optional check.
|
|
52609
|
+
*/
|
|
52610
|
+
async function codeDrift(planFile, sources) {
|
|
52611
|
+
const changed = /* @__PURE__ */ new Set();
|
|
52612
|
+
const code = [...new Set(sources.filter((s) => s.source === "code").map((s) => s.detail))].flatMap((detail) => {
|
|
52613
|
+
const ref = parseCodeRef(detail);
|
|
52614
|
+
return ref === null ? [] : [{
|
|
52615
|
+
detail,
|
|
52616
|
+
ref
|
|
52617
|
+
}];
|
|
52618
|
+
}).slice(0, 20);
|
|
52619
|
+
if (code.length === 0 || planFile === void 0) return changed;
|
|
52620
|
+
try {
|
|
52621
|
+
const root = await checkoutOf(planFile);
|
|
52622
|
+
if (root === null) return changed;
|
|
52623
|
+
const then = await blobsAt(root, code.map((c) => c.ref));
|
|
52624
|
+
await Promise.all(code.map(async ({ detail, ref }, index) => {
|
|
52625
|
+
const was = then[index] === null || then[index] === void 0 ? null : pinned(linesOf(then[index]), ref.from, ref.to);
|
|
52626
|
+
if (was === null) return;
|
|
52627
|
+
const now = await readFile(join(root, ref.path), "utf8").then(linesOf, () => null);
|
|
52628
|
+
if (now === null || !contains(now, was)) changed.add(detail);
|
|
52629
|
+
}));
|
|
52630
|
+
} catch {}
|
|
52631
|
+
return changed;
|
|
52632
|
+
}
|
|
51779
52633
|
// src/domain/dependencies.ts
|
|
51780
52634
|
/**
|
|
51781
52635
|
* The dependency graph (MCP-16, MCP-17): the edges between items, and the two integrity rules that make
|
|
@@ -52240,20 +53094,27 @@ async function createItem(db, input, actor) {
|
|
|
52240
53094
|
sortPath: path,
|
|
52241
53095
|
parentId,
|
|
52242
53096
|
title: input.title,
|
|
52243
|
-
body: input.body
|
|
53097
|
+
body: input.body === void 0 ? null : bareForm(input.body),
|
|
52244
53098
|
status,
|
|
52245
53099
|
startOn,
|
|
52246
53100
|
dueOn
|
|
52247
53101
|
}).returning());
|
|
52248
53102
|
if (input.deps && input.deps.length > 0) await setDependencies(tx, item, input.deps);
|
|
53103
|
+
const addedSources = input.sources === void 0 ? [] : await addSources(tx, input.projectId, { itemId: item.id }, item.body ?? "", input.sources, actor);
|
|
52249
53104
|
return {
|
|
52250
|
-
result:
|
|
53105
|
+
result: {
|
|
53106
|
+
...item,
|
|
53107
|
+
addedSources
|
|
53108
|
+
},
|
|
52251
53109
|
event: {
|
|
52252
53110
|
projectId: input.projectId,
|
|
52253
53111
|
entityType: "item",
|
|
52254
53112
|
entityId: item.id,
|
|
52255
53113
|
kind: "created",
|
|
52256
|
-
after:
|
|
53114
|
+
after: addedSources.length > 0 ? {
|
|
53115
|
+
...item,
|
|
53116
|
+
addedSources
|
|
53117
|
+
} : item
|
|
52257
53118
|
}
|
|
52258
53119
|
};
|
|
52259
53120
|
});
|
|
@@ -52348,21 +53209,29 @@ async function setStatus(db, args, actor) {
|
|
|
52348
53209
|
* touches it; at least one field must be given. The whole before/after is logged, so the edit is auditable
|
|
52349
53210
|
* and reversible like any other mutation. */
|
|
52350
53211
|
async function editItem(db, input, actor) {
|
|
52351
|
-
if (input.title === void 0 && input.body === void 0 && input.deps === void 0 && input.start === void 0 && input.due === void 0) throw new Error("nothing to edit: provide a title, body, deps, start and/or
|
|
53212
|
+
if (input.title === void 0 && input.body === void 0 && input.deps === void 0 && input.start === void 0 && input.due === void 0 && input.sources === void 0) throw new Error("nothing to edit: provide a title, body, deps, start, due and/or sources");
|
|
52352
53213
|
return mutate(db, actor, async (tx) => {
|
|
52353
53214
|
const before = maybeOne(await tx.select().from(items).where(and(eq(items.projectId, input.projectId), eq(items.ref, input.ref))));
|
|
52354
53215
|
if (before === null) throw new Error(`no ticket "${input.ref}" in this project`);
|
|
52355
53216
|
const changes = { updatedAt: timestamp() };
|
|
52356
53217
|
if (input.title !== void 0) changes.title = input.title;
|
|
52357
|
-
if (input.body !== void 0) changes.body = input.body;
|
|
53218
|
+
if (input.body !== void 0) changes.body = bareForm(input.body);
|
|
52358
53219
|
if (input.start !== void 0) changes.startOn = input.start;
|
|
52359
53220
|
if (input.due !== void 0) changes.dueOn = input.due;
|
|
52360
53221
|
assertDates(input.start === void 0 ? before.startOn : input.start, input.due === void 0 ? before.dueOn : input.due);
|
|
52361
53222
|
const after = one(await tx.update(items).set(changes).where(eq(items.id, before.id)).returning());
|
|
53223
|
+
const sourcesBefore = input.body === void 0 ? [] : await liveSources(tx, { itemId: before.id });
|
|
53224
|
+
const retiredReferences = input.body === void 0 ? [] : await retireRemovedPointers(tx, { itemId: before.id }, after.body ?? "");
|
|
53225
|
+
const addedSources = input.sources === void 0 ? [] : await addSources(tx, input.projectId, { itemId: before.id }, after.body ?? "", input.sources, actor);
|
|
53226
|
+
const changedReferences = input.body === void 0 ? [] : referenceChanges(before.body ?? "", after.body ?? "", sourcesBefore);
|
|
52362
53227
|
const beforeDeps = input.deps === void 0 ? void 0 : await dependencyRefs(tx, before.id);
|
|
52363
53228
|
const afterDeps = input.deps === void 0 ? void 0 : await setDependencies(tx, before, input.deps);
|
|
52364
53229
|
return {
|
|
52365
|
-
result:
|
|
53230
|
+
result: {
|
|
53231
|
+
...after,
|
|
53232
|
+
referenceChanges: changedReferences,
|
|
53233
|
+
addedSources
|
|
53234
|
+
},
|
|
52366
53235
|
event: {
|
|
52367
53236
|
projectId: input.projectId,
|
|
52368
53237
|
entityType: "item",
|
|
@@ -52374,7 +53243,9 @@ async function editItem(db, input, actor) {
|
|
|
52374
53243
|
},
|
|
52375
53244
|
after: {
|
|
52376
53245
|
...after,
|
|
52377
|
-
deps: afterDeps
|
|
53246
|
+
deps: afterDeps,
|
|
53247
|
+
...retiredReferences.length > 0 ? { retiredReferences } : {},
|
|
53248
|
+
...addedSources.length > 0 ? { addedSources } : {}
|
|
52378
53249
|
}
|
|
52379
53250
|
}
|
|
52380
53251
|
};
|
|
@@ -52906,16 +53777,20 @@ async function removeAttachment(db, projectId, hash, actor) {
|
|
|
52906
53777
|
/** Comments on one item, all of them: the pane shows the whole record, and a busy item has a few dozen. */
|
|
52907
53778
|
var COMMENT_LIMIT = 500;
|
|
52908
53779
|
/** Null when the owner has no such project, or the project no such live item; a host answers 404. */
|
|
52909
|
-
async function itemFeed(db, ownerId, projectKey, ref) {
|
|
53780
|
+
async function itemFeed(db, ownerId, projectKey, ref, drift) {
|
|
52910
53781
|
const project = await getProjectByKey(db, ownerId, projectKey);
|
|
52911
53782
|
if (project === null) return null;
|
|
52912
53783
|
const item = await getItem(db, project.id, ref);
|
|
52913
53784
|
if (item === null || item.deletedAt !== null) return null;
|
|
52914
|
-
const [comments, attachments] = await Promise.all([
|
|
52915
|
-
|
|
52916
|
-
|
|
52917
|
-
|
|
52918
|
-
|
|
53785
|
+
const [comments, attachments, references] = await Promise.all([
|
|
53786
|
+
listComments(db, {
|
|
53787
|
+
projectId: project.id,
|
|
53788
|
+
itemId: item.id,
|
|
53789
|
+
limit: COMMENT_LIMIT
|
|
53790
|
+
}),
|
|
53791
|
+
listAttachments(db, project.id, ref),
|
|
53792
|
+
liveSources(db, { itemId: item.id })
|
|
53793
|
+
]);
|
|
52919
53794
|
return {
|
|
52920
53795
|
ref: item.ref,
|
|
52921
53796
|
body: item.body ?? "",
|
|
@@ -52932,7 +53807,18 @@ async function itemFeed(db, ownerId, projectKey, ref) {
|
|
|
52932
53807
|
bytes: a.bytes,
|
|
52933
53808
|
...a.caption ? { caption: a.caption } : {},
|
|
52934
53809
|
at: a.createdAt
|
|
52935
|
-
}))
|
|
53810
|
+
})),
|
|
53811
|
+
references: await (async () => {
|
|
53812
|
+
const changed = drift === void 0 ? /* @__PURE__ */ new Set() : await drift(references);
|
|
53813
|
+
return references.map((r) => ({
|
|
53814
|
+
key: r.key,
|
|
53815
|
+
source: r.source,
|
|
53816
|
+
detail: r.detail,
|
|
53817
|
+
text: r.quotedText,
|
|
53818
|
+
at: r.recordedAt,
|
|
53819
|
+
...r.source === "code" && changed.has(r.detail) ? { codeChanged: true } : {}
|
|
53820
|
+
}));
|
|
53821
|
+
})()
|
|
52936
53822
|
};
|
|
52937
53823
|
}
|
|
52938
53824
|
// src/domain/layout.ts
|
|
@@ -53232,7 +54118,11 @@ function createViewerHost(db, sources, store, caller) {
|
|
|
53232
54118
|
if (!sameOrigin(request, bound)) return json(403, { error: "cross-origin writes are refused" });
|
|
53233
54119
|
return null;
|
|
53234
54120
|
};
|
|
53235
|
-
const changes = createChangeFeed((store.paths?.() ?? []).flatMap((path) => [
|
|
54121
|
+
const changes = createChangeFeed((store.paths?.() ?? []).flatMap((path) => [
|
|
54122
|
+
path,
|
|
54123
|
+
layoutPathFor(path),
|
|
54124
|
+
referencesPathFor(path)
|
|
54125
|
+
]), async () => {
|
|
53236
54126
|
await store.refresh();
|
|
53237
54127
|
return (await versionFeed(db, caller.ownerId, store.reloads?.() ?? 0)).version;
|
|
53238
54128
|
});
|
|
@@ -53265,7 +54155,7 @@ function createViewerHost(db, sources, store, caller) {
|
|
|
53265
54155
|
}));
|
|
53266
54156
|
}
|
|
53267
54157
|
if (path === "/api/item") {
|
|
53268
|
-
const found = await itemFeed(db, caller.ownerId, params.get("project") ?? "", params.get("ref") ?? "");
|
|
54158
|
+
const found = await itemFeed(db, caller.ownerId, params.get("project") ?? "", params.get("ref") ?? "", (sources) => codeDrift(store.planFileOf?.(params.get("project") ?? ""), sources));
|
|
53269
54159
|
return found === null ? json(404, { error: `no item "${params.get("ref") ?? ""}" in "${params.get("project") ?? ""}"` }) : json(200, found);
|
|
53270
54160
|
}
|
|
53271
54161
|
if (path === "/api/search") {
|
|
@@ -53580,6 +54470,23 @@ function redact(url) {
|
|
|
53580
54470
|
return "<unparseable connection string>";
|
|
53581
54471
|
}
|
|
53582
54472
|
}
|
|
54473
|
+
// src/mcp/referenceReplies.ts
|
|
54474
|
+
/**
|
|
54475
|
+
* How a writing tool reports what it did to source references (`CTX-13`). Reply formatting, so it lives with the
|
|
54476
|
+
* tools rather than in `domain/`, which returns the facts: the sources added, the sourced claims an edit changed or
|
|
54477
|
+
* retired, and anything about the pointers a writer should hear now rather than from `apm:check` later.
|
|
54478
|
+
*/
|
|
54479
|
+
/** The sourced claims an edit touched, as lines. Empty when nothing sourced was touched, so a reply stays as it was. */
|
|
54480
|
+
function fmtReferenceChanges(changes) {
|
|
54481
|
+
if (changes.length === 0) return "";
|
|
54482
|
+
return `\nsourced claims you changed:\n${changes.map((c) => c.kind === "retired" ? `- ${c.key} (${c.sources}): pointer removed, so its sources were retired` : `- ${c.key} (${c.sources}): "${c.before}" -> "${c.after}". Kept; reads "text changed since" until a source is added for the new text`).join("\n")}`;
|
|
54483
|
+
}
|
|
54484
|
+
/** The keys sources were added to, from what was actually inserted, and the problems with the text's pointers. */
|
|
54485
|
+
function fmtSourcesWritten(added, text) {
|
|
54486
|
+
const keys = [...new Set(added.map((a) => a.key))];
|
|
54487
|
+
const problems = text === null ? [] : parsePointers(text).problems.map((p) => p.problem);
|
|
54488
|
+
return (keys.length > 0 ? `\nsources added to: ${keys.join(", ")}` : "") + (problems.length > 0 ? `\npointer problems (the text is saved; fix these with another edit):\n${problems.map((p) => `- ${p}`).join("\n")}` : "");
|
|
54489
|
+
}
|
|
53583
54490
|
// src/domain/areas.ts
|
|
53584
54491
|
/**
|
|
53585
54492
|
* Areas: the ref prefix that groups items, and the metadata a project can attach to one.
|
|
@@ -53917,6 +54824,18 @@ var date = (what, more) => string().describe(dateText(what, more));
|
|
|
53917
54824
|
* a description set first lands on the string branch inside it, where a client showing the field never looks.
|
|
53918
54825
|
*/
|
|
53919
54826
|
var clearableDate = (what) => string().nullable().describe(dateText(`${what}; null clears it`));
|
|
54827
|
+
/**
|
|
54828
|
+
* Where claims in some prose came from (`CTX-13`), shared by every tool that writes prose. Kept to one parameter's
|
|
54829
|
+
* description rather than a tool of its own, because every tool description sits in every conversation's context:
|
|
54830
|
+
* this is the whole of the guidance, and it says once what the rest of the design does.
|
|
54831
|
+
*/
|
|
54832
|
+
var SOURCE = object({
|
|
54833
|
+
source: _enum(SOURCE_KINDS),
|
|
54834
|
+
detail: string().min(1).max(500).describe("For user, their words verbatim; for test, the command; for search, the URL; for docs, the file or page; for code, path:line or path:from-to@commit (e.g. src/db/schema.ts:120-140@345a746).")
|
|
54835
|
+
});
|
|
54836
|
+
/** Bounds on one write, so a reply that inlines every source stays readable and one call cannot insert thousands. */
|
|
54837
|
+
var MAX_KEYS = 20;
|
|
54838
|
+
var SOURCES = record(string().regex(/^[a-z0-9]{1,16}$/, "a key is 1 to 16 lowercase letters and digits"), union$1([SOURCE, array(SOURCE).min(1).max(5)])).refine((sources) => Object.keys(sources).length > 0, "name at least one key, or leave sources out").refine((sources) => Object.keys(sources).length <= MAX_KEYS, `at most ${MAX_KEYS} keys in one write`).describe("Where claims in this text came from, when it is more than your own reasoning. Write a pointer straight after the claim, like \"Postgres 18.4 runs in production [ref pg18].\", and give its sources here keyed by it: {\"pg18\": {\"source\": \"test\", \"detail\": \"yarn cloud:check\"}}. Keys are short lowercase letters and digits, unused elsewhere in the project. A key already sourced here gains another source. Unreferenced text is yours by default, so reference only claims with a real source.").optional();
|
|
53920
54839
|
var DEPS = array(string()).describe("Refs this item depends on (must be done first). Replaces the whole set; pass [] to clear it. A ref may name another project, as `key:REF` (e.g. `apm:DIST-1`), which is how an edge survives a plan split across store files; it stays valid when that project is not loaded.").optional();
|
|
53921
54840
|
/**
|
|
53922
54841
|
* A list read as prose: "kg", "kg and lb", "kg, lb and stone".
|
|
@@ -54381,7 +55300,7 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54381
55300
|
}));
|
|
54382
55301
|
server.registerTool("set_next", {
|
|
54383
55302
|
annotations: WRITE,
|
|
54384
|
-
description: "Record the order to work in:
|
|
55303
|
+
description: "Record the order to work in: item refs, most important first. Replaces the whole list (pass [] to clear it), because a list you can only append to is one nobody re-examines. Rank it rather than collect into it: each ref's place should say what it beats. This is a stated intention, not a constraint: it does not gate anything, and an item whose dependencies are unmet is flagged rather than refused. get_project reads it back, so this is how an agreed order survives the conversation that produced it.",
|
|
54385
55304
|
inputSchema: {
|
|
54386
55305
|
project: string(),
|
|
54387
55306
|
refs: array(string()).describe("Item refs in the order to work on them. Replaces the whole list; pass [] to clear it.")
|
|
@@ -54405,9 +55324,10 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54405
55324
|
status: _enum(STATUS_VALUES).describe("Defaults to to-do.").optional(),
|
|
54406
55325
|
deps: DEPS,
|
|
54407
55326
|
start: date("When work on it is planned to begin", "Optional; most items have no dates.").optional(),
|
|
54408
|
-
due: date("When it is due", "Optional; most items have no dates.").optional()
|
|
55327
|
+
due: date("When it is due", "Optional; most items have no dates.").optional(),
|
|
55328
|
+
sources: SOURCES
|
|
54409
55329
|
}
|
|
54410
|
-
}, async ({ project, area, parent, ref, title, body, status, deps, start, due }) => guarded(async () => {
|
|
55330
|
+
}, async ({ project, area, parent, ref, title, body, status, deps, start, due, sources }) => guarded(async () => {
|
|
54411
55331
|
const item = await createItem(db, {
|
|
54412
55332
|
projectId: (await resolveProject(db, caller, project)).id,
|
|
54413
55333
|
area,
|
|
@@ -54418,10 +55338,11 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54418
55338
|
status,
|
|
54419
55339
|
deps,
|
|
54420
55340
|
start,
|
|
54421
|
-
due
|
|
55341
|
+
due,
|
|
55342
|
+
sources
|
|
54422
55343
|
}, ACTOR);
|
|
54423
55344
|
await store.persist();
|
|
54424
|
-
return text(`created ${fmtItem(item)}${deps?.length ? `\ndepends on: ${deps.join(", ")}` : ""}`);
|
|
55345
|
+
return text(`created ${fmtItem(item)}${deps?.length ? `\ndepends on: ${deps.join(", ")}` : ""}${fmtSourcesWritten(item.addedSources, item.body)}`);
|
|
54425
55346
|
}));
|
|
54426
55347
|
server.registerTool("list_items", {
|
|
54427
55348
|
annotations: READ,
|
|
@@ -54496,16 +55417,24 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54496
55417
|
}));
|
|
54497
55418
|
server.registerTool("get_item", {
|
|
54498
55419
|
annotations: READ,
|
|
54499
|
-
description: "Read one item in full by its ref: status, title, dependencies, its body (the prose the viewer's detail pane shows), and any comments recorded against it. Use list_items to find the ref.",
|
|
55420
|
+
description: "Read one item in full by its ref: status, title, dependencies, its body (the prose the viewer's detail pane shows), and any comments recorded against it. Use list_items to find the ref. A claim followed by [ref key: ...] has sources, named with their dates; \"text changed since\" means the claim was edited after its source vouched for it.",
|
|
54500
55421
|
inputSchema: {
|
|
54501
55422
|
project: string(),
|
|
54502
|
-
ref: string()
|
|
55423
|
+
ref: string(),
|
|
55424
|
+
references: _enum(["full"]).describe("\"full\" includes every source's detail in full; otherwise a code location always shows, a quote up to about 100 characters, and other details only when short.").optional()
|
|
54503
55425
|
}
|
|
54504
|
-
}, async ({ project, ref }) => guarded(async () => {
|
|
55426
|
+
}, async ({ project, ref, references }) => guarded(async () => {
|
|
54505
55427
|
const p = await resolveProject(db, caller, project);
|
|
54506
|
-
const
|
|
54507
|
-
if (
|
|
54508
|
-
|
|
55428
|
+
const found = await getItemDetail(db, p.id, ref);
|
|
55429
|
+
if (found === null) throw await noSuchRef(db, p, ref);
|
|
55430
|
+
const sources = found.item.body === null ? [] : await liveSources(db, { itemId: found.item.id });
|
|
55431
|
+
return text(fmtItemDetail(found.item.body === null ? found : {
|
|
55432
|
+
...found,
|
|
55433
|
+
item: {
|
|
55434
|
+
...found.item,
|
|
55435
|
+
body: expandPointers(found.item.body, sources, references === "full", await codeDrift(store.planFileOf?.(p.key), sources))
|
|
55436
|
+
}
|
|
55437
|
+
}));
|
|
54509
55438
|
}));
|
|
54510
55439
|
server.registerTool("set_status", {
|
|
54511
55440
|
annotations: WRITE,
|
|
@@ -54536,9 +55465,10 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54536
55465
|
body: string().describe("The item's description, in markdown.").optional(),
|
|
54537
55466
|
deps: DEPS,
|
|
54538
55467
|
start: clearableDate("When work on it is planned to begin").optional(),
|
|
54539
|
-
due: clearableDate("When it is due").optional()
|
|
55468
|
+
due: clearableDate("When it is due").optional(),
|
|
55469
|
+
sources: SOURCES
|
|
54540
55470
|
}
|
|
54541
|
-
}, async ({ project, ref, title, body, deps, start, due }) => guarded(async () => {
|
|
55471
|
+
}, async ({ project, ref, title, body, deps, start, due, sources }) => guarded(async () => {
|
|
54542
55472
|
const p = await resolveProject(db, caller, project);
|
|
54543
55473
|
await resolveRef(db, p, ref);
|
|
54544
55474
|
for (const dep of deps ?? []) if (splitScope(dep) === null) await resolveRef(db, p, dep);
|
|
@@ -54549,10 +55479,11 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54549
55479
|
body,
|
|
54550
55480
|
deps,
|
|
54551
55481
|
start,
|
|
54552
|
-
due
|
|
55482
|
+
due,
|
|
55483
|
+
sources
|
|
54553
55484
|
}, ACTOR);
|
|
54554
55485
|
await store.persist();
|
|
54555
|
-
return text(`edited ${fmtItem(item)}${deps ? `\ndepends on: ${deps.length ? deps.join(", ") : "(nothing)"}` : ""}`);
|
|
55486
|
+
return text(`edited ${fmtItem(item)}${deps ? `\ndepends on: ${deps.length ? deps.join(", ") : "(nothing)"}` : ""}${fmtSourcesWritten(item.addedSources, body === void 0 ? null : item.body)}${fmtReferenceChanges(item.referenceChanges)}`);
|
|
54556
55487
|
}));
|
|
54557
55488
|
server.registerTool("delete_item", {
|
|
54558
55489
|
annotations: WRITE,
|
|
@@ -54661,16 +55592,18 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54661
55592
|
}));
|
|
54662
55593
|
server.registerTool("get_context", {
|
|
54663
55594
|
annotations: READ,
|
|
54664
|
-
description: "Read one context section by its exact heading, so it can be revised from its current content. Use list_context to see the headings; get_project already returns `protocol` in full.",
|
|
55595
|
+
description: "Read one context section by its exact heading, so it can be revised from its current content. Use list_context to see the headings; get_project already returns `protocol` in full. A claim followed by [ref key: ...] has sources, named with their dates; \"text changed since\" means the claim was edited after its source vouched for it.",
|
|
54665
55596
|
inputSchema: {
|
|
54666
55597
|
project: string(),
|
|
54667
|
-
heading: string()
|
|
55598
|
+
heading: string(),
|
|
55599
|
+
references: _enum(["full"]).describe("\"full\" includes every source's detail in full; otherwise a code location always shows, a quote up to about 100 characters, and other details only when short.").optional()
|
|
54668
55600
|
}
|
|
54669
|
-
}, async ({ project, heading }) => guarded(async () => {
|
|
55601
|
+
}, async ({ project, heading, references }) => guarded(async () => {
|
|
54670
55602
|
const p = await resolveProject(db, caller, project);
|
|
54671
55603
|
const section = await getSection(db, p.id, heading);
|
|
54672
55604
|
if (section === null) throw await noSuchSection(db, p, heading);
|
|
54673
|
-
|
|
55605
|
+
const sources = await liveSources(db, { sectionId: section.id });
|
|
55606
|
+
return text(`### ${section.heading}\n${expandPointers(section.content, sources, references === "full", await codeDrift(store.planFileOf?.(p.key), sources))}`);
|
|
54674
55607
|
}));
|
|
54675
55608
|
server.registerTool("set_context", {
|
|
54676
55609
|
annotations: WRITE,
|
|
@@ -54679,20 +55612,22 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54679
55612
|
project: string(),
|
|
54680
55613
|
heading: string(),
|
|
54681
55614
|
content: string().describe("Markdown."),
|
|
54682
|
-
after: string().describe("Place this section immediately after the named one. Pass \"\" to put it first. Omit to append, or to leave an existing section where it is.").optional()
|
|
55615
|
+
after: string().describe("Place this section immediately after the named one. Pass \"\" to put it first. Omit to append, or to leave an existing section where it is.").optional(),
|
|
55616
|
+
sources: SOURCES
|
|
54683
55617
|
}
|
|
54684
|
-
}, async ({ project, heading, content, after }) => guarded(async () => {
|
|
55618
|
+
}, async ({ project, heading, content, after, sources }) => guarded(async () => {
|
|
54685
55619
|
const p = await resolveProject(db, caller, project);
|
|
54686
55620
|
const placement = after === void 0 ? void 0 : after === "" ? null : after;
|
|
54687
55621
|
const section = await setSection(db, {
|
|
54688
55622
|
projectId: p.id,
|
|
54689
55623
|
heading,
|
|
54690
55624
|
content,
|
|
54691
|
-
after: placement
|
|
55625
|
+
after: placement,
|
|
55626
|
+
sources
|
|
54692
55627
|
}, ACTOR);
|
|
54693
55628
|
await store.persist();
|
|
54694
55629
|
const order = (await listSections(db, p.id)).map((s) => s.heading);
|
|
54695
|
-
return text(`set context section "${section.heading}"\norder: ${order.join(" -> ")}`);
|
|
55630
|
+
return text(`set context section "${section.heading}"\norder: ${order.join(" -> ")}${fmtSourcesWritten(section.addedSources, section.content)}${fmtReferenceChanges(section.referenceChanges)}`);
|
|
54696
55631
|
}));
|
|
54697
55632
|
server.registerTool("delete_context", {
|
|
54698
55633
|
annotations: WRITE,
|