attraverso 0.6.1 → 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 +18 -0
- 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 +1032 -99
- package/viewer/assets/{index-xQN8YmLe.js → index-BlJrlICb.js} +27 -20
- package/viewer/assets/{index-CndPhj7n.css → index-D4LIwbZD.css} +1 -1
- package/viewer/index.html +2 -2
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`).
|
|
@@ -50502,6 +50554,23 @@ var attachmentSchema = object({
|
|
|
50502
50554
|
at: string(),
|
|
50503
50555
|
actor: string()
|
|
50504
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));
|
|
50505
50574
|
/** One project's layout: node id -> "x,y", whole numbers on the layout's grid. */
|
|
50506
50575
|
var layoutSchema = record(string(), string().regex(/^-?\d+,-?\d+$/, "a layout position is \"x,y\" in whole numbers"));
|
|
50507
50576
|
var itemSchema = object({
|
|
@@ -50533,7 +50602,8 @@ var itemSchema = object({
|
|
|
50533
50602
|
comments: array(commentSchema).optional(),
|
|
50534
50603
|
/** Accepted for old plan files, never written: see `readComments` (CTX-2). */
|
|
50535
50604
|
notes: array(commentSchema).optional(),
|
|
50536
|
-
attachments: array(attachmentSchema).optional()
|
|
50605
|
+
attachments: array(attachmentSchema).optional(),
|
|
50606
|
+
references: referencesSchema.optional()
|
|
50537
50607
|
});
|
|
50538
50608
|
var retiredSessionSchema = array(unknown());
|
|
50539
50609
|
var projectSchema = object({
|
|
@@ -50548,6 +50618,7 @@ var projectSchema = object({
|
|
|
50548
50618
|
updated_at: string(),
|
|
50549
50619
|
archived_at: string().optional(),
|
|
50550
50620
|
context: record(string(), string()).optional(),
|
|
50621
|
+
context_references: record(string(), referencesSchema).optional(),
|
|
50551
50622
|
areas: array(areaSchema),
|
|
50552
50623
|
items: array(itemSchema),
|
|
50553
50624
|
sessions: retiredSessionSchema.optional(),
|
|
@@ -50605,7 +50676,7 @@ function asPlan(store) {
|
|
|
50605
50676
|
return {
|
|
50606
50677
|
...rest,
|
|
50607
50678
|
next: project.next?.filter((ref) => actionable.has(ref)),
|
|
50608
|
-
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 }) => ({
|
|
50609
50680
|
...item,
|
|
50610
50681
|
deps: item.deps?.filter((ref) => splitScope(ref) !== null || present.has(ref)),
|
|
50611
50682
|
parent: item.parent !== void 0 && present.has(item.parent) ? item.parent : void 0
|
|
@@ -50667,6 +50738,28 @@ async function exportStore(db, ownerId) {
|
|
|
50667
50738
|
actor: a.actor
|
|
50668
50739
|
})) : void 0;
|
|
50669
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
|
+
}
|
|
50670
50763
|
const fmtComments = (rows) => rows.length > 0 ? rows.map((n) => ({
|
|
50671
50764
|
body: n.body,
|
|
50672
50765
|
audience: n.audience,
|
|
@@ -50686,6 +50779,7 @@ async function exportStore(db, ownerId) {
|
|
|
50686
50779
|
updated_at: p.updatedAt,
|
|
50687
50780
|
archived_at: opt(p.archivedAt),
|
|
50688
50781
|
context: sectionRows.length > 0 ? context : void 0,
|
|
50782
|
+
context_references: Object.keys(contextReferences).length > 0 ? contextReferences : void 0,
|
|
50689
50783
|
comments: fmtComments(projectComments),
|
|
50690
50784
|
attachments: fmtAttachments(projectAttachments),
|
|
50691
50785
|
areas: areaRows.map((a) => ({
|
|
@@ -50716,7 +50810,8 @@ async function exportStore(db, ownerId) {
|
|
|
50716
50810
|
closed_at: opt(i.closedAt),
|
|
50717
50811
|
deleted_at: opt(i.deletedAt),
|
|
50718
50812
|
comments: fmtComments(commentsByItem.get(i.id) ?? []),
|
|
50719
|
-
attachments: fmtAttachments(attachmentsByItem.get(i.id) ?? [])
|
|
50813
|
+
attachments: fmtAttachments(attachmentsByItem.get(i.id) ?? []),
|
|
50814
|
+
references: referencesByItem.get(i.id)
|
|
50720
50815
|
};
|
|
50721
50816
|
}),
|
|
50722
50817
|
layout: layoutRows.length > 0 ? Object.fromEntries(layoutRows.map((row) => [row.node, `${row.x},${row.y}`])) : void 0
|
|
@@ -50744,6 +50839,7 @@ async function replaceStore(db, store) {
|
|
|
50744
50839
|
});
|
|
50745
50840
|
}
|
|
50746
50841
|
async function insertStore(tx, store, owner) {
|
|
50842
|
+
await tx.execute(sql`select set_config('attraverso.loading_plan', 'on', true)`);
|
|
50747
50843
|
const ownerId = owner ?? (await ensureUserIn(tx, LOCAL_IDENTITY)).id;
|
|
50748
50844
|
for (const p of store.projects) {
|
|
50749
50845
|
await tx.insert(projects).values({
|
|
@@ -50832,12 +50928,43 @@ async function insertStore(tx, store, owner) {
|
|
|
50832
50928
|
});
|
|
50833
50929
|
if (layoutValues.length > 0) await tx.insert(layoutPositions).values(layoutValues);
|
|
50834
50930
|
const contextEntries = Object.entries(p.context ?? {});
|
|
50835
|
-
|
|
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,
|
|
50836
50956
|
projectId: p.id,
|
|
50837
|
-
|
|
50838
|
-
|
|
50839
|
-
|
|
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
|
|
50840
50966
|
})));
|
|
50967
|
+
if (referenceValues.length > 0) await tx.insert(sourceReferences).values(referenceValues);
|
|
50841
50968
|
const commentValues = [...readComments(p).map((c) => ({
|
|
50842
50969
|
comment: c,
|
|
50843
50970
|
itemId: null
|
|
@@ -50911,6 +51038,67 @@ var stringifyLayout = (layouts) => (0, import_dist.stringify)(layouts, YAML_FORM
|
|
|
50911
51038
|
function parseLayout(text) {
|
|
50912
51039
|
return layoutFileSchema.parse((0, import_dist.parse)(text) ?? {});
|
|
50913
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
|
+
}
|
|
50914
51102
|
function parseStore(text) {
|
|
50915
51103
|
return storeSchema.parse((0, import_dist.parse)(text));
|
|
50916
51104
|
}
|
|
@@ -51090,10 +51278,10 @@ async function writeAtomic(path, text) {
|
|
|
51090
51278
|
*/
|
|
51091
51279
|
async function saveStore(db, path, only) {
|
|
51092
51280
|
const { id: ownerId } = await ensureUser(db, LOCAL_IDENTITY);
|
|
51093
|
-
const { plan,
|
|
51281
|
+
const { plan, sides } = splitSides(restrict(await exportStore(db, ownerId), only));
|
|
51094
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)));
|
|
51095
51284
|
await writeAtomic(path, text);
|
|
51096
|
-
if (Object.keys(layouts).length > 0) await writeAtomic(layoutPathFor(path), stringifyLayout(layouts));
|
|
51097
51285
|
return hashOf$1(text);
|
|
51098
51286
|
}
|
|
51099
51287
|
/** The store narrowed to some project ids, preserving `exportStore`'s order so the result stays deterministic. */
|
|
@@ -51123,11 +51311,61 @@ async function stampOf(path) {
|
|
|
51123
51311
|
return null;
|
|
51124
51312
|
}
|
|
51125
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
|
+
}
|
|
51126
51364
|
/**
|
|
51127
|
-
* A
|
|
51128
|
-
*
|
|
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.
|
|
51129
51367
|
*/
|
|
51130
|
-
async function
|
|
51368
|
+
async function readSideFile(kind, path) {
|
|
51131
51369
|
let text;
|
|
51132
51370
|
try {
|
|
51133
51371
|
text = await readFile(path, "utf8");
|
|
@@ -51136,12 +51374,12 @@ async function readLayoutFile(path) {
|
|
|
51136
51374
|
}
|
|
51137
51375
|
try {
|
|
51138
51376
|
return {
|
|
51139
|
-
|
|
51377
|
+
side: kind.parse(text),
|
|
51140
51378
|
hash: hashOf$1(text),
|
|
51141
51379
|
stamp: await stampOf(path)
|
|
51142
51380
|
};
|
|
51143
51381
|
} catch (cause) {
|
|
51144
|
-
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)}`);
|
|
51145
51383
|
}
|
|
51146
51384
|
}
|
|
51147
51385
|
/**
|
|
@@ -51178,30 +51416,31 @@ function createStoreFile(where) {
|
|
|
51178
51416
|
file.keys = new Set(store.projects.map((project) => project.key));
|
|
51179
51417
|
};
|
|
51180
51418
|
/**
|
|
51181
|
-
* The
|
|
51182
|
-
* by path rather than hung off each plan file, because two plan
|
|
51183
|
-
* `*.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.
|
|
51184
51422
|
*/
|
|
51185
|
-
const
|
|
51186
|
-
for (const file of files) {
|
|
51187
|
-
const path =
|
|
51188
|
-
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,
|
|
51189
51428
|
known: null,
|
|
51190
51429
|
stamp: null,
|
|
51191
51430
|
owners: []
|
|
51192
51431
|
};
|
|
51193
51432
|
entry.owners.push(file);
|
|
51194
|
-
|
|
51433
|
+
sideFiles.set(path, entry);
|
|
51195
51434
|
}
|
|
51196
51435
|
/**
|
|
51197
|
-
* Read every
|
|
51198
|
-
*
|
|
51199
|
-
* 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.
|
|
51200
51439
|
*/
|
|
51201
|
-
const
|
|
51440
|
+
const overlaySides = async (loaded) => {
|
|
51202
51441
|
const out = [...loaded];
|
|
51203
|
-
for (const [path, entry] of
|
|
51204
|
-
const read = await
|
|
51442
|
+
for (const [path, entry] of sideFiles) {
|
|
51443
|
+
const read = await readSideFile(entry.kind, path);
|
|
51205
51444
|
if (read === null) continue;
|
|
51206
51445
|
entry.known = read.hash;
|
|
51207
51446
|
entry.stamp = read.stamp;
|
|
@@ -51209,7 +51448,7 @@ function createStoreFile(where) {
|
|
|
51209
51448
|
const one = out[index];
|
|
51210
51449
|
if (entry.owners.includes(one.file)) out[index] = {
|
|
51211
51450
|
file: one.file,
|
|
51212
|
-
store:
|
|
51451
|
+
store: entry.kind.merge(one.store, read.side)
|
|
51213
51452
|
};
|
|
51214
51453
|
}
|
|
51215
51454
|
}
|
|
@@ -51288,7 +51527,7 @@ function createStoreFile(where) {
|
|
|
51288
51527
|
store
|
|
51289
51528
|
})));
|
|
51290
51529
|
let created = false;
|
|
51291
|
-
for (const { file, store } of await
|
|
51530
|
+
for (const { file, store } of await overlaySides(loaded)) {
|
|
51292
51531
|
claim(file, store);
|
|
51293
51532
|
await importStore(db, store);
|
|
51294
51533
|
}
|
|
@@ -51324,18 +51563,18 @@ function createStoreFile(where) {
|
|
|
51324
51563
|
stamp: current
|
|
51325
51564
|
});
|
|
51326
51565
|
}
|
|
51327
|
-
let
|
|
51328
|
-
for (const [path, entry] of
|
|
51566
|
+
let sideMoved = false;
|
|
51567
|
+
for (const [path, entry] of sideFiles) {
|
|
51329
51568
|
const current = await stampOf(path);
|
|
51330
51569
|
if (current === null || current === entry.stamp) continue;
|
|
51331
51570
|
if (await hashOnDisk(path) === entry.known) entry.stamp = current;
|
|
51332
|
-
else
|
|
51571
|
+
else sideMoved = true;
|
|
51333
51572
|
}
|
|
51334
|
-
if (fresh.size === 0 && !
|
|
51573
|
+
if (fresh.size === 0 && !sideMoved) return false;
|
|
51335
51574
|
const { id: ownerId } = await ensureUser(db, LOCAL_IDENTITY);
|
|
51336
51575
|
const loadedNow = await exportStore(db, ownerId);
|
|
51337
51576
|
const claimed = new Set(files.flatMap((file) => [...file.ids]));
|
|
51338
|
-
const union = await
|
|
51577
|
+
const union = await overlaySides(files.map((file) => {
|
|
51339
51578
|
const moved = fresh.get(file);
|
|
51340
51579
|
if (moved !== void 0) return {
|
|
51341
51580
|
file,
|
|
@@ -51364,38 +51603,56 @@ function createStoreFile(where) {
|
|
|
51364
51603
|
return true;
|
|
51365
51604
|
}),
|
|
51366
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
|
+
};
|
|
51367
51609
|
for (const file of files) {
|
|
51368
51610
|
const current = await hashOnDisk(file.path);
|
|
51369
|
-
if (file.known !== null && current !== file.known)
|
|
51370
|
-
|
|
51371
|
-
|
|
51372
|
-
|
|
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);
|
|
51373
51617
|
}
|
|
51374
51618
|
const { id: ownerId } = await ensureUser(db, LOCAL_IDENTITY);
|
|
51375
51619
|
const full = await exportStore(db, ownerId);
|
|
51376
51620
|
const claimed = new Set(files.flatMap((file) => [...file.ids]));
|
|
51377
|
-
const
|
|
51621
|
+
const sidesOf = /* @__PURE__ */ new Map();
|
|
51622
|
+
const plans = [];
|
|
51378
51623
|
for (const file of files) {
|
|
51379
51624
|
const mine = full.projects.filter((p) => file.ids.has(p.id) || file === primary && !claimed.has(p.id));
|
|
51380
|
-
const { plan,
|
|
51381
|
-
|
|
51625
|
+
const { plan, sides } = splitSides({ projects: mine });
|
|
51626
|
+
sidesOf.set(file, sides);
|
|
51382
51627
|
const text = stringifyStore(plan);
|
|
51383
|
-
|
|
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) {
|
|
51384
51650
|
if (hash === file.known) continue;
|
|
51385
51651
|
await writeAtomic(file.path, text);
|
|
51386
51652
|
claim(file, { projects: mine });
|
|
51387
51653
|
await remember(file, hash);
|
|
51388
51654
|
}
|
|
51389
|
-
|
|
51390
|
-
const layouts = Object.assign({}, ...entry.owners.map((owner) => layoutsOf.get(owner) ?? {}));
|
|
51391
|
-
if (Object.keys(layouts).length === 0 && entry.known === null) continue;
|
|
51392
|
-
const text = stringifyLayout(layouts);
|
|
51393
|
-
const hash = hashOf$1(text);
|
|
51394
|
-
if (hash === entry.known) continue;
|
|
51395
|
-
await writeAtomic(path, text);
|
|
51396
|
-
entry.known = hash;
|
|
51397
|
-
entry.stamp = await stampOf(path);
|
|
51398
|
-
}
|
|
51655
|
+
await writeSides([LAYOUT]);
|
|
51399
51656
|
})
|
|
51400
51657
|
};
|
|
51401
51658
|
}
|
|
@@ -51404,6 +51661,7 @@ var accessTo = (store, db) => ({
|
|
|
51404
51661
|
refresh: () => store.refresh(db),
|
|
51405
51662
|
reloads: () => store.reloads(),
|
|
51406
51663
|
paths: () => store.paths,
|
|
51664
|
+
planFileOf: (key) => store.fileOf(key),
|
|
51407
51665
|
appendMeasurements: (records) => store.appendMeasurements(records)
|
|
51408
51666
|
});
|
|
51409
51667
|
// src/media/store.ts
|
|
@@ -51506,6 +51764,468 @@ function createUnavailableMediaStore(reason) {
|
|
|
51506
51764
|
}
|
|
51507
51765
|
};
|
|
51508
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
|
+
}
|
|
51509
52229
|
// src/domain/context.ts
|
|
51510
52230
|
/**
|
|
51511
52231
|
* Context sections (CTX): the project's living narrative as named prose blocks - "Goals", "Assumptions",
|
|
@@ -51550,6 +52270,7 @@ async function orderAfter(tx, projectId, after, movingHeading) {
|
|
|
51550
52270
|
return index * 16 + 8;
|
|
51551
52271
|
}
|
|
51552
52272
|
async function setSection(db, input, actor) {
|
|
52273
|
+
const content = bareForm(input.content);
|
|
51553
52274
|
return mutate(db, actor, async (tx) => {
|
|
51554
52275
|
const existing = maybeOne(await tx.select().from(contextSections).where(and(eq(contextSections.projectId, input.projectId), eq(contextSections.heading, input.heading))));
|
|
51555
52276
|
const now = timestamp();
|
|
@@ -51557,27 +52278,38 @@ async function setSection(db, input, actor) {
|
|
|
51557
52278
|
const after = one(await tx.insert(contextSections).values({
|
|
51558
52279
|
projectId: input.projectId,
|
|
51559
52280
|
heading: input.heading,
|
|
51560
|
-
content
|
|
52281
|
+
content,
|
|
51561
52282
|
sortOrder: order,
|
|
51562
52283
|
createdAt: now,
|
|
51563
52284
|
updatedAt: now
|
|
51564
52285
|
}).onConflictDoUpdate({
|
|
51565
52286
|
target: [contextSections.projectId, contextSections.heading],
|
|
51566
52287
|
set: {
|
|
51567
|
-
content
|
|
52288
|
+
content,
|
|
51568
52289
|
sortOrder: order,
|
|
51569
52290
|
updatedAt: now
|
|
51570
52291
|
}
|
|
51571
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);
|
|
51572
52296
|
return {
|
|
51573
|
-
result:
|
|
52297
|
+
result: {
|
|
52298
|
+
...after,
|
|
52299
|
+
referenceChanges: existing ? referenceChanges(existing.content, content, sourcesBefore) : [],
|
|
52300
|
+
addedSources
|
|
52301
|
+
},
|
|
51574
52302
|
event: {
|
|
51575
52303
|
projectId: input.projectId,
|
|
51576
52304
|
entityType: "context_section",
|
|
51577
52305
|
entityId: after.id,
|
|
51578
52306
|
kind: existing ? "updated" : "created",
|
|
51579
52307
|
before: existing ?? void 0,
|
|
51580
|
-
after
|
|
52308
|
+
after: {
|
|
52309
|
+
...after,
|
|
52310
|
+
...retiredReferences.length > 0 ? { retiredReferences } : {},
|
|
52311
|
+
...addedSources.length > 0 ? { addedSources } : {}
|
|
52312
|
+
}
|
|
51581
52313
|
}
|
|
51582
52314
|
};
|
|
51583
52315
|
});
|
|
@@ -51595,6 +52327,7 @@ async function deleteSection(db, projectId, heading, actor) {
|
|
|
51595
52327
|
return mutate(db, actor, async (tx) => {
|
|
51596
52328
|
const existing = maybeOne(await tx.select().from(contextSections).where(and(eq(contextSections.projectId, projectId), eq(contextSections.heading, heading))));
|
|
51597
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));
|
|
51598
52331
|
await tx.delete(contextSections).where(eq(contextSections.id, existing.id));
|
|
51599
52332
|
return {
|
|
51600
52333
|
result: existing,
|
|
@@ -51603,7 +52336,10 @@ async function deleteSection(db, projectId, heading, actor) {
|
|
|
51603
52336
|
entityType: "context_section",
|
|
51604
52337
|
entityId: existing.id,
|
|
51605
52338
|
kind: "deleted",
|
|
51606
|
-
before:
|
|
52339
|
+
before: references.length > 0 ? {
|
|
52340
|
+
...existing,
|
|
52341
|
+
references
|
|
52342
|
+
} : existing
|
|
51607
52343
|
}
|
|
51608
52344
|
};
|
|
51609
52345
|
});
|
|
@@ -51778,6 +52514,122 @@ async function metricsForFeed(db, ownerId) {
|
|
|
51778
52514
|
}
|
|
51779
52515
|
return out;
|
|
51780
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
|
+
}
|
|
51781
52633
|
// src/domain/dependencies.ts
|
|
51782
52634
|
/**
|
|
51783
52635
|
* The dependency graph (MCP-16, MCP-17): the edges between items, and the two integrity rules that make
|
|
@@ -52242,20 +53094,27 @@ async function createItem(db, input, actor) {
|
|
|
52242
53094
|
sortPath: path,
|
|
52243
53095
|
parentId,
|
|
52244
53096
|
title: input.title,
|
|
52245
|
-
body: input.body
|
|
53097
|
+
body: input.body === void 0 ? null : bareForm(input.body),
|
|
52246
53098
|
status,
|
|
52247
53099
|
startOn,
|
|
52248
53100
|
dueOn
|
|
52249
53101
|
}).returning());
|
|
52250
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);
|
|
52251
53104
|
return {
|
|
52252
|
-
result:
|
|
53105
|
+
result: {
|
|
53106
|
+
...item,
|
|
53107
|
+
addedSources
|
|
53108
|
+
},
|
|
52253
53109
|
event: {
|
|
52254
53110
|
projectId: input.projectId,
|
|
52255
53111
|
entityType: "item",
|
|
52256
53112
|
entityId: item.id,
|
|
52257
53113
|
kind: "created",
|
|
52258
|
-
after:
|
|
53114
|
+
after: addedSources.length > 0 ? {
|
|
53115
|
+
...item,
|
|
53116
|
+
addedSources
|
|
53117
|
+
} : item
|
|
52259
53118
|
}
|
|
52260
53119
|
};
|
|
52261
53120
|
});
|
|
@@ -52350,21 +53209,29 @@ async function setStatus(db, args, actor) {
|
|
|
52350
53209
|
* touches it; at least one field must be given. The whole before/after is logged, so the edit is auditable
|
|
52351
53210
|
* and reversible like any other mutation. */
|
|
52352
53211
|
async function editItem(db, input, actor) {
|
|
52353
|
-
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");
|
|
52354
53213
|
return mutate(db, actor, async (tx) => {
|
|
52355
53214
|
const before = maybeOne(await tx.select().from(items).where(and(eq(items.projectId, input.projectId), eq(items.ref, input.ref))));
|
|
52356
53215
|
if (before === null) throw new Error(`no ticket "${input.ref}" in this project`);
|
|
52357
53216
|
const changes = { updatedAt: timestamp() };
|
|
52358
53217
|
if (input.title !== void 0) changes.title = input.title;
|
|
52359
|
-
if (input.body !== void 0) changes.body = input.body;
|
|
53218
|
+
if (input.body !== void 0) changes.body = bareForm(input.body);
|
|
52360
53219
|
if (input.start !== void 0) changes.startOn = input.start;
|
|
52361
53220
|
if (input.due !== void 0) changes.dueOn = input.due;
|
|
52362
53221
|
assertDates(input.start === void 0 ? before.startOn : input.start, input.due === void 0 ? before.dueOn : input.due);
|
|
52363
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);
|
|
52364
53227
|
const beforeDeps = input.deps === void 0 ? void 0 : await dependencyRefs(tx, before.id);
|
|
52365
53228
|
const afterDeps = input.deps === void 0 ? void 0 : await setDependencies(tx, before, input.deps);
|
|
52366
53229
|
return {
|
|
52367
|
-
result:
|
|
53230
|
+
result: {
|
|
53231
|
+
...after,
|
|
53232
|
+
referenceChanges: changedReferences,
|
|
53233
|
+
addedSources
|
|
53234
|
+
},
|
|
52368
53235
|
event: {
|
|
52369
53236
|
projectId: input.projectId,
|
|
52370
53237
|
entityType: "item",
|
|
@@ -52376,7 +53243,9 @@ async function editItem(db, input, actor) {
|
|
|
52376
53243
|
},
|
|
52377
53244
|
after: {
|
|
52378
53245
|
...after,
|
|
52379
|
-
deps: afterDeps
|
|
53246
|
+
deps: afterDeps,
|
|
53247
|
+
...retiredReferences.length > 0 ? { retiredReferences } : {},
|
|
53248
|
+
...addedSources.length > 0 ? { addedSources } : {}
|
|
52380
53249
|
}
|
|
52381
53250
|
}
|
|
52382
53251
|
};
|
|
@@ -52908,16 +53777,20 @@ async function removeAttachment(db, projectId, hash, actor) {
|
|
|
52908
53777
|
/** Comments on one item, all of them: the pane shows the whole record, and a busy item has a few dozen. */
|
|
52909
53778
|
var COMMENT_LIMIT = 500;
|
|
52910
53779
|
/** Null when the owner has no such project, or the project no such live item; a host answers 404. */
|
|
52911
|
-
async function itemFeed(db, ownerId, projectKey, ref) {
|
|
53780
|
+
async function itemFeed(db, ownerId, projectKey, ref, drift) {
|
|
52912
53781
|
const project = await getProjectByKey(db, ownerId, projectKey);
|
|
52913
53782
|
if (project === null) return null;
|
|
52914
53783
|
const item = await getItem(db, project.id, ref);
|
|
52915
53784
|
if (item === null || item.deletedAt !== null) return null;
|
|
52916
|
-
const [comments, attachments] = await Promise.all([
|
|
52917
|
-
|
|
52918
|
-
|
|
52919
|
-
|
|
52920
|
-
|
|
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
|
+
]);
|
|
52921
53794
|
return {
|
|
52922
53795
|
ref: item.ref,
|
|
52923
53796
|
body: item.body ?? "",
|
|
@@ -52934,7 +53807,18 @@ async function itemFeed(db, ownerId, projectKey, ref) {
|
|
|
52934
53807
|
bytes: a.bytes,
|
|
52935
53808
|
...a.caption ? { caption: a.caption } : {},
|
|
52936
53809
|
at: a.createdAt
|
|
52937
|
-
}))
|
|
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
|
+
})()
|
|
52938
53822
|
};
|
|
52939
53823
|
}
|
|
52940
53824
|
// src/domain/layout.ts
|
|
@@ -53234,7 +54118,11 @@ function createViewerHost(db, sources, store, caller) {
|
|
|
53234
54118
|
if (!sameOrigin(request, bound)) return json(403, { error: "cross-origin writes are refused" });
|
|
53235
54119
|
return null;
|
|
53236
54120
|
};
|
|
53237
|
-
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 () => {
|
|
53238
54126
|
await store.refresh();
|
|
53239
54127
|
return (await versionFeed(db, caller.ownerId, store.reloads?.() ?? 0)).version;
|
|
53240
54128
|
});
|
|
@@ -53267,7 +54155,7 @@ function createViewerHost(db, sources, store, caller) {
|
|
|
53267
54155
|
}));
|
|
53268
54156
|
}
|
|
53269
54157
|
if (path === "/api/item") {
|
|
53270
|
-
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));
|
|
53271
54159
|
return found === null ? json(404, { error: `no item "${params.get("ref") ?? ""}" in "${params.get("project") ?? ""}"` }) : json(200, found);
|
|
53272
54160
|
}
|
|
53273
54161
|
if (path === "/api/search") {
|
|
@@ -53582,6 +54470,23 @@ function redact(url) {
|
|
|
53582
54470
|
return "<unparseable connection string>";
|
|
53583
54471
|
}
|
|
53584
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
|
+
}
|
|
53585
54490
|
// src/domain/areas.ts
|
|
53586
54491
|
/**
|
|
53587
54492
|
* Areas: the ref prefix that groups items, and the metadata a project can attach to one.
|
|
@@ -53919,6 +54824,18 @@ var date = (what, more) => string().describe(dateText(what, more));
|
|
|
53919
54824
|
* a description set first lands on the string branch inside it, where a client showing the field never looks.
|
|
53920
54825
|
*/
|
|
53921
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();
|
|
53922
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();
|
|
53923
54840
|
/**
|
|
53924
54841
|
* A list read as prose: "kg", "kg and lb", "kg, lb and stone".
|
|
@@ -54407,9 +55324,10 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54407
55324
|
status: _enum(STATUS_VALUES).describe("Defaults to to-do.").optional(),
|
|
54408
55325
|
deps: DEPS,
|
|
54409
55326
|
start: date("When work on it is planned to begin", "Optional; most items have no dates.").optional(),
|
|
54410
|
-
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
|
|
54411
55329
|
}
|
|
54412
|
-
}, 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 () => {
|
|
54413
55331
|
const item = await createItem(db, {
|
|
54414
55332
|
projectId: (await resolveProject(db, caller, project)).id,
|
|
54415
55333
|
area,
|
|
@@ -54420,10 +55338,11 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54420
55338
|
status,
|
|
54421
55339
|
deps,
|
|
54422
55340
|
start,
|
|
54423
|
-
due
|
|
55341
|
+
due,
|
|
55342
|
+
sources
|
|
54424
55343
|
}, ACTOR);
|
|
54425
55344
|
await store.persist();
|
|
54426
|
-
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)}`);
|
|
54427
55346
|
}));
|
|
54428
55347
|
server.registerTool("list_items", {
|
|
54429
55348
|
annotations: READ,
|
|
@@ -54498,16 +55417,24 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54498
55417
|
}));
|
|
54499
55418
|
server.registerTool("get_item", {
|
|
54500
55419
|
annotations: READ,
|
|
54501
|
-
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.",
|
|
54502
55421
|
inputSchema: {
|
|
54503
55422
|
project: string(),
|
|
54504
|
-
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()
|
|
54505
55425
|
}
|
|
54506
|
-
}, async ({ project, ref }) => guarded(async () => {
|
|
55426
|
+
}, async ({ project, ref, references }) => guarded(async () => {
|
|
54507
55427
|
const p = await resolveProject(db, caller, project);
|
|
54508
|
-
const
|
|
54509
|
-
if (
|
|
54510
|
-
|
|
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
|
+
}));
|
|
54511
55438
|
}));
|
|
54512
55439
|
server.registerTool("set_status", {
|
|
54513
55440
|
annotations: WRITE,
|
|
@@ -54538,9 +55465,10 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54538
55465
|
body: string().describe("The item's description, in markdown.").optional(),
|
|
54539
55466
|
deps: DEPS,
|
|
54540
55467
|
start: clearableDate("When work on it is planned to begin").optional(),
|
|
54541
|
-
due: clearableDate("When it is due").optional()
|
|
55468
|
+
due: clearableDate("When it is due").optional(),
|
|
55469
|
+
sources: SOURCES
|
|
54542
55470
|
}
|
|
54543
|
-
}, async ({ project, ref, title, body, deps, start, due }) => guarded(async () => {
|
|
55471
|
+
}, async ({ project, ref, title, body, deps, start, due, sources }) => guarded(async () => {
|
|
54544
55472
|
const p = await resolveProject(db, caller, project);
|
|
54545
55473
|
await resolveRef(db, p, ref);
|
|
54546
55474
|
for (const dep of deps ?? []) if (splitScope(dep) === null) await resolveRef(db, p, dep);
|
|
@@ -54551,10 +55479,11 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54551
55479
|
body,
|
|
54552
55480
|
deps,
|
|
54553
55481
|
start,
|
|
54554
|
-
due
|
|
55482
|
+
due,
|
|
55483
|
+
sources
|
|
54555
55484
|
}, ACTOR);
|
|
54556
55485
|
await store.persist();
|
|
54557
|
-
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)}`);
|
|
54558
55487
|
}));
|
|
54559
55488
|
server.registerTool("delete_item", {
|
|
54560
55489
|
annotations: WRITE,
|
|
@@ -54663,16 +55592,18 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54663
55592
|
}));
|
|
54664
55593
|
server.registerTool("get_context", {
|
|
54665
55594
|
annotations: READ,
|
|
54666
|
-
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.",
|
|
54667
55596
|
inputSchema: {
|
|
54668
55597
|
project: string(),
|
|
54669
|
-
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()
|
|
54670
55600
|
}
|
|
54671
|
-
}, async ({ project, heading }) => guarded(async () => {
|
|
55601
|
+
}, async ({ project, heading, references }) => guarded(async () => {
|
|
54672
55602
|
const p = await resolveProject(db, caller, project);
|
|
54673
55603
|
const section = await getSection(db, p.id, heading);
|
|
54674
55604
|
if (section === null) throw await noSuchSection(db, p, heading);
|
|
54675
|
-
|
|
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))}`);
|
|
54676
55607
|
}));
|
|
54677
55608
|
server.registerTool("set_context", {
|
|
54678
55609
|
annotations: WRITE,
|
|
@@ -54681,20 +55612,22 @@ function registerTools(server, db, store, viewer, caller) {
|
|
|
54681
55612
|
project: string(),
|
|
54682
55613
|
heading: string(),
|
|
54683
55614
|
content: string().describe("Markdown."),
|
|
54684
|
-
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
|
|
54685
55617
|
}
|
|
54686
|
-
}, async ({ project, heading, content, after }) => guarded(async () => {
|
|
55618
|
+
}, async ({ project, heading, content, after, sources }) => guarded(async () => {
|
|
54687
55619
|
const p = await resolveProject(db, caller, project);
|
|
54688
55620
|
const placement = after === void 0 ? void 0 : after === "" ? null : after;
|
|
54689
55621
|
const section = await setSection(db, {
|
|
54690
55622
|
projectId: p.id,
|
|
54691
55623
|
heading,
|
|
54692
55624
|
content,
|
|
54693
|
-
after: placement
|
|
55625
|
+
after: placement,
|
|
55626
|
+
sources
|
|
54694
55627
|
}, ACTOR);
|
|
54695
55628
|
await store.persist();
|
|
54696
55629
|
const order = (await listSections(db, p.id)).map((s) => s.heading);
|
|
54697
|
-
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)}`);
|
|
54698
55631
|
}));
|
|
54699
55632
|
server.registerTool("delete_context", {
|
|
54700
55633
|
annotations: WRITE,
|