@phren/cli 0.3.70 → 0.3.72
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/dist/bridge/browser-env.d.ts +5 -0
- package/dist/bridge/browser-env.js +86 -0
- package/dist/bridge/browser-protocol.d.ts +120 -0
- package/dist/bridge/browser-protocol.js +70 -0
- package/dist/bridge/browser-recordings.d.ts +63 -0
- package/dist/bridge/browser-recordings.js +148 -0
- package/dist/bridge/browser-registry.d.ts +64 -0
- package/dist/bridge/browser-registry.js +262 -0
- package/dist/bridge/browser-routes.d.ts +4 -0
- package/dist/bridge/browser-routes.js +39 -0
- package/dist/bridge/browser-shim/phren-playwright.cjs +184 -0
- package/dist/bridge/browser-socket.d.ts +2 -0
- package/dist/bridge/browser-socket.js +10 -0
- package/dist/bridge/browser-stream.d.ts +3 -0
- package/dist/bridge/browser-stream.js +129 -0
- package/dist/bridge/claude-question-dialog.js +32 -7
- package/dist/bridge/dispatch.d.ts +10 -0
- package/dist/bridge/dispatch.js +3 -1
- package/dist/bridge/dream-schedule.d.ts +133 -0
- package/dist/bridge/dream-schedule.js +322 -0
- package/dist/bridge/herdr.js +15 -6
- package/dist/bridge/install.js +4 -0
- package/dist/bridge/launch-brief.d.ts +11 -0
- package/dist/bridge/launch-brief.js +22 -0
- package/dist/bridge/pane-status.js +1 -1
- package/dist/bridge/server-routes.d.ts +3 -0
- package/dist/bridge/server-routes.js +15 -15
- package/dist/bridge/server-stream.d.ts +4 -0
- package/dist/bridge/server-stream.js +24 -5
- package/dist/bridge/server.js +23 -3
- package/dist/bridge/session-move.d.ts +10 -4
- package/dist/bridge/session-move.js +65 -34
- package/dist/bridge/simulator-stream.d.ts +2 -0
- package/dist/bridge/simulator-stream.js +2 -0
- package/dist/bridge/tab-activity.d.ts +2 -0
- package/dist/bridge/tab-activity.js +15 -2
- package/dist/bridge/task-routes.d.ts +20 -16
- package/dist/bridge/task-routes.js +1 -1
- package/dist/bridge/terminal-herdr.js +2 -1
- package/dist/bridge/terminal-tmux.js +2 -1
- package/dist/bridge/worker-reports.js +15 -3
- package/dist/bridge-hook.mjs +36819 -35219
- package/dist/capabilities/mcp.js +1 -1
- package/dist/cli/config-dreaming.d.ts +7 -0
- package/dist/cli/config-dreaming.js +72 -0
- package/dist/cli/config.js +6 -0
- package/dist/cli/dream.d.ts +59 -0
- package/dist/cli/dream.js +315 -0
- package/dist/cli/namespaces-tasks.js +14 -0
- package/dist/cli-registry.js +24 -1
- package/dist/config/dreaming.d.ts +82 -0
- package/dist/config/dreaming.js +195 -0
- package/dist/config/resolve.js +11 -0
- package/dist/config/schema.d.ts +4 -4
- package/dist/config/schema.js +157 -1
- package/dist/content/citation-freshness.js +6 -0
- package/dist/content/learning.d.ts +1 -0
- package/dist/content/learning.js +2 -0
- package/dist/data/access.d.ts +1 -1
- package/dist/data/access.js +3 -1
- package/dist/data/task-contract.d.ts +5 -4
- package/dist/data/tasks.d.ts +5 -0
- package/dist/data/tasks.js +28 -2
- package/dist/dream/apply.d.ts +69 -0
- package/dist/dream/apply.js +372 -0
- package/dist/dream/budget.d.ts +78 -0
- package/dist/dream/budget.js +180 -0
- package/dist/dream/collect.d.ts +86 -0
- package/dist/dream/collect.js +449 -0
- package/dist/dream/eval/dream-adapter.d.ts +16 -0
- package/dist/dream/eval/dream-adapter.js +21 -0
- package/dist/dream/eval/fixture.d.ts +53 -0
- package/dist/dream/eval/fixture.js +172 -0
- package/dist/dream/eval/index.d.ts +40 -0
- package/dist/dream/eval/index.js +78 -0
- package/dist/dream/eval/score.d.ts +34 -0
- package/dist/dream/eval/score.js +99 -0
- package/dist/dream/eval/scripted-model.d.ts +19 -0
- package/dist/dream/eval/scripted-model.js +70 -0
- package/dist/dream/pages.d.ts +68 -0
- package/dist/dream/pages.js +220 -0
- package/dist/dream/privacy.d.ts +3 -0
- package/dist/dream/privacy.js +18 -0
- package/dist/dream/prompt.d.ts +13 -0
- package/dist/dream/prompt.js +84 -0
- package/dist/dream/run.d.ts +98 -0
- package/dist/dream/run.js +317 -0
- package/dist/dream/types.d.ts +74 -0
- package/dist/dream/types.js +4 -0
- package/dist/finding/lifecycle.d.ts +2 -2
- package/dist/finding/lifecycle.js +5 -2
- package/dist/finding/versions.d.ts +4 -0
- package/dist/finding/versions.js +28 -0
- package/dist/index.js +1 -0
- package/dist/modules/registry.js +9 -7
- package/dist/project-config.d.ts +3 -0
- package/dist/task/merge-links.d.ts +38 -0
- package/dist/task/merge-links.js +45 -0
- package/dist/task/reconcile.d.ts +39 -0
- package/dist/task/reconcile.js +201 -0
- package/dist/task/report-links.d.ts +10 -0
- package/dist/task/report-links.js +47 -0
- package/dist/tools/config.js +46 -4
- package/dist/tools/dispatch.js +2 -1
- package/dist/tools/dream.d.ts +3 -0
- package/dist/tools/dream.js +123 -0
- package/dist/tools/tasks.js +4 -1
- package/package.json +1 -1
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The dreaming eval's fixture: a small store and synthetic transcripts that
|
|
3
|
+
* contain exactly the situations a dream should handle.
|
|
4
|
+
*
|
|
5
|
+
* 1. A finding contradicted by a later transcript (the dev server moved off port 3000).
|
|
6
|
+
* 2. Two findings that say the same thing (migrate before tests).
|
|
7
|
+
* 3. A decision stated in a transcript and never saved (Postgres advisory locks
|
|
8
|
+
* instead of Redis for the rate limiter).
|
|
9
|
+
* 4. Truths over the injected budget, some recently cited and some stale.
|
|
10
|
+
* plus a correct finding nothing should touch (the control).
|
|
11
|
+
*
|
|
12
|
+
* Transcripts are written where phren's readers look for them under `home`:
|
|
13
|
+
* a Claude Code session (`.claude/projects/<cwd>/<id>.jsonl`) and a Codex
|
|
14
|
+
* rollout (`.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`), both with the
|
|
15
|
+
* project's checkout as their cwd.
|
|
16
|
+
*/
|
|
17
|
+
import * as fs from "fs";
|
|
18
|
+
import * as path from "path";
|
|
19
|
+
import { execFileSync } from "child_process";
|
|
20
|
+
import { writeRootManifest } from "../../shared.js";
|
|
21
|
+
export const EVAL_PROJECT = "lantern";
|
|
22
|
+
/** Fixed clock for the fixture; transcripts fall inside the default 24 h lookback from here. */
|
|
23
|
+
export const EVAL_NOW = new Date("2026-11-06T12:00:00.000Z");
|
|
24
|
+
export const EVAL_BUDGET_KB = 8;
|
|
25
|
+
export const FIDS = {
|
|
26
|
+
contradicted: "a1000001",
|
|
27
|
+
dupA: "a1000002",
|
|
28
|
+
dupB: "a1000003",
|
|
29
|
+
control: "a1000004",
|
|
30
|
+
};
|
|
31
|
+
export const CLAUDE_SESSION = "5f0c2a7e-1b7d-4c55-9a52-0d9a6b3e7c11";
|
|
32
|
+
export const CODEX_SESSION = "0199a3c4-7d10-7b2e-9f61-2c8d4e5a6b70";
|
|
33
|
+
/** Phrases the scripted model and the scorer key on. */
|
|
34
|
+
export const FACTS = {
|
|
35
|
+
newPort: "4100",
|
|
36
|
+
decisionKeyword: "advisory lock",
|
|
37
|
+
decisionPattern: /advisory[- ]lock/i,
|
|
38
|
+
decisionTopicPattern: /rate[- ]?limit/i,
|
|
39
|
+
};
|
|
40
|
+
const FRESH_TRUTHS = [
|
|
41
|
+
"The production database is Postgres 16 on the managed cluster; never point local tooling at it.",
|
|
42
|
+
"Releases are cut from main by the release workflow only; never publish from a laptop.",
|
|
43
|
+
"The public API is versioned under /v2; /v1 routes are frozen and only take security fixes.",
|
|
44
|
+
"Feature flags live in config/flags.yaml and are read once at boot; a change needs a restart.",
|
|
45
|
+
"Customer data never leaves the eu-west region; analytics exports go through the anonymizer job.",
|
|
46
|
+
"The worker queue retries a job five times with exponential backoff, then parks it in the dead-letter table.",
|
|
47
|
+
];
|
|
48
|
+
const STALE_COMPONENTS = [
|
|
49
|
+
"Travis CI pipeline", "Heroku review apps", "Grunt asset build", "Mongo session store", "Bower front-end deps",
|
|
50
|
+
"Python 2 export script", "Jenkins nightly job", "Vagrant dev box", "Gulp sprite task", "old Elastic 5 cluster",
|
|
51
|
+
"Memcached page cache", "CoffeeScript admin panel", "Capistrano deploy", "Sidekiq 4 queue", "Node 12 runtime",
|
|
52
|
+
"Webpack 3 config", "Flow type stubs", "Karma browser tests", "Ansible 2.4 playbooks", "Mesos scheduler",
|
|
53
|
+
"Consul 0.9 KV", "Selenium grid", "Rails 4 admin", "Angular 1 dashboard", "Ruby 2.3 cron box",
|
|
54
|
+
"Puppet manifests", "Docker Swarm stack", "Nagios checks", "ZooKeeper locks", "Graphite metrics",
|
|
55
|
+
];
|
|
56
|
+
function staleTruth(component, i) {
|
|
57
|
+
return `Legacy note ${i + 1}: the ${component} needs its credentials rotated by hand every quarter, `
|
|
58
|
+
+ `and its config lives in the ops wiki rather than the repo, so check the wiki page before touching it; `
|
|
59
|
+
+ `the on-call runbook still links to it from the incident checklist section.`;
|
|
60
|
+
}
|
|
61
|
+
function claudeProjectDir(home, cwd) {
|
|
62
|
+
return path.join(home, ".claude", "projects", cwd.replace(/[^a-zA-Z0-9]/g, "-"));
|
|
63
|
+
}
|
|
64
|
+
function iso(base, minutesBefore) {
|
|
65
|
+
return new Date(base.getTime() - minutesBefore * 60_000).toISOString();
|
|
66
|
+
}
|
|
67
|
+
function jsonl(rows) {
|
|
68
|
+
return rows.map((r) => JSON.stringify(r)).join("\n") + "\n";
|
|
69
|
+
}
|
|
70
|
+
function writeClaudeTranscript(home, repo, now) {
|
|
71
|
+
const dir = claudeProjectDir(home, repo);
|
|
72
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
73
|
+
const base = { sessionId: CLAUDE_SESSION, cwd: repo, version: "2.1.0", gitBranch: "main", userType: "external", isSidechain: false };
|
|
74
|
+
let n = 0;
|
|
75
|
+
const user = (minutes, text) => ({ ...base, type: "user", uuid: `c-u-${++n}`, timestamp: iso(now, minutes), message: { role: "user", content: text } });
|
|
76
|
+
const assistant = (minutes, content) => ({ ...base, type: "assistant", uuid: `c-a-${++n}`, timestamp: iso(now, minutes), message: { role: "assistant", model: "claude-opus-5-5", content } });
|
|
77
|
+
const toolResult = (minutes, id, text) => ({ ...base, type: "user", uuid: `c-r-${++n}`, timestamp: iso(now, minutes), message: { role: "user", content: [{ type: "tool_result", tool_use_id: id, content: text }] } });
|
|
78
|
+
fs.writeFileSync(path.join(dir, `${CLAUDE_SESSION}.jsonl`), jsonl([
|
|
79
|
+
user(300, "The web app now runs its own dev server on 3000, so the API clashes with it. Move the API dev server to port 4100 and update anything that assumes 3000."),
|
|
80
|
+
assistant(299, [
|
|
81
|
+
{ type: "text", text: "I'll move the API dev server from 3000 to 4100. Let me find every place the port is set." },
|
|
82
|
+
{ type: "tool_use", id: "toolu_01", name: "Grep", input: { pattern: "3000", path: "." } },
|
|
83
|
+
]),
|
|
84
|
+
toolResult(298, "toolu_01", "src/server.ts:12: const port = Number(process.env.PORT ?? 3000);\n.env.example:3:PORT=3000\n" + "x".repeat(4000)),
|
|
85
|
+
assistant(297, [
|
|
86
|
+
{ type: "tool_use", id: "toolu_02", name: "Edit", input: { file_path: "src/server.ts", old_string: "3000", new_string: "4100" } },
|
|
87
|
+
]),
|
|
88
|
+
toolResult(296, "toolu_02", "The file src/server.ts has been updated."),
|
|
89
|
+
assistant(295, [{ type: "text", text: "Done. The API dev server now listens on port 4100 (src/server.ts and .env.example). Port 3000 is the web app's." }]),
|
|
90
|
+
user(290, "Thanks. Run the tests."),
|
|
91
|
+
assistant(289, [{ type: "tool_use", id: "toolu_03", name: "Bash", input: { command: "pnpm test" } }]),
|
|
92
|
+
toolResult(288, "toolu_03", "error: relation \"accounts\" does not exist\n" + "y".repeat(3000)),
|
|
93
|
+
assistant(287, [{ type: "text", text: "The tests failed on a missing table, as usual when migrations have not run. Running `pnpm db:migrate` first." }]),
|
|
94
|
+
]));
|
|
95
|
+
}
|
|
96
|
+
function writeCodexTranscript(home, repo, now) {
|
|
97
|
+
const day = now.toISOString().slice(0, 10).split("-");
|
|
98
|
+
const dir = path.join(home, ".codex", "sessions", day[0], day[1], day[2]);
|
|
99
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
100
|
+
const started = iso(now, 120);
|
|
101
|
+
const stamp = started.replace(/[:.]/g, "-").slice(0, 19);
|
|
102
|
+
const msg = (minutes, role, text) => ({
|
|
103
|
+
timestamp: iso(now, minutes), type: "response_item",
|
|
104
|
+
payload: { type: "message", role, content: [{ type: role === "user" ? "input_text" : "output_text", text }] },
|
|
105
|
+
});
|
|
106
|
+
fs.writeFileSync(path.join(dir, `rollout-${stamp}-${CODEX_SESSION}.jsonl`), jsonl([
|
|
107
|
+
{ timestamp: started, type: "session_meta", payload: { id: CODEX_SESSION, timestamp: started, cwd: repo, originator: "codex_cli_rs", cli_version: "0.157.0", source: "cli" } },
|
|
108
|
+
msg(119, "user", "The rate limiter needs a store. Redis is not available in the customer's on-prem install, so we can't use it there."),
|
|
109
|
+
msg(118, "assistant", "Two options: an in-process limiter (wrong across replicas) or Postgres. Postgres advisory locks give us a shared limiter with no new dependency."),
|
|
110
|
+
msg(117, "user", "Decision: drop Redis for the rate limiter and use Postgres advisory locks everywhere, on-prem and cloud alike, so there is one code path."),
|
|
111
|
+
{ timestamp: iso(now, 116), type: "response_item", payload: { type: "function_call", name: "shell", arguments: JSON.stringify({ command: ["rg", "redis", "src/"] }), call_id: "call_1" } },
|
|
112
|
+
{ timestamp: iso(now, 115), type: "response_item", payload: { type: "function_call_output", call_id: "call_1", output: "src/ratelimit/redis.ts:1:import Redis from 'ioredis'\n" + "z".repeat(3000) } },
|
|
113
|
+
msg(114, "assistant", "Understood: the rate limiter moves to Postgres advisory locks and the Redis adapter goes away. I'll start with src/ratelimit/."),
|
|
114
|
+
]));
|
|
115
|
+
}
|
|
116
|
+
function writeStore(store, repo, now) {
|
|
117
|
+
const projectDir = path.join(store, EVAL_PROJECT);
|
|
118
|
+
fs.mkdirSync(path.join(store, "global"), { recursive: true });
|
|
119
|
+
fs.mkdirSync(path.join(store, ".runtime"), { recursive: true });
|
|
120
|
+
fs.mkdirSync(path.join(projectDir, "reference", "pages"), { recursive: true });
|
|
121
|
+
writeRootManifest(store, { version: 1, installMode: "shared", syncMode: "managed-git" });
|
|
122
|
+
fs.writeFileSync(path.join(projectDir, "phren.project.yaml"), `sourcePath: ${repo}\n`);
|
|
123
|
+
fs.writeFileSync(path.join(projectDir, "summary.md"), `# ${EVAL_PROJECT}\n\nAn HTTP API with a Postgres database, a worker queue and a web front end.\n`);
|
|
124
|
+
fs.writeFileSync(path.join(projectDir, "FINDINGS.md"), [
|
|
125
|
+
`# ${EVAL_PROJECT} Findings`,
|
|
126
|
+
"",
|
|
127
|
+
"## 2026-10-20",
|
|
128
|
+
"",
|
|
129
|
+
`- [pattern] The API dev server listens on port 3000; the web app proxies /api to localhost:3000 <!-- fid:${FIDS.contradicted} --> <!-- created: 2026-10-20 -->`,
|
|
130
|
+
`- [pitfall] Run \`pnpm db:migrate\` before \`pnpm test\`, or the suite fails with missing-table errors <!-- fid:${FIDS.dupA} --> <!-- created: 2026-10-20 -->`,
|
|
131
|
+
"",
|
|
132
|
+
"## 2026-10-28",
|
|
133
|
+
"",
|
|
134
|
+
`- [pitfall] Tests fail with "relation does not exist" unless migrations ran first (pnpm db:migrate) <!-- fid:${FIDS.dupB} --> <!-- created: 2026-10-28 -->`,
|
|
135
|
+
`- [decision] Structured logging uses pino with one child logger per request, keyed by request id <!-- fid:${FIDS.control} --> <!-- created: 2026-10-28 -->`,
|
|
136
|
+
"",
|
|
137
|
+
].join("\n"));
|
|
138
|
+
const freshTruths = FRESH_TRUTHS;
|
|
139
|
+
const staleTruths = STALE_COMPONENTS.map(staleTruth);
|
|
140
|
+
// upsertCanonical's layout: newest first under "## Truths".
|
|
141
|
+
const lines = [...freshTruths.map((t) => `- ${t} _(added 2026-10-01)_`), ...staleTruths.map((t) => `- ${t} _(added 2026-03-01)_`)];
|
|
142
|
+
fs.writeFileSync(path.join(projectDir, "truths.md"), `# ${EVAL_PROJECT} Truths\n\n## Truths\n\n${lines.join("\n")}\n`);
|
|
143
|
+
// Fresh truths were found by searches this week; stale ones never were.
|
|
144
|
+
fs.writeFileSync(path.join(store, ".runtime", "lookup-events.jsonl"), freshTruths.map((t, i) => JSON.stringify({
|
|
145
|
+
at: iso(now, 60 * 24 * (i + 1)), query: "deploy", project: EVAL_PROJECT, filename: "truths.md", type: "canonical", snippet: t, source: "search",
|
|
146
|
+
})).join("\n") + "\n");
|
|
147
|
+
return { staleTruths, freshTruths };
|
|
148
|
+
}
|
|
149
|
+
function initRepo(repo, now) {
|
|
150
|
+
fs.mkdirSync(path.join(repo, "src"), { recursive: true });
|
|
151
|
+
fs.writeFileSync(path.join(repo, "src", "server.ts"), "export const port = Number(process.env.PORT ?? 4100);\n");
|
|
152
|
+
try {
|
|
153
|
+
const env = { ...process.env, GIT_AUTHOR_DATE: iso(now, 280), GIT_COMMITTER_DATE: iso(now, 280) };
|
|
154
|
+
const git = (...args) => execFileSync("git", args, { cwd: repo, env, stdio: "ignore" });
|
|
155
|
+
git("init", "-q");
|
|
156
|
+
git("-c", "user.name=eval", "-c", "user.email=eval@example.invalid", "add", ".");
|
|
157
|
+
git("-c", "user.name=eval", "-c", "user.email=eval@example.invalid", "commit", "-q", "-m", "Move the API dev server to port 4100");
|
|
158
|
+
}
|
|
159
|
+
catch { /* git is optional for the eval: collect treats a missing log as empty */ }
|
|
160
|
+
}
|
|
161
|
+
/** Builds the fixture under `root` (an empty directory the caller owns and removes). */
|
|
162
|
+
export function buildEvalFixture(root, now = EVAL_NOW) {
|
|
163
|
+
const store = path.join(root, "store");
|
|
164
|
+
const home = path.join(root, "home");
|
|
165
|
+
const repo = path.join(root, "src", EVAL_PROJECT);
|
|
166
|
+
fs.mkdirSync(home, { recursive: true });
|
|
167
|
+
initRepo(repo, now);
|
|
168
|
+
const { staleTruths, freshTruths } = writeStore(store, repo, now);
|
|
169
|
+
writeClaudeTranscript(home, repo, now);
|
|
170
|
+
writeCodexTranscript(home, repo, now);
|
|
171
|
+
return { root, store, home, repo, project: EVAL_PROJECT, now, budgetKB: EVAL_BUDGET_KB, staleTruths, freshTruths };
|
|
172
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The dreaming eval: build the fixture in a temp directory, run `dream()` on it
|
|
3
|
+
* in propose mode, read back what it proposed and score it.
|
|
4
|
+
*
|
|
5
|
+
* `model: "scripted"` (the default, used by tests) answers from the prompt with
|
|
6
|
+
* `scriptedRunner`. `model: "real"` runs the project's helper (`claude -p`) with
|
|
7
|
+
* the owner's own environment, for `phren dream eval --real`; it costs a real
|
|
8
|
+
* model call.
|
|
9
|
+
*
|
|
10
|
+
* The run points PHREN_PATH and HOME at the fixture so collect reads its
|
|
11
|
+
* transcripts and nothing else. Both are restored afterwards; do not run the
|
|
12
|
+
* eval concurrently with other work in the same process.
|
|
13
|
+
*/
|
|
14
|
+
import { type DreamFn } from "./dream-adapter.js";
|
|
15
|
+
import { type EvalScore } from "./score.js";
|
|
16
|
+
export { buildEvalFixture, EVAL_PROJECT, EVAL_NOW, FIDS } from "./fixture.js";
|
|
17
|
+
export { scoreChanges, formatScore, extractChanges, readLatestDream } from "./score.js";
|
|
18
|
+
export { scriptedRunner, scriptedChanges, scriptedReply } from "./scripted-model.js";
|
|
19
|
+
export type { EvalFixture } from "./fixture.js";
|
|
20
|
+
export type { EvalScore, EvalCheck } from "./score.js";
|
|
21
|
+
export interface DreamEvalOptions {
|
|
22
|
+
model?: "scripted" | "real";
|
|
23
|
+
/** B's `dream`; defaults to the integrated one. */
|
|
24
|
+
dream?: DreamFn;
|
|
25
|
+
/** Keep the fixture directory for inspection instead of removing it. */
|
|
26
|
+
keep?: boolean;
|
|
27
|
+
/** Use this empty directory instead of a fresh temp one (implies keep). */
|
|
28
|
+
root?: string;
|
|
29
|
+
}
|
|
30
|
+
export interface DreamEvalReport {
|
|
31
|
+
model: "scripted" | "real";
|
|
32
|
+
score: EvalScore;
|
|
33
|
+
/** Where the fixture was built; removed unless `keep` or `root` was given. */
|
|
34
|
+
root: string;
|
|
35
|
+
kept: boolean;
|
|
36
|
+
/** Prompts the scripted model saw (empty for a real run). */
|
|
37
|
+
prompts: string[];
|
|
38
|
+
error?: string;
|
|
39
|
+
}
|
|
40
|
+
export declare function runDreamEval(opts?: DreamEvalOptions): Promise<DreamEvalReport>;
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The dreaming eval: build the fixture in a temp directory, run `dream()` on it
|
|
3
|
+
* in propose mode, read back what it proposed and score it.
|
|
4
|
+
*
|
|
5
|
+
* `model: "scripted"` (the default, used by tests) answers from the prompt with
|
|
6
|
+
* `scriptedRunner`. `model: "real"` runs the project's helper (`claude -p`) with
|
|
7
|
+
* the owner's own environment, for `phren dream eval --real`; it costs a real
|
|
8
|
+
* model call.
|
|
9
|
+
*
|
|
10
|
+
* The run points PHREN_PATH and HOME at the fixture so collect reads its
|
|
11
|
+
* transcripts and nothing else. Both are restored afterwards; do not run the
|
|
12
|
+
* eval concurrently with other work in the same process.
|
|
13
|
+
*/
|
|
14
|
+
import * as fs from "fs";
|
|
15
|
+
import * as os from "os";
|
|
16
|
+
import * as path from "path";
|
|
17
|
+
import { helperEnv, helperFor, runHelper } from "../../bridge/helper.js";
|
|
18
|
+
import { overBudget } from "../budget.js";
|
|
19
|
+
import { defaultDream } from "./dream-adapter.js";
|
|
20
|
+
import { buildEvalFixture } from "./fixture.js";
|
|
21
|
+
import { extractChanges, readLatestDream, scoreChanges } from "./score.js";
|
|
22
|
+
import { scriptedRunner } from "./scripted-model.js";
|
|
23
|
+
export { buildEvalFixture, EVAL_PROJECT, EVAL_NOW, FIDS } from "./fixture.js";
|
|
24
|
+
export { scoreChanges, formatScore, extractChanges, readLatestDream } from "./score.js";
|
|
25
|
+
export { scriptedRunner, scriptedChanges, scriptedReply } from "./scripted-model.js";
|
|
26
|
+
const ENV_KEYS = ["PHREN_PATH", "HOME", "USERPROFILE", "CLAUDE_CONFIG_DIR", "CODEX_HOME", "COPILOT_HOME"];
|
|
27
|
+
function swapEnv(fixture) {
|
|
28
|
+
const saved = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
|
|
29
|
+
process.env.PHREN_PATH = fixture.store;
|
|
30
|
+
process.env.HOME = fixture.home;
|
|
31
|
+
process.env.USERPROFILE = fixture.home;
|
|
32
|
+
delete process.env.CLAUDE_CONFIG_DIR;
|
|
33
|
+
delete process.env.CODEX_HOME;
|
|
34
|
+
delete process.env.COPILOT_HOME;
|
|
35
|
+
return () => {
|
|
36
|
+
for (const k of ENV_KEYS) {
|
|
37
|
+
if (saved[k] === undefined)
|
|
38
|
+
delete process.env[k];
|
|
39
|
+
else
|
|
40
|
+
process.env[k] = saved[k];
|
|
41
|
+
}
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
/** The real helper, with the owner's environment (their Claude login) rather than the fixture's HOME. */
|
|
45
|
+
function realRunner(fixture, ownerEnv) {
|
|
46
|
+
const choice = helperFor(fixture.store, fixture.project, ownerEnv);
|
|
47
|
+
return (requested, options) => runHelper({ ...requested, home: choice.home }, { ...options, env: helperEnv(choice.home, ownerEnv) });
|
|
48
|
+
}
|
|
49
|
+
export async function runDreamEval(opts = {}) {
|
|
50
|
+
const model = opts.model ?? "scripted";
|
|
51
|
+
const dream = opts.dream ?? defaultDream;
|
|
52
|
+
const root = opts.root ?? fs.mkdtempSync(path.join(os.tmpdir(), "phren-dream-eval-"));
|
|
53
|
+
const kept = Boolean(opts.keep || opts.root);
|
|
54
|
+
const fixture = buildEvalFixture(root);
|
|
55
|
+
const before = overBudget(fixture.store, fixture.project, fixture.budgetKB, { skipLookupLog: true });
|
|
56
|
+
const prompts = [];
|
|
57
|
+
const ownerEnv = { ...process.env };
|
|
58
|
+
const runner = model === "scripted" ? scriptedRunner(fixture, prompts) : realRunner(fixture, ownerEnv);
|
|
59
|
+
const restore = swapEnv(fixture);
|
|
60
|
+
let result;
|
|
61
|
+
let error;
|
|
62
|
+
try {
|
|
63
|
+
result = await dream(fixture.project, { mode: "propose", force: true, now: fixture.now, runner });
|
|
64
|
+
}
|
|
65
|
+
catch (err) {
|
|
66
|
+
error = err instanceof Error ? err.message : String(err);
|
|
67
|
+
}
|
|
68
|
+
finally {
|
|
69
|
+
restore();
|
|
70
|
+
}
|
|
71
|
+
let changes = extractChanges(result);
|
|
72
|
+
if (!changes.length)
|
|
73
|
+
changes = extractChanges(readLatestDream(fixture.store, fixture.project));
|
|
74
|
+
const score = scoreChanges(changes, fixture, before);
|
|
75
|
+
if (!kept)
|
|
76
|
+
fs.rmSync(root, { recursive: true, force: true });
|
|
77
|
+
return { model, score, root, kept, prompts, ...(error ? { error } : {}) };
|
|
78
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Scores a dream's changeset against what the eval fixture calls for.
|
|
3
|
+
* Recall checks (did it correct, merge, capture, demote) and precision checks
|
|
4
|
+
* (did it leave correct memory alone, did every claim carry evidence).
|
|
5
|
+
*/
|
|
6
|
+
import type { DreamChange } from "./dream-adapter.js";
|
|
7
|
+
import { type EvalFixture } from "./fixture.js";
|
|
8
|
+
export interface EvalCheck {
|
|
9
|
+
name: string;
|
|
10
|
+
kind: "recall" | "precision";
|
|
11
|
+
ok: boolean;
|
|
12
|
+
detail: string;
|
|
13
|
+
}
|
|
14
|
+
export interface EvalScore {
|
|
15
|
+
checks: EvalCheck[];
|
|
16
|
+
passed: number;
|
|
17
|
+
total: number;
|
|
18
|
+
ok: boolean;
|
|
19
|
+
changes: number;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Pulls the change list out of whatever the dream handed back: a changeset,
|
|
23
|
+
* a `{ changeset }` wrapper (DreamResult or the dreams/<runId>.json record),
|
|
24
|
+
* or a bare array.
|
|
25
|
+
*/
|
|
26
|
+
export declare function extractChanges(value: unknown): DreamChange[];
|
|
27
|
+
/** The newest `dreams/<runId>.json` for the project, parsed, or null. */
|
|
28
|
+
export declare function readLatestDream(store: string, project: string): unknown;
|
|
29
|
+
/**
|
|
30
|
+
* `budgetBefore` is the fixture's injected size before the dream ran; pass it
|
|
31
|
+
* when the dream ran in apply mode, since truths.md has changed by then.
|
|
32
|
+
*/
|
|
33
|
+
export declare function scoreChanges(changes: DreamChange[], fixture: EvalFixture, budgetBefore?: import("../budget.js").BudgetState): EvalScore;
|
|
34
|
+
export declare function formatScore(score: EvalScore): string;
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Scores a dream's changeset against what the eval fixture calls for.
|
|
3
|
+
* Recall checks (did it correct, merge, capture, demote) and precision checks
|
|
4
|
+
* (did it leave correct memory alone, did every claim carry evidence).
|
|
5
|
+
*/
|
|
6
|
+
import * as fs from "fs";
|
|
7
|
+
import * as path from "path";
|
|
8
|
+
import { FACTS, FIDS } from "./fixture.js";
|
|
9
|
+
import { overBudget, parseTruths } from "../budget.js";
|
|
10
|
+
const ASSERTING_OPS = new Set(["add_finding", "supersede", "retract", "edit", "merge", "promote_truth"]);
|
|
11
|
+
const FINDING_TOUCHING = new Set(["supersede", "retract", "edit"]);
|
|
12
|
+
function normalize(text) {
|
|
13
|
+
return text.replace(/\s+/g, " ").trim().toLowerCase();
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Pulls the change list out of whatever the dream handed back: a changeset,
|
|
17
|
+
* a `{ changeset }` wrapper (DreamResult or the dreams/<runId>.json record),
|
|
18
|
+
* or a bare array.
|
|
19
|
+
*/
|
|
20
|
+
export function extractChanges(value) {
|
|
21
|
+
if (Array.isArray(value))
|
|
22
|
+
return value;
|
|
23
|
+
if (!value || typeof value !== "object")
|
|
24
|
+
return [];
|
|
25
|
+
const obj = value;
|
|
26
|
+
if (Array.isArray(obj.changes))
|
|
27
|
+
return obj.changes;
|
|
28
|
+
if (obj.changeset)
|
|
29
|
+
return extractChanges(obj.changeset);
|
|
30
|
+
return [];
|
|
31
|
+
}
|
|
32
|
+
/** The newest `dreams/<runId>.json` for the project, parsed, or null. */
|
|
33
|
+
export function readLatestDream(store, project) {
|
|
34
|
+
const dir = path.join(store, project, "dreams");
|
|
35
|
+
let files = [];
|
|
36
|
+
try {
|
|
37
|
+
files = fs.readdirSync(dir).filter((f) => f.endsWith(".json") && f !== "last-run.json");
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
return null;
|
|
41
|
+
}
|
|
42
|
+
const newest = files
|
|
43
|
+
.map((f) => ({ f, t: fs.statSync(path.join(dir, f)).mtimeMs }))
|
|
44
|
+
.sort((a, b) => b.t - a.t || b.f.localeCompare(a.f))[0];
|
|
45
|
+
if (!newest)
|
|
46
|
+
return null;
|
|
47
|
+
try {
|
|
48
|
+
return JSON.parse(fs.readFileSync(path.join(dir, newest.f), "utf8"));
|
|
49
|
+
}
|
|
50
|
+
catch {
|
|
51
|
+
return null;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
function touches(change, fid) {
|
|
55
|
+
if (change.op === "merge")
|
|
56
|
+
return change.findingIds.includes(fid);
|
|
57
|
+
return "findingId" in change && change.findingId === fid;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* `budgetBefore` is the fixture's injected size before the dream ran; pass it
|
|
61
|
+
* when the dream ran in apply mode, since truths.md has changed by then.
|
|
62
|
+
*/
|
|
63
|
+
export function scoreChanges(changes, fixture, budgetBefore = overBudget(fixture.store, fixture.project, fixture.budgetKB, { skipLookupLog: true })) {
|
|
64
|
+
const checks = [];
|
|
65
|
+
const add = (name, kind, ok, detail) => checks.push({ name, kind, ok, detail });
|
|
66
|
+
const fix = changes.find((c) => FINDING_TOUCHING.has(c.op) && touches(c, FIDS.contradicted));
|
|
67
|
+
const fixText = fix && (fix.op === "supersede" || fix.op === "edit") ? fix.newText : "";
|
|
68
|
+
const fixEvidence = fix && "evidence" in fix ? fix.evidence.some((e) => e.kind !== "finding") : false;
|
|
69
|
+
add("corrects the contradicted finding", "recall", Boolean(fix) && fixEvidence && (fix?.op === "retract" || fixText.includes(FACTS.newPort)), fix ? `${fix.op} ${FIDS.contradicted}${fixText ? `: ${fixText}` : ""}${fixEvidence ? "" : " (no transcript/code/git evidence)"}` : `no change to ${FIDS.contradicted}`);
|
|
70
|
+
const merged = changes.some((c) => c.op === "merge" && c.findingIds.includes(FIDS.dupA) && c.findingIds.includes(FIDS.dupB));
|
|
71
|
+
const retired = (fid) => changes.some((c) => (c.op === "retract" || c.op === "supersede") && touches(c, fid));
|
|
72
|
+
const folded = retired(FIDS.dupA) !== retired(FIDS.dupB);
|
|
73
|
+
add("merges the duplicate findings", "recall", merged || folded, merged ? `merge ${FIDS.dupA} + ${FIDS.dupB}` : folded ? "one duplicate retired, the other kept" : "duplicates left as they are");
|
|
74
|
+
const captured = changes.find((c) => c.op === "add_finding" && FACTS.decisionPattern.test(c.text) && FACTS.decisionTopicPattern.test(c.text));
|
|
75
|
+
add("captures the unsaved decision", "recall", Boolean(captured), captured && captured.op === "add_finding" ? `${captured.findingType ?? "untyped"}: ${captured.text}` : "no finding about the rate limiter's advisory locks");
|
|
76
|
+
const byKey = new Map(budgetBefore.ranking.map((t) => [normalize(t.text), t]));
|
|
77
|
+
const demoted = [...new Set(changes.flatMap((c) => {
|
|
78
|
+
if (c.op !== "demote_truth")
|
|
79
|
+
return [];
|
|
80
|
+
const hit = byKey.get(normalize(parseTruths(`- ${c.truth.replace(/^- /, "")}`)[0]?.text ?? ""));
|
|
81
|
+
return hit ? [hit] : [];
|
|
82
|
+
}))];
|
|
83
|
+
const freed = demoted.reduce((sum, t) => sum + t.bytes, 0);
|
|
84
|
+
add("brings truths under the injected budget", "recall", !budgetBefore.over || freed >= budgetBefore.excessBytes, `${(budgetBefore.bytes / 1024).toFixed(1)} KB of ${(budgetBefore.budgetBytes / 1024).toFixed(1)} KB; demotes free ${freed} of ${budgetBefore.excessBytes} bytes needed`);
|
|
85
|
+
const fresh = new Set(fixture.freshTruths.map(normalize));
|
|
86
|
+
const wrongDemotes = demoted.filter((t) => fresh.has(normalize(t.text)));
|
|
87
|
+
add("keeps recently cited truths", "precision", wrongDemotes.length === 0, wrongDemotes.length ? `demoted: ${wrongDemotes.map((t) => t.text).join(" | ")}` : "none demoted");
|
|
88
|
+
const controlHit = changes.filter((c) => c.op !== "link" && c.op !== "move_topic" && touches(c, FIDS.control));
|
|
89
|
+
add("leaves the correct finding alone", "precision", controlHit.length === 0, controlHit.length ? controlHit.map((c) => c.op).join(", ") : `${FIDS.control} untouched`);
|
|
90
|
+
const unbacked = changes.filter((c) => ASSERTING_OPS.has(c.op) && !("evidence" in c && Array.isArray(c.evidence) && c.evidence.length > 0));
|
|
91
|
+
add("every claim carries evidence", "precision", unbacked.length === 0, unbacked.length ? `${unbacked.length} change(s) without evidence: ${unbacked.map((c) => c.op).join(", ")}` : `${changes.length} change(s) checked`);
|
|
92
|
+
const passed = checks.filter((c) => c.ok).length;
|
|
93
|
+
return { checks, passed, total: checks.length, ok: passed === checks.length, changes: changes.length };
|
|
94
|
+
}
|
|
95
|
+
export function formatScore(score) {
|
|
96
|
+
const lines = score.checks.map((c) => `${c.ok ? "PASS" : "FAIL"} ${c.name} (${c.kind}): ${c.detail}`);
|
|
97
|
+
lines.push(`${score.passed}/${score.total} checks passed, ${score.changes} change(s) proposed.`);
|
|
98
|
+
return lines.join("\n");
|
|
99
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A scripted stand-in for the dreaming model. It answers each fixture
|
|
3
|
+
* situation only when the prompt actually carries the evidence a real model
|
|
4
|
+
* would need, so a passing eval shows that collect and the prompt surfaced
|
|
5
|
+
* the right inputs, not just that the scorer matches a canned answer.
|
|
6
|
+
*/
|
|
7
|
+
import type { DreamChange } from "./dream-adapter.js";
|
|
8
|
+
import type { HelperRunner } from "./dream-adapter.js";
|
|
9
|
+
import { type EvalFixture } from "./fixture.js";
|
|
10
|
+
export interface ScriptedAnswer {
|
|
11
|
+
changes: DreamChange[];
|
|
12
|
+
/** Situations the prompt lacked the evidence for. */
|
|
13
|
+
missing: string[];
|
|
14
|
+
}
|
|
15
|
+
export declare function scriptedChanges(prompt: string, fixture: EvalFixture): ScriptedAnswer;
|
|
16
|
+
/** The changeset JSON a model would print for this prompt. */
|
|
17
|
+
export declare function scriptedReply(prompt: string, fixture: EvalFixture): string;
|
|
18
|
+
/** A `runHelper`-shaped runner that answers with the scripted reply and records each prompt. */
|
|
19
|
+
export declare function scriptedRunner(fixture: EvalFixture, prompts?: string[]): HelperRunner;
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A scripted stand-in for the dreaming model. It answers each fixture
|
|
3
|
+
* situation only when the prompt actually carries the evidence a real model
|
|
4
|
+
* would need, so a passing eval shows that collect and the prompt surfaced
|
|
5
|
+
* the right inputs, not just that the scorer matches a canned answer.
|
|
6
|
+
*/
|
|
7
|
+
import { CLAUDE_SESSION, CODEX_SESSION, FACTS, FIDS } from "./fixture.js";
|
|
8
|
+
import { overBudget } from "../budget.js";
|
|
9
|
+
export function scriptedChanges(prompt, fixture) {
|
|
10
|
+
const changes = [];
|
|
11
|
+
const missing = [];
|
|
12
|
+
const has = (s) => prompt.includes(s);
|
|
13
|
+
if (has(FIDS.contradicted) && has(FACTS.newPort)) {
|
|
14
|
+
changes.push({
|
|
15
|
+
op: "supersede", findingId: FIDS.contradicted,
|
|
16
|
+
newText: "[pattern] The API dev server listens on port 4100 (src/server.ts); port 3000 belongs to the web app's own dev server.",
|
|
17
|
+
evidence: [
|
|
18
|
+
{ kind: "transcript", ref: `claude:${CLAUDE_SESSION}#1`, quote: "Move the API dev server to port 4100" },
|
|
19
|
+
{ kind: "code", ref: "src/server.ts:1" },
|
|
20
|
+
],
|
|
21
|
+
});
|
|
22
|
+
}
|
|
23
|
+
else
|
|
24
|
+
missing.push("contradicted");
|
|
25
|
+
if (has(FIDS.dupA) && has(FIDS.dupB)) {
|
|
26
|
+
changes.push({
|
|
27
|
+
op: "merge", findingIds: [FIDS.dupA, FIDS.dupB],
|
|
28
|
+
newText: "[pitfall] Run `pnpm db:migrate` before `pnpm test`; without it the suite fails with \"relation does not exist\".",
|
|
29
|
+
evidence: [{ kind: "finding", ref: FIDS.dupA }, { kind: "finding", ref: FIDS.dupB }],
|
|
30
|
+
});
|
|
31
|
+
}
|
|
32
|
+
else
|
|
33
|
+
missing.push("duplicates");
|
|
34
|
+
if (FACTS.decisionPattern.test(prompt)) {
|
|
35
|
+
changes.push({
|
|
36
|
+
op: "add_finding", findingType: "decision",
|
|
37
|
+
text: "The rate limiter uses Postgres advisory locks, not Redis, on-prem and cloud alike: Redis is unavailable in the customer's on-prem install and one code path beats two.",
|
|
38
|
+
evidence: [{ kind: "transcript", ref: `codex:${CODEX_SESSION}#3`, quote: "drop Redis for the rate limiter and use Postgres advisory locks everywhere" }],
|
|
39
|
+
});
|
|
40
|
+
}
|
|
41
|
+
else
|
|
42
|
+
missing.push("decision");
|
|
43
|
+
const inPrompt = fixture.staleTruths.filter((t) => has(t.slice(0, 60)));
|
|
44
|
+
if (inPrompt.length) {
|
|
45
|
+
const state = overBudget(fixture.store, fixture.project, fixture.budgetKB, { skipLookupLog: true });
|
|
46
|
+
const stale = new Set(inPrompt);
|
|
47
|
+
let freed = 0;
|
|
48
|
+
for (const truth of state.ranking.filter((t) => stale.has(t.text))) {
|
|
49
|
+
if (freed >= state.excessBytes)
|
|
50
|
+
break;
|
|
51
|
+
changes.push({ op: "demote_truth", truth: truth.text, reason: "Describes retired infrastructure; not cited in months and the injected layer is over budget." });
|
|
52
|
+
freed += truth.bytes;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
else
|
|
56
|
+
missing.push("budget");
|
|
57
|
+
return { changes, missing };
|
|
58
|
+
}
|
|
59
|
+
/** The changeset JSON a model would print for this prompt. */
|
|
60
|
+
export function scriptedReply(prompt, fixture) {
|
|
61
|
+
const { changes, missing } = scriptedChanges(prompt, fixture);
|
|
62
|
+
return JSON.stringify({ changes, notes: missing.length ? `Not enough evidence for: ${missing.join(", ")}.` : "" });
|
|
63
|
+
}
|
|
64
|
+
/** A `runHelper`-shaped runner that answers with the scripted reply and records each prompt. */
|
|
65
|
+
export function scriptedRunner(fixture, prompts = []) {
|
|
66
|
+
return async (choice, options) => {
|
|
67
|
+
prompts.push(options.prompt);
|
|
68
|
+
return { ok: true, output: scriptedReply(options.prompt, fixture), project: choice.project, account: choice.account, model: "scripted", durationMs: 0 };
|
|
69
|
+
};
|
|
70
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pages: one markdown file per subject under `<store>/<project>/reference/pages/<slug>.md`.
|
|
3
|
+
*
|
|
4
|
+
* Dreaming writes these instead of growing shared files (one page per subject
|
|
5
|
+
* beats a big FINDINGS.md). A page is frontmatter (`title`, `summary`), then a
|
|
6
|
+
* body that links other pages as `[[slug]]` and cites findings as `fid:xxxxxxxx`.
|
|
7
|
+
*
|
|
8
|
+
* Search needs no extra wiring: the indexer globs every `**\/*.md` in a project
|
|
9
|
+
* (DEFAULT_INDEX_POLICY.includeGlobs) and `classifyFile` types anything under a
|
|
10
|
+
* `reference/` segment as `reference`, so a page is found like any archive doc
|
|
11
|
+
* on the next index build.
|
|
12
|
+
*/
|
|
13
|
+
export declare const PAGES_DIR: string;
|
|
14
|
+
/** A page is a summary of one subject, not an archive. Larger pages are refused. */
|
|
15
|
+
export declare const MAX_PAGE_BYTES: number;
|
|
16
|
+
export declare class PageError extends Error {
|
|
17
|
+
constructor(message: string);
|
|
18
|
+
}
|
|
19
|
+
export interface PageMeta {
|
|
20
|
+
slug: string;
|
|
21
|
+
title: string;
|
|
22
|
+
summary: string;
|
|
23
|
+
/** Page slugs this page links to (`[[slug]]`), deduplicated, in order of appearance. */
|
|
24
|
+
links: string[];
|
|
25
|
+
/** Finding ids the page cites (`fid:xxxxxxxx`). */
|
|
26
|
+
fids: string[];
|
|
27
|
+
path: string;
|
|
28
|
+
}
|
|
29
|
+
export interface Page extends PageMeta {
|
|
30
|
+
body: string;
|
|
31
|
+
markdown: string;
|
|
32
|
+
}
|
|
33
|
+
export declare function isValidPageSlug(slug: string): boolean;
|
|
34
|
+
/**
|
|
35
|
+
* Accepts a bare slug or the changeset's page reference (`reference/pages/<slug>.md`)
|
|
36
|
+
* and returns the slug. Throws on anything else, including traversal attempts.
|
|
37
|
+
*/
|
|
38
|
+
export declare function pageSlug(ref: string): string;
|
|
39
|
+
/** `[[slug]]` targets in a body, deduplicated. Invalid targets are kept verbatim so the link check reports them. */
|
|
40
|
+
export declare function extractPageLinks(body: string): string[];
|
|
41
|
+
export declare function extractPageFids(body: string): string[];
|
|
42
|
+
/**
|
|
43
|
+
* Puts the markdown in page shape: frontmatter with a title and a summary
|
|
44
|
+
* (taken from the model's frontmatter, else the first heading and paragraph),
|
|
45
|
+
* an `updated` date, and the body. `links` the caller declares but the body
|
|
46
|
+
* does not mention are appended as a "Related" line so they stay visible.
|
|
47
|
+
*/
|
|
48
|
+
export declare function normalizePage(slug: string, markdown: string, links: string[], now?: Date): string;
|
|
49
|
+
export declare function listPages(store: string, project: string): PageMeta[];
|
|
50
|
+
export declare function readPage(store: string, project: string, slugOrRef: string): Page | null;
|
|
51
|
+
/**
|
|
52
|
+
* Writes (creates or replaces) one page. The write is locked and atomic and
|
|
53
|
+
* goes to the audit log. Broken links do not stop the write; they are returned
|
|
54
|
+
* so the caller can record them beside the change.
|
|
55
|
+
*/
|
|
56
|
+
export declare function writePage(store: string, project: string, slug: string, markdown: string, links: string[]): Promise<{
|
|
57
|
+
path: string;
|
|
58
|
+
brokenLinks: string[];
|
|
59
|
+
}>;
|
|
60
|
+
export interface PageLinkReport {
|
|
61
|
+
slug: string;
|
|
62
|
+
/** `[[target]]` links with no page (or an invalid slug). */
|
|
63
|
+
brokenLinks: string[];
|
|
64
|
+
/** Cited fids that are not in the given set of known finding ids. Empty when no set is given. */
|
|
65
|
+
unknownFids: string[];
|
|
66
|
+
}
|
|
67
|
+
/** Link check across every page of a project. Only pages with a problem are returned. */
|
|
68
|
+
export declare function checkPageLinks(store: string, project: string, knownFids?: Iterable<string>): PageLinkReport[];
|