// Tests for the shared lessons.mjs (shipped in plan2code-quick-task and, from // Phase 6, every skill that reads or notes lessons) and the core it loads, // src/web-console/learning.mjs. // // See skill-script-helpers.mjs for how these run. Every test gets its own // PLAN2CODE_LEARNING_DIR, so nothing reaches ~/.plan2code/learning. import { test, after } from "node:test"; import assert from "node:assert/strict"; import fs from "node:fs"; import path from "node:path"; import { spawnSync } from "node:child_process"; import { runScript, tmp, write, read, gitInit, gitIn, copyFixture, fixtureCleanup, scrubbedEnv, slashed, SKILLS, NOW } from "./skill-script-helpers.mjs"; import * as core from "../src/web-console/learning.mjs"; // The record functions, imported straight from the source (the script runs // its CLI only when started as a script). import * as record from "../src/skill-scripts/lessons.mjs"; after(fixtureCleanup); const learningDir = () => tmp("learning-store"); function L(cwd, args, learning) { return runScript("plan2code-quick-task", "lessons.mjs", args, { cwd, env: { PLAN2CODE_LEARNING_DIR: learning } }); } // A repository with one commit on main, copied fresh for each caller. const repo = () => copyFixture("lessons-repo", "one-commit", (dir) => { const g = gitInit(dir); write(dir, "README.md", "# Fixture\n"); g("add", "-A"); g("commit", "-q", "-m", "init"); }); // The same clock the scripts run on (PLAN2CODE_NOW, local time). const nowDate = () => { const m = NOW.match(/^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2})$/); return new Date(+m[1], +m[2] - 1, +m[3], +m[4], +m[5]); }; const daysBefore = (n) => new Date(nowDate().getTime() - n * 24 * 60 * 60 * 1000); // Write a waiting item through the core, into a given store. function waiting(cwd, learning, noted, id) { const before = process.env.PLAN2CODE_LEARNING_DIR; process.env.PLAN2CODE_LEARNING_DIR = learning; try { return core.writeWaiting(cwd, { id: id || core.newWaitingId(noted), type: "lesson", text: "A lesson.", noted: noted.toISOString() }); } finally { if (before === undefined) delete process.env.PLAN2CODE_LEARNING_DIR; else process.env.PLAN2CODE_LEARNING_DIR = before; } } const settings = (dir, body) => write(dir, ".plan2code/settings.json", typeof body === "string" ? body : JSON.stringify(body)); /* ----------------------------------------------------------------- state */ test("lessons state: not set up, off, on, paused, and unknown for another format", () => { const dir = repo(); const store = learningDir(); const s0 = L(dir, ["state"], store); assert.equal(s0.code, 0, s0.stderr); assert.deepEqual(s0.json, { ok: true, state: "not-set-up", active: false, pausedSince: null, waiting: { count: 0, oldestDays: 0 }, hasAgents: false, onDefaultBranch: true, }); settings(dir, { format: 1, learning: "off" }); assert.equal(L(dir, ["state"], store).json.state, "off"); settings(dir, { format: 1, learning: "on" }); const on = L(dir, ["state"], store).json; assert.equal(on.state, "on"); assert.equal(on.active, true); assert.equal(L(dir, ["pause", "on"], store).code, 0); const paused = L(dir, ["state"], store).json; assert.equal(paused.state, "paused"); assert.equal(paused.active, false); assert.ok(paused.pausedSince, "a paused state says since when"); settings(dir, { format: 2, learning: "on" }); const unknown = L(dir, ["state"], store).json; assert.equal(unknown.state, "unknown"); assert.equal(unknown.active, false); settings(dir, "{ not json"); assert.equal(L(dir, ["state"], store).json.state, "unknown"); settings(dir, { format: 1, learning: "maybe" }); assert.equal(L(dir, ["state"], store).json.state, "unknown"); }); test("lessons state: a pause file is ignored unless the project is on", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); assert.equal(L(dir, ["pause", "on"], store).code, 0); settings(dir, { format: 1, learning: "off" }); assert.equal(L(dir, ["state"], store).json.state, "off"); }); test("lessons state: hasAgents and onDefaultBranch", () => { const dir = repo(); const store = learningDir(); write(dir, "AGENTS.md", "# Agents\n"); const g = gitIn(dir); const s = L(dir, ["state"], store).json; assert.equal(s.hasAgents, true); assert.equal(s.onDefaultBranch, true, "main is the default branch with no origin"); g("checkout", "-q", "-b", "feature/x"); assert.equal(L(dir, ["state"], store).json.onDefaultBranch, false); const outside = tmp("lessons-nogit"); assert.equal(L(outside, ["state"], store).json.onDefaultBranch, false, "outside git it is false"); // origin/HEAD names the default branch when it is set, with origin/ removed. g("checkout", "-q", "-b", "trunk"); g("update-ref", "refs/remotes/origin/trunk", "HEAD"); g("symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/trunk"); assert.equal(L(dir, ["state"], store).json.onDefaultBranch, true, "trunk, from origin/HEAD"); g("checkout", "-q", "main"); assert.equal(L(dir, ["state"], store).json.onDefaultBranch, false, "main is not the default once origin/HEAD says trunk"); // No origin/HEAD and no main: master. const old = tmp("lessons-master"); const gm = gitInit(old, "master"); write(old, "README.md", "# Old\n"); gm("add", "-A"); gm("commit", "-q", "-m", "init"); assert.equal(L(old, ["state"], store).json.onDefaultBranch, true, "master when there is no main"); }); test("lessons state: a second worktree of the same repository shares the waiting store", () => { const dir = repo(); const store = learningDir(); const wt = path.join(tmp("lessons-wt"), "second"); gitIn(dir)("worktree", "add", "-q", "-b", "second", wt); waiting(dir, store, daysBefore(2)); waiting(dir, store, daysBefore(1)); const main = L(dir, ["state"], store).json; const other = L(wt, ["state"], store).json; assert.equal(main.waiting.count, 2); assert.deepEqual(other.waiting, main.waiting, "same repository key, same store"); assert.equal(other.waiting.oldestDays, 2); }); test("lessons state: a waiting item older than 30 days is deleted, a 29-day-old one is counted", () => { const dir = repo(); const store = learningDir(); const old = waiting(dir, store, daysBefore(31)); waiting(dir, store, daysBefore(29)); const s = L(dir, ["state"], store).json; assert.deepEqual(s.waiting, { count: 1, oldestDays: 29 }); const files = fs.readdirSync(path.join(store), { recursive: true }).map(String); assert.equal(files.some((f) => f.includes(old.id)), false, "the old item's file is gone"); }); /* ---------------------------------------------------------------- switch */ test("lessons switch: on then off write only settings.json and never stage it", () => { const dir = repo(); const store = learningDir(); const on = L(dir, ["switch", "on"], store); assert.equal(on.code, 0, on.stderr); assert.deepEqual(on.json, { ok: true, state: "on", active: true, written: [".plan2code/settings.json"], dryRun: false, skipped: "no-agents", next: "plan2code-init", offerLogMove: false, firstOn: true }); assert.equal(fs.readFileSync(path.join(dir, ".plan2code", "settings.json"), "utf8"), '{\n "format": 1,\n "learning": "on"\n}\n'); const g = gitIn(dir); assert.equal(g("status", "--porcelain", "--untracked-files=all").trim(), "?? .plan2code/settings.json"); assert.deepEqual(L(dir, ["switch", "on"], store).json.written, [], "nothing changed, nothing written"); g("add", "-A"); g("commit", "-q", "-m", "learning on"); const off = L(dir, ["switch", "off"], store); assert.equal(off.code, 0, off.stderr); assert.equal(off.json.state, "off"); assert.deepEqual(off.json.written, [".plan2code/settings.json"]); assert.equal(g("status", "--porcelain").trim(), "M .plan2code/settings.json", "modified, not staged"); }); test("lessons switch: --dry-run writes nothing", () => { const dir = repo(); const store = learningDir(); const r = L(dir, ["switch", "on", "--dry-run"], store); assert.equal(r.code, 0, r.stderr); assert.deepEqual(r.json.written, []); assert.equal(r.json.dryRun, true); assert.equal(r.json.state, "not-set-up"); assert.equal(fs.existsSync(path.join(dir, ".plan2code")), false); }); test("lessons switch: run from a subfolder writes and reads the checkout's top-level settings", () => { const dir = repo(); const store = learningDir(); const sub = path.join(dir, "packages", "app"); fs.mkdirSync(sub, { recursive: true }); write(dir, "AGENTS.md", "# Agents\n"); const on = L(sub, ["switch", "on"], store); assert.equal(on.code, 0, on.stderr); assert.equal(on.json.state, "on"); assert.deepEqual(on.json.written, [".plan2code/settings.json", "AGENTS.md"], "the pointer line lands in the top-level AGENTS.md"); assert.ok(fs.existsSync(path.join(dir, ".plan2code", "settings.json"))); assert.equal(fs.existsSync(path.join(sub, ".plan2code")), false, "no stray settings in the subfolder"); const viaRoot = L(dir, ["state", "--root", sub], store).json; assert.equal(viaRoot.state, "on"); assert.equal(viaRoot.hasAgents, true, "AGENTS.md is read at the top level too"); }); test("lessons switch: refused while the settings file is of another format", () => { const dir = repo(); const store = learningDir(); const body = JSON.stringify({ format: 2, learning: "on" }); settings(dir, body); const r = L(dir, ["switch", "off"], store); assert.equal(r.code, 5); assert.equal(r.json.error, "unknown-format"); assert.equal(r.json.state, "unknown"); assert.equal(fs.readFileSync(path.join(dir, ".plan2code", "settings.json"), "utf8"), body, "the newer file is left as it is"); }); test("lessons switch: needs on or off", () => { const dir = repo(); const r = L(dir, ["switch"], learningDir()); assert.equal(r.code, 2); assert.equal(r.json.error, "missing-value"); }); /* ----------------------------------------------------------------- pause */ test("lessons pause: refused with exit 5 when not set up and when off", () => { const dir = repo(); const store = learningDir(); const notSetUp = L(dir, ["pause", "on"], store); assert.equal(notSetUp.code, 5); assert.equal(notSetUp.json.error, "not-on"); assert.match(notSetUp.json.message, /only available while Learning is on/); settings(dir, { format: 1, learning: "off" }); const off = L(dir, ["pause", "on"], store); assert.equal(off.code, 5); assert.equal(off.json.error, "not-on"); assert.equal(fs.existsSync(store) && fs.readdirSync(store).length > 0, false, "nothing written on this machine"); }); test("lessons pause: on gives paused with pausedSince, off clears it, off again is a no-op", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const p = L(dir, ["pause", "on"], store); assert.equal(p.code, 0, p.stderr); assert.equal(p.json.state, "paused"); assert.equal(p.json.active, false); assert.equal(p.json.pausedSince, nowDate().toISOString(), "the pinned clock"); const s = L(dir, ["state"], store).json; assert.equal(s.state, "paused"); assert.equal(s.pausedSince, p.json.pausedSince); const off = L(dir, ["pause", "off"], store); assert.deepEqual(off.json, { ok: true, state: "on", active: true, pausedSince: null }); const again = L(dir, ["pause", "off"], store); assert.equal(again.code, 0); assert.equal(again.json.state, "on"); }); /* ----------------------------------------------------------- the rest */ test("lessons: unknown commands exit 2", () => { const dir = repo(); const store = learningDir(); for (const cmd of ["frobnicate", "unlearn"]) { const r = L(dir, [cmd], store); assert.equal(r.code, 2, cmd); assert.equal(r.json.error, "unknown-command", cmd); } assert.equal(L(dir, [], store).code, 2); }); test("lessons: a missing console folder gives exit 3 no-console", () => { const base = tmp("lessons-alone"); const scripts = path.join(base, "skill", "scripts"); fs.mkdirSync(scripts, { recursive: true }); for (const f of ["lessons.mjs", "common.mjs", "glob.mjs", "test-map.mjs"]) fs.copyFileSync(path.join(SKILLS, "plan2code-quick-task", "scripts", f), path.join(scripts, f)); const emptyHome = tmp("lessons-console-home"); const r = spawnSync(process.execPath, [path.join(scripts, "lessons.mjs"), "state"], { cwd: repo(), encoding: "utf8", env: scrubbedEnv({ PLAN2CODE_NOW: NOW, PLAN2CODE_CONSOLE_HOME: emptyHome, PLAN2CODE_LEARNING_DIR: learningDir() }), }); assert.equal(r.status, 3, r.stderr); const json = JSON.parse(r.stdout); assert.equal(json.error, "no-console"); assert.match(json.next, /without lessons/); }); /* -------------------------------------------------------------- the core */ test("learning core: the repository key matches projectKey's shape and removeWaiting refuses paths", () => { const dir = repo(); const store = learningDir(); const before = process.env.PLAN2CODE_LEARNING_DIR; process.env.PLAN2CODE_LEARNING_DIR = store; try { const key = core.repositoryKey(dir); assert.match(key, /^[a-z0-9-]{1,40}-[0-9a-f]{12}$/); assert.equal(core.storeDir(dir), path.join(store, key)); assert.match(core.newWaitingId(nowDate()), /^20260803-140500-[0-9a-f]{6}$/); for (const bad of ["../x", "a/b", "a\\b", "..", "", "a:b", ".hidden", "a b"]) assert.throws(() => core.removeWaiting(dir, bad), /Refused/, bad); const item = core.writeWaiting(dir, { id: "20260803-140500-abcdef", type: "lesson", text: "x", noted: nowDate().toISOString() }); assert.equal(item.format, 1); assert.equal(core.listWaiting(dir, nowDate()).length, 1); fs.writeFileSync(path.join(core.storeDir(dir), "waiting", "bad.json"), "{ nope"); fs.writeFileSync(path.join(core.storeDir(dir), "waiting", "v2.json"), JSON.stringify({ format: 2, id: "v2", noted: nowDate().toISOString() })); assert.equal(core.listWaiting(dir, nowDate()).length, 1, "unreadable and other-format files are skipped"); assert.equal(core.removeWaiting(dir, "20260803-140500-abcdef"), true); assert.equal(core.removeWaiting(dir, "20260803-140500-abcdef"), false); } finally { if (before === undefined) delete process.env.PLAN2CODE_LEARNING_DIR; else process.env.PLAN2CODE_LEARNING_DIR = before; } }); /* ------------------------------------------------------------ the record */ const AREA_TEXT = [ "# Web console", "Paths: src/web-console/**, scripts/test-web-console-*.mjs", "", "### A first lesson about the server", "- Kind: convention", "- About: src/web-console/server.mjs", "- Noted: 2026-11-01, Implement", "", "### Cut the page test's wait, never the timeout", "- Kind: correction", "- About: scripts/a.mjs, scripts/b.mjs", "- Why: a redraw raced the read once.", "- Noted: 2026-11-02, Quick Task, checked 2026-11-10", "", ].join("\n"); test("lessons record: parse and render round trip byte for byte, LF and CRLF", () => { for (const text of [AREA_TEXT, AREA_TEXT.replace(/\n/g, "\r\n"), AREA_TEXT.replace(/\n$/, "")]) { const area = record.parseAreaFile(text); assert.equal(record.renderAreaFile(area), text); assert.equal(area.name, "Web console"); assert.deepEqual(area.paths, ["src/web-console/**", "scripts/test-web-console-*.mjs"]); assert.equal(area.blocks.length, 2); const [a, b] = area.blocks; assert.equal(a.heading, "A first lesson about the server"); assert.equal(a.kind, "convention"); assert.deepEqual(a.about, ["src/web-console/server.mjs"]); assert.equal(a.why, ""); assert.equal(a.noted, "2026-11-01, Implement"); assert.equal(a.checked, null); assert.equal(a.startLine, 4); assert.deepEqual(b.about, ["scripts/a.mjs", "scripts/b.mjs"]); assert.equal(b.why, "a redraw raced the read once."); assert.equal(b.noted, "2026-11-02, Quick Task"); assert.equal(b.checked, "2026-11-10"); } assert.equal(record.parseAreaFile(AREA_TEXT.replace(/\n/g, "\r\n")).eol, "\r\n"); }); test("lessons record: an insert lands at its alphabetical place and leaves every other line alone", () => { for (const eolText of ["\n", "\r\n"]) { const text = AREA_TEXT.replace(/\n/g, eolText); const area = record.parseAreaFile(text); const r = record.insertBlock(area, { heading: "Build the skills before the tests", kind: "command", about: ["install.js"], why: "", noted: "2026-11-13, Implement" }); assert.deepEqual(r, { inserted: true, index: 1 }); const outText = record.renderAreaFile(area); const added = ["### Build the skills before the tests", "- Kind: command", "- About: install.js", "- Noted: 2026-11-13, Implement", ""].join(eolText) + eolText; const at = text.indexOf("### Cut"); assert.equal(outText, text.slice(0, at) + added + text.slice(at)); assert.deepEqual(record.insertBlock(area, { heading: "build the skills before the tests", kind: "command", about: ["x"], noted: "x" }), { duplicate: true }); assert.equal(record.removeBlock(area, "web-console/build-the-skills-before-the-tests"), true); assert.equal(record.renderAreaFile(area), text, "removing it gives the file back"); } const general = record.newArea("General", []); for (let i = 0; i < 25; i++) assert.equal(record.insertBlock(general, { heading: `Lesson ${String(i).padStart(2, "0")}`, kind: "convention", about: ["a"], noted: "x" }, { general: true }).inserted, true); assert.deepEqual(record.insertBlock(general, { heading: "One more", kind: "convention", about: ["a"], noted: "x" }, { general: true }), { full: true }); assert.ok(record.renderAreaFile(general).startsWith("# General\n\n### Lesson 00\n"), "general.md has no Paths line"); }); test("lessons record: slugs, ids and file paths", () => { assert.equal(record.slugOf(" Web Console: server (v2)! "), "web-console-server-v2"); assert.equal(record.slugOf("x".repeat(80)).length, 60); assert.equal(record.lessonId("activities-games", "Set the seen flag for a new first-run dialog"), "activities-games/set-the-seen-flag-for-a-new-first-run-dialog"); assert.equal(record.areaFilePath("/repo", "web-console"), path.join("/repo", ".plan2code", "lessons", "web-console.md")); }); /* ------------------------------------------------------------- the check */ // Fixture secrets are assembled from parts so a scanner on this repository // never sees one whole. const SECRETS = { "private-key-block": ["-----BEGIN " + "RSA PRIVATE KEY-----", "-----BEGIN PUBLIC KEY-----"], "aws-access-key": ["AK" + "IA" + "0".repeat(16), "AK" + "IA" + "0".repeat(10)], "github-token": ["gh" + "p_" + "a".repeat(36), "gh" + "p_short"], "slack-token": ["xo" + "xb-" + "1".repeat(12), "xox-plain-words"], "stripe-key": ["sk" + "_live_" + "a".repeat(24), "sk" + "_test_" + "a".repeat(24)], "google-api-key": ["AI" + "za" + "A".repeat(35), "AI" + "za" + "A".repeat(10)], "sk-key": ["sk" + "-" + "a1".repeat(12), "the sk-short-name flag"], jwt: ["ey" + "JhbGciOi.eyJzdWIi.c2lnbmF0dXJl", "eyJhbGciOi alone"], "url-credentials": ["https://" + "user:hunter22" + "@example.com", "https://user@example.com"], "assigned-secret": ["password = " + "hunter2hunter2", "password = "], }; test("lessons check: each secret pattern refuses its shape and passes its near miss", () => { for (const [name, [bad, near]] of Object.entries(SECRETS)) { const r = record.checkText(`Set it to ${bad} in the config`); assert.equal(r.refused && r.refused.pattern, name, `${name} refuses`); assert.ok(!r.refused.part.includes(bad.slice(5)), `${name}: the output never repeats the secret`); assert.ok(r.refused.part.length <= 5, name); assert.equal(record.checkText(`Set it to ${near} in the config`).refused, null, `${name} near miss passes`); } for (const placeholder of ["token: GITHUB_TOKEN", "secret = xxxxxxxxxx", "api key: ********", "password=${DB_PASSWORD}", "token: "]) { assert.equal(record.checkText(placeholder).refused, null, placeholder); } }); test("lessons check: prefixed assignments and a user-less credential URL are refused", () => { for (const [bad, name] of [ ["DB_PASS" + "WORD=hunter2hunter2", "assigned-secret"], ["OPENAI_API" + "_KEY=abcd1234efgh5678", "assigned-secret"], ["CLIENT_SEC" + "RET: abcd1234efgh5678", "assigned-secret"], ["redis://" + ":hunter2hunter2@localhost:6379", "url-credentials"], // Uppercase letters with digits are a value, not a variable's name. ["API_" + "KEY=K8J2H4G6F9D3S1A5", "assigned-secret"], ["pass" + "word: HUNTER2HUNTER2", "assigned-secret"], // A keyword that ends a camelCase name, and the key names that follow secret. ["dbPass" + "word=hunter2hunter2", "assigned-secret"], ["authTo" + "ken=abcd1234efgh5678", "assigned-secret"], ["clientSec" + 'ret: "abcd1234efgh5678"', "assigned-secret"], ["SECRET" + "_KEY=abcd1234efgh5678", "assigned-secret"], ["AWS_SECRET_ACCESS" + "_KEY=wJalrXUtnFEMIabcd1234", "assigned-secret"], ["private" + "Key: abcd1234efgh5678", "assigned-secret"], // A real value that merely holds filler characters is still a value. ["pass" + "word=Sup3rS3cretxxx1", "assigned-secret"], ["to" + "ken: abcd1234...efgh", "assigned-secret"], ]) { assert.equal(record.checkText(`Set ${bad} first`).refused?.pattern, name, bad); } for (const fine of ["PASSWORD_FILE=/run/secrets/db", "the tokenizer: abcdefghijk", "http://localhost:8080/x"]) assert.equal(record.checkText(fine).refused, null, fine); }); test("lessons check: no output ever repeats a fixture secret, flags included", () => { const dir = repo(); const store = learningDir(); for (const [bad] of Object.values(SECRETS)) { const r = L(dir, ["check", "--text", `Connect with ${bad}/db`], store); assert.equal(r.code, 0, r.stderr); assert.ok(r.json.refused, bad); assert.ok(!r.stdout.includes(bad), `stdout repeats ${bad}`); } const url = record.checkText("Connect with https://" + "user:hunter22" + "@example.com/db"); assert.equal(url.refused.pattern, "url-credentials"); assert.ok(!url.flags.some((f) => f.part.includes("hunter22")), "the email flag never shows the password half"); }); test("lessons check: flags fire in prose and never inside backticks", () => { const prose = record.checkText("Ask Jane Doe or @alice, or write to jane@example.com."); assert.deepEqual(prose.flags.map((f) => f.pattern).sort(), ["email", "handle", "person-name"]); assert.equal(prose.refused, null); const code = record.checkText("Import `@scope/pkg` and call `Jane Doe` with `jane@example.com`."); assert.deepEqual(code.flags, []); }); test("lessons check: the command reports and always exits 0", () => { const dir = repo(); const store = learningDir(); const r = L(dir, ["check", "--text", "Use the flat keys.", "--why", SECRETS["aws-access-key"][0]], store); assert.equal(r.code, 0, r.stderr); assert.equal(r.json.refused.pattern, "aws-access-key"); assert.ok(!r.stdout.includes(SECRETS["aws-access-key"][0]), "stdout never repeats the secret"); const clean = L(dir, ["check", "--text", "Ask Jane Doe."], store).json; assert.equal(clean.refused, null); assert.deepEqual(clean.flags, [{ pattern: "person-name", part: "Jane Doe" }]); }); /* ----------------------------------------------------------------- note */ const waitingFiles = (store) => fs.existsSync(store) ? fs .readdirSync(store, { recursive: true }) .map(String) .filter((f) => /waiting[\\/][^\\/]+\.json$/.test(f)) : []; const lesson = (text, extra = []) => ["note", "--type", "lesson", "--text", text, "--kind", "convention", "--about", "src/a.js", "--source", "said", "--skill", "Implement", ...extra]; test("lessons note: each rule refuses with exit 4 invalid-lesson", () => { const dir = repo(); const store = learningDir(); const cases = [ ["two sentences", lesson("Use the flat keys. Never browser storage.")], ["201 characters", lesson("a".repeat(201))], ["unknown kind", ["note", "--type", "lesson", "--text", "One rule", "--kind", "rule", "--about", "src/a.js", "--source", "said", "--skill", "I"]], ["a correction with no why", ["note", "--type", "lesson", "--text", "One rule", "--kind", "correction", "--about", "src/a.js", "--source", "said", "--skill", "I"]], ["four files", ["note", "--type", "lesson", "--text", "One rule", "--kind", "convention", "--about", "a.js,b.js,c.js,d.js", "--source", "said", "--skill", "I"]], ["a path with ..", ["note", "--type", "lesson", "--text", "One rule", "--kind", "convention", "--about", "../outside.js", "--source", "said", "--skill", "I"]], ["inferred with no seen files", ["note", "--type", "lesson", "--text", "One rule", "--kind", "convention", "--about", "src/a.js", "--source", "inferred", "--skill", "I"]], ]; for (const [what, args] of cases) { const r = L(dir, args, store); assert.equal(r.code, 4, `${what}: ${r.stdout}`); assert.equal(r.json.error, "invalid-lesson", what); assert.ok(r.json.problems.length >= 1, what); } assert.equal(L(dir, lesson("Call `a.b()` first. Then `c()`, as in `x. Y`"), store).code, 4, "a second sentence outside code still counts"); assert.equal(L(dir, lesson("Call `x. Y` before the build"), store).code, 0, "a stop inside a code span is not a sentence end"); write(dir, "src/web/a.js", ""); assert.equal(L(dir, ["note", "--type", "lesson", "--text", "One rule", "--kind", "convention", "--about", "src/web,src/a.js", "--source", "said", "--skill", "I"], store).code, 4, "a folder stands alone"); }); test("lessons note: a refused secret exits 5 and writes nothing anywhere", () => { const dir = repo(); const store = learningDir(); for (const [bad] of Object.values(SECRETS)) { const r = L(dir, lesson(`Set it to ${bad} first`), store); assert.equal(r.code, 5, r.stdout); assert.equal(r.json.error, "secret"); assert.ok(!r.stdout.includes(bad), "the output never repeats the secret"); } const why = L(dir, lesson("Set the key first", ["--why", `the key is ${SECRETS["github-token"][0]}`]), store); assert.equal(why.code, 5); const secret = SECRETS["assigned-secret"][0]; const fields = [ ["note", "--type", "area", "--name", secret, "--paths", "src/**", "--skill", "Implement"], ["note", "--type", "area", "--name", "Web", "--paths", `src/${SECRETS["aws-access-key"][0]}/**`, "--skill", "Implement"], lesson("One rule", ["--area", secret]), ["note", "--type", "lesson", "--text", "One rule", "--kind", "convention", "--about", `src/${SECRETS["aws-access-key"][0]}.js`, "--source", "said", "--skill", "Implement"], ["note", "--type", "lesson", "--text", "One rule", "--kind", "convention", "--about", "src/a.js", "--source", "said", "--skill", secret], ]; for (const args of fields) { const r = L(dir, args, store); assert.equal(r.code, 5, r.stdout); assert.equal(r.json.error, "secret"); assert.ok(!r.stdout.includes(SECRETS["aws-access-key"][0]) && !r.stdout.includes("hunter2hunter2"), r.stdout); } assert.deepEqual(waitingFiles(store), [], "the waiting folder stays empty"); }); test("lessons note: a skill name with a line break or over 40 characters is refused", () => { const dir = repo(); const store = learningDir(); for (const skill of ["Implement\n### Injected heading", "x".repeat(41)]) { const r = L(dir, ["note", "--type", "lesson", "--text", "One rule", "--kind", "convention", "--about", "src/a.js", "--source", "said", "--skill", skill], store); assert.equal(r.code, 4, r.stdout); assert.equal(r.json.error, "invalid-lesson"); } assert.deepEqual(waitingFiles(store), []); }); test("lessons note: does nothing while off or paused, holds the lesson while not set up and on", () => { const dir = repo(); const store = learningDir(); const notSetUp = L(dir, lesson("Use the flat keys", ["--why", "Ask Jane Doe"]), store); assert.equal(notSetUp.code, 0, notSetUp.stderr); assert.equal(notSetUp.json.noted, true); assert.equal(notSetUp.json.line, "Noted for the end of the run: Use the flat keys"); assert.deepEqual(notSetUp.json.flags, [{ pattern: "person-name", part: "Jane Doe" }]); assert.equal(waitingFiles(store).length, 1); settings(dir, { format: 1, learning: "off" }); const off = L(dir, lesson("Another one"), store); assert.deepEqual(off.json, { ok: true, state: "off", active: false, noted: false }); settings(dir, { format: 1, learning: "on" }); L(dir, ["pause", "on"], store); const paused = L(dir, lesson("Another one"), store); assert.equal(paused.code, 0); assert.equal(paused.json.noted, false); assert.equal(waitingFiles(store).length, 1, "nothing more was written"); L(dir, ["pause", "off"], store); const dry = L(dir, lesson("A dry one", ["--dry-run"]), store); assert.equal(dry.json.noted, true); assert.equal(waitingFiles(store).length, 1, "--dry-run writes nothing"); }); test("lessons note: an area needs a plain name and supported globs inside the repository", () => { const dir = repo(); const store = learningDir(); const area = (name, paths) => L(dir, ["note", "--type", "area", "--name", name, "--paths", paths, "--skill", "Implement"], store); for (const name of ["General", "!!!"]) { const r = area(name, "src/**"); assert.equal(r.code, 4, name); assert.equal(r.json.error, "bad-area", name); } for (const paths of ["../x/**", "src/[ab]/**", "/abs/**", Array.from({ length: 9 }, (_, i) => `p${i}/**`).join(",")]) { const r = area("Web", paths); assert.equal(r.code, 4, paths); assert.equal(r.json.error, "invalid-area", paths); } // Each brace alternative must stay inside the repository too. for (const paths of ["{..,src}/**", "{/etc,src}/**", "src/{a,..}/**"]) { const r = area("Web", paths); assert.equal(r.code, 4, paths); assert.equal(r.json.error, "invalid-area", paths); } const ok = area("Web console", "src/web-console/**, scripts/test-web-console-*.mjs"); assert.equal(ok.code, 0, ok.stderr); assert.equal(ok.json.line, "Noted for the end of the run: a new area, Web console"); assert.equal(waitingFiles(store).length, 1); // A brace glob is one glob, not split on its inner comma. const brace = area("Apps", "src/{web,api}/**, bin/**"); assert.equal(brace.code, 0, brace.stdout + brace.stderr); const proposed = L(dir, ["list"], store).json.items.find((i) => i.name === "Apps"); assert.deepEqual(proposed.paths, ["src/{web,api}/**", "bin/**"]); }); test("lessons record: a Paths line with a brace glob parses whole, round trips and matches", () => { const text = "# Apps\nPaths: src/{web,api}/**, bin/**\n\n"; const area = record.parseAreaFile(text); assert.deepEqual(area.paths, ["src/{web,api}/**", "bin/**"]); assert.equal(record.renderAreaFile(area), text); const dir = repo(); write(dir, ".plan2code/lessons/apps.md", text); assert.equal(record.matchArea(dir, ["src/web/a.js"]).slug, "apps"); assert.equal(record.matchArea(dir, ["src/other/a.js"]).slug, "general"); }); test("lessons: a rejected kind, source, type, choice or about entry is never echoed", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const secret = SECRETS["aws-access-key"][0]; const runs = [ L(dir, ["note", "--type", "lesson", "--text", "A lesson", "--kind", secret, "--about", "src/a.js", "--source", "said", "--skill", "Implement"], store), L(dir, ["note", "--type", "lesson", "--text", "A lesson", "--kind", "convention", "--about", "src/a.js", "--source", secret, "--skill", "Implement"], store), L(dir, ["note", "--type", secret, "--skill", "Implement"], store), ]; for (const r of runs) { assert.notEqual(r.code, 0); assert.ok(!(r.stdout + r.stderr).includes(secret), r.stdout + r.stderr); } assert.equal(waitingFiles(store).length, 0); L(dir, lesson("First lesson"), store); L(dir, lesson("Second lesson"), store); L(dir, lesson("Third lesson"), store); const [a, b, c] = idsOf(dir, store, "First lesson", "Second lesson", "Third lesson"); const r = decide(dir, store, [ { id: a, choice: secret }, { id: b, choice: "Reword", text: "Second lesson", kind: secret }, { id: c, choice: "Reword", text: "Third lesson", about: [{ k: secret }] }, ]); assert.equal(r.code, 0, r.stdout + r.stderr); assert.deepEqual( r.json.results.map((x) => x.outcome), ["invalid-choice", "invalid", "invalid"] ); assert.ok(!(r.stdout + r.stderr).includes(secret), r.stdout); assert.equal(r.json.stillWaiting, 3); const broken = path.join(tmp("lessons-broken"), "d.json"); fs.writeFileSync(broken, `[{ "id": "x", "choice": "Reword", "text": "${secret}" `); const bad = L(dir, ["decide", "--file", broken], store); assert.equal(bad.json.error, "invalid-file"); assert.ok(!(bad.stdout + bad.stderr).includes(secret), "a broken decisions file is never quoted back"); }); test("lessons note: a branch name holding a secret is never stored", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const branch = "fix/tok" + "en=abcdefgh123"; gitIn(dir)("checkout", "-q", "-b", branch); const r = L(dir, lesson("A lesson"), store); assert.equal(r.code, 0, r.stderr); const files = waitingFiles(store); assert.equal(files.length, 1); const item = JSON.parse(fs.readFileSync(path.join(store, files[0]), "utf8")); assert.equal(item.branch, ""); assert.ok(!L(dir, ["list"], store).stdout.includes("abcdefgh123")); }); test("lessons areas --suggest: unshared test map rows that are not area files yet", () => { const dir = repo(); const store = learningDir(); assert.deepEqual(L(dir, ["areas", "--suggest"], store).json.areas, [], "no AGENTS.md, no suggestions"); write( dir, "AGENTS.md", [ "# Agents", "", "## Test map", "", "| Area | Paths | Run | Shared |", "| --- | --- | --- | --- |", "| Web console | `src/web-console/**` | npm test | no |", "| Launcher | `src/launcher/**`, `bin/**` | npm test | no |", "| Helpers | `scripts/*-helpers.mjs` | npm test | yes |", "", ].join("\n") ); write(dir, ".plan2code/lessons/launcher.md", "# Launcher\nPaths: src/launcher/**\n"); const r = L(dir, ["areas", "--suggest"], store); assert.equal(r.code, 0, r.stderr); assert.deepEqual(r.json.areas, [{ name: "Web console", paths: ["src/web-console/**"] }]); }); /* ------------------------------------------------------- list and decide */ const ids = (dir, store) => L(dir, ["list"], store).json.items.map((i) => i.id); // Items noted under the pinned clock share one time, so their order is the // random part of the id: find them by their text (or an area's name). const idsOf = (dir, store, ...texts) => { const items = L(dir, ["list"], store).json.items; return texts.map((t) => items.find((i) => i.text === t || i.name === t).id); }; const decide = (dir, store, decisions, extra = []) => { const file = path.join(tmp("lessons-decide"), "decisions.json"); fs.writeFileSync(file, JSON.stringify(decisions)); return L(dir, ["decide", "--file", file, ...extra], store); }; test("lessons list: origin lines, the other-branch note and the main-branch opening", () => { const dir = repo(); const store = learningDir(); const g = gitIn(dir); settings(dir, { format: 1, learning: "on" }); g("checkout", "-q", "-b", "feature/x"); write(dir, "src/only-here.js", "x\n"); g("add", "-A"); g("commit", "-q", "-m", "feature file"); L(dir, ["note", "--type", "lesson", "--text", "Keep it short", "--kind", "convention", "--about", "src/only-here.js", "--source", "inferred", "--seen", "src/only-here.js,src/b.js", "--skill", "Implement"], store); const onFeature = L(dir, ["list"], store).json; assert.equal(onFeature.opening, null, "not on the default branch"); assert.equal(onFeature.items[0].note, ""); assert.equal(onFeature.items[0].origin, "Seen in the code, in src/only-here.js, src/b.js."); g("checkout", "-q", "main"); L(dir, lesson("Said aloud"), store); const r = L(dir, ["list"], store); assert.equal(r.code, 0, r.stderr); const inferred = r.json.items.find((i) => i.text === "Keep it short"); const said = r.json.items.find((i) => i.text === "Said aloud"); assert.equal(r.json.opening, "You are on main: kept lessons will be uncommitted changes here."); assert.equal(inferred.note, "Noted on feature/x. Its files are not on this branch."); assert.deepEqual(inferred.choices, ["Keep", "Reword", "Drop"]); assert.equal(said.origin, "You said this."); assert.equal(said.note, ""); assert.equal(said.area, "General"); assert.equal(r.json.card.kind, "lessons"); assert.equal(r.json.card.opening, r.json.opening); assert.deepEqual( r.json.card.rows.map((row) => row.id), r.json.items.map((i) => i.id) ); assert.deepEqual( r.json.rounds.map((round) => round.type), ["lesson"] ); const empty = L(repo(), ["list"], learningDir()).json; assert.deepEqual(empty.items, []); assert.equal(empty.card, null); }); test("lessons list: an item whose text is now refused is listed without Keep and without the secret", () => { const dir = repo(); const store = learningDir(); waiting(dir, store, daysBefore(1), "20260802-140500-aaaaaa"); const file = fs .readdirSync(store, { recursive: true }) .map(String) .find((f) => f.endsWith("aaaaaa.json")); const full = path.join(store, file); const item = JSON.parse(fs.readFileSync(full, "utf8")); fs.writeFileSync(full, JSON.stringify({ ...item, text: `Use ${SECRETS["stripe-key"][0]} here`, kind: "convention", about: ["a.js"], source: "said", skill: "Implement" })); const r = L(dir, ["list"], store); assert.equal(r.json.items[0].refused.pattern, "stripe-key"); assert.deepEqual(r.json.items[0].choices, ["Reword", "Drop"]); assert.ok(!r.stdout.includes(SECRETS["stripe-key"][0])); }); test("lessons decide: Keep writes a block at its alphabetical place, nothing staged", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); write(dir, ".plan2code/lessons/web-console.md", AREA_TEXT); L(dir, ["note", "--type", "lesson", "--text", "Build the skills before the tests", "--kind", "command", "--about", "src/web-console/x.mjs", "--source", "said", "--skill", "Implement"], store); const r = decide(dir, store, [{ id: ids(dir, store)[0], choice: "Keep" }]); assert.equal(r.code, 0, r.stderr); assert.deepEqual(r.json.written, [".plan2code/lessons/web-console.md"]); assert.equal(r.json.results[0].outcome, "kept"); assert.equal(r.json.results[0].lesson, "web-console/build-the-skills-before-the-tests"); assert.equal(r.json.closing, "Kept 1. 0 still waiting."); const text = read(dir, ".plan2code/lessons/web-console.md"); const at = AREA_TEXT.indexOf("### Cut"); assert.equal(text, AREA_TEXT.slice(0, at) + "### Build the skills before the tests\n- Kind: command\n- About: src/web-console/x.mjs\n- Noted: 2026-08-03, Implement\n\n" + AREA_TEXT.slice(at)); assert.deepEqual(waitingFiles(store), []); assert.equal(gitIn(dir)("diff", "--cached", "--name-only").trim(), "", "nothing staged"); }); test("lessons decide: two branches keeping different lessons in one area merge without a conflict", () => { const dir = repo(); const store = learningDir(); const g = gitIn(dir); settings(dir, { format: 1, learning: "on" }); write(dir, ".plan2code/lessons/web-console.md", "# Web console\nPaths: src/web-console/**\n\n### Middle lesson\n- Kind: convention\n- About: src/web-console/m.mjs\n- Noted: 2026-11-01, Implement\n"); g("add", "-A"); g("commit", "-q", "-m", "area"); const keepOn = (branch, text) => { g("checkout", "-q", "-b", branch, "main"); L(dir, ["note", "--type", "lesson", "--text", text, "--kind", "convention", "--about", "src/web-console/a.mjs", "--source", "said", "--skill", "Implement"], store); assert.equal(decide(dir, store, [{ id: ids(dir, store)[0], choice: "Keep" }]).json.results[0].outcome, "kept"); g("commit", "-q", "-am", branch); }; keepOn("a", "Alpha lesson first"); keepOn("b", "Zulu lesson last"); g("checkout", "-q", "a"); g("merge", "-q", "--no-edit", "b"); const headings = read(dir, ".plan2code/lessons/web-console.md").match(/^### .*$/gm); assert.deepEqual(headings, ["### Alpha lesson first", "### Middle lesson", "### Zulu lesson last"]); }); test("lessons decide: the 26th general lesson comes back as needsRoom and keeps waiting", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const blocks = Array.from({ length: 25 }, (_, i) => `### General lesson ${String(i).padStart(2, "0")}\n- Kind: convention\n- About: a.js\n- Noted: 2026-11-01, Implement\n`); write(dir, ".plan2code/lessons/general.md", "# General\n\n" + blocks.join("\n")); L(dir, lesson("One lesson too many"), store); const r = decide(dir, store, [{ id: ids(dir, store)[0], choice: "Keep" }]); assert.equal(r.json.results[0].outcome, "needsRoom"); assert.equal(r.json.stillWaiting, 1); assert.deepEqual(r.json.written, []); assert.equal(r.json.closing, "Nothing decided. 1 still waiting."); assert.equal(read(dir, ".plan2code/lessons/general.md").match(/^### /gm).length, 25); }); test("lessons decide: a lesson whose proposed area is dropped lands in a matching area, else general.md", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); write(dir, ".plan2code/lessons/source.md", "# Source\nPaths: src/**\n"); L(dir, ["note", "--type", "area", "--name", "Web", "--paths", "src/web/**", "--skill", "Implement"], store); L(dir, ["note", "--type", "lesson", "--text", "Web lesson", "--kind", "convention", "--about", "src/web/a.js", "--source", "said", "--skill", "Implement", "--area", "Web"], store); L(dir, ["note", "--type", "lesson", "--text", "Docs lesson", "--kind", "convention", "--about", "docs/a.md", "--source", "said", "--skill", "Implement", "--area", "Web"], store); const listed = L(dir, ["list"], store).json; assert.deepEqual( listed.rounds.map((round) => round.type), ["area", "lesson"] ); assert.equal(listed.items.find((i) => i.text === "Web lesson").area, "Web", "the proposed area, while it waits"); const [areaId, webId, docsId] = idsOf(dir, store, "Web", "Web lesson", "Docs lesson"); // Lessons first in the file: areas are still decided first. const r = decide(dir, store, [ { id: webId, choice: "Keep" }, { id: docsId, choice: "Keep" }, { id: areaId, choice: "Drop" }, ]); assert.equal(r.code, 0, r.stderr); const by = Object.fromEntries(r.json.results.map((x) => [x.id, x])); assert.equal(by[areaId].outcome, "dropped"); assert.equal(by[webId].area, "Source"); assert.equal(by[docsId].area, "General"); assert.deepEqual(r.json.written, [".plan2code/lessons/general.md", ".plan2code/lessons/source.md"]); assert.equal(r.json.closing, "Kept 2, dropped 1. 0 still waiting."); }); test("lessons decide: Create then Keep into the new area, Rename, and unknown ids", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); L(dir, ["note", "--type", "area", "--name", "Web", "--paths", "src/web/**", "--skill", "Implement"], store); L(dir, ["note", "--type", "area", "--name", "Docs", "--paths", "docs/**", "--skill", "Implement"], store); L(dir, ["note", "--type", "lesson", "--text", "Web lesson", "--kind", "convention", "--about", "src/web/a.js", "--source", "said", "--skill", "Implement"], store); const [web, docs, one] = idsOf(dir, store, "Web", "Docs", "Web lesson"); const r = decide(dir, store, [ { id: one, choice: "Keep" }, { id: web, choice: "Create" }, { id: docs, choice: "Rename", name: "Written docs" }, { id: "20200101-000000-ffffff", choice: "Keep" }, ]); assert.equal(r.code, 0, r.stderr); assert.equal(r.json.results.find((x) => x.id === one).area, "Web"); assert.equal(r.json.results.find((x) => x.id === "20200101-000000-ffffff").outcome, "unknown"); assert.equal(read(dir, ".plan2code/lessons/written-docs.md"), "# Written docs\nPaths: docs/**\n"); assert.ok(read(dir, ".plan2code/lessons/web.md").startsWith("# Web\nPaths: src/web/**\n\n### Web lesson\n")); assert.equal(r.json.closing, "Kept 1, created 2 areas. 0 still waiting."); }); test("lessons decide: Reword with a secret is refused and keeps waiting while another item is kept", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); L(dir, lesson("First lesson"), store); L(dir, lesson("Second lesson"), store); const [first, second] = ids(dir, store); const r = decide(dir, store, [ { id: first, choice: "Reword", text: `Use ${SECRETS["github-token"][0]} for the push` }, { id: second, choice: "Reword", text: "Second lesson, reworded", why: "it read badly" }, ]); assert.equal(r.code, 0, r.stderr); const by = Object.fromEntries(r.json.results.map((x) => [x.id, x])); assert.equal(by[first].outcome, "refused"); assert.equal(by[first].pattern, "github-token"); assert.equal(by[second].outcome, "reworded"); assert.ok(!r.stdout.includes(SECRETS["github-token"][0])); assert.equal(r.json.stillWaiting, 1); assert.equal(r.json.closing, "Kept 1 (1 reworded). 1 still waiting."); assert.ok(!read(dir, ".plan2code/lessons/general.md").includes("ghp"), "the secret never reached the file"); }); test("lessons decide: a Rename holding a secret is refused, and a bad about in one item never loses another", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); L(dir, ["note", "--type", "area", "--name", "Web", "--paths", "src/web/**", "--skill", "Implement"], store); L(dir, lesson("Kept lesson"), store); L(dir, lesson("Broken lesson"), store); const [area, kept, broken] = idsOf(dir, store, "Web", "Kept lesson", "Broken lesson"); const r = decide(dir, store, [ { id: area, choice: "Rename", name: SECRETS["assigned-secret"][0] }, { id: kept, choice: "Keep" }, { id: broken, choice: "Reword", text: "Broken lesson", about: [1] }, ]); assert.equal(r.code, 0, r.stdout + r.stderr); const by = Object.fromEntries(r.json.results.map((x) => [x.id, x])); assert.equal(by[area].outcome, "refused"); assert.equal(by[kept].outcome, "kept"); assert.equal(by[broken].outcome, "invalid"); assert.ok(!r.stdout.includes("hunter2hunter2")); assert.equal(r.json.stillWaiting, 2); assert.deepEqual(r.json.written, [".plan2code/lessons/general.md"]); assert.equal(fs.readdirSync(path.join(dir, ".plan2code", "lessons")).length, 1, "no area file named after the secret"); }); test("lessons decide: --dry-run changes no file and no waiting item", () => { const dir = repo(); const store = learningDir(); const g = gitIn(dir); settings(dir, { format: 1, learning: "on" }); g("add", "-A"); g("commit", "-q", "-m", "on"); L(dir, ["note", "--type", "area", "--name", "Web", "--paths", "src/web/**", "--skill", "Implement"], store); L(dir, lesson("A lesson"), store); const before = waitingFiles(store).sort(); const [area, one] = idsOf(dir, store, "Web", "A lesson"); const r = decide( dir, store, [ { id: area, choice: "Create" }, { id: one, choice: "Keep" }, ], ["--dry-run"] ); assert.equal(r.code, 0, r.stderr); assert.equal(r.json.dryRun, true); assert.deepEqual(r.json.written, []); assert.equal(r.json.closing, "Kept 1, created 1 area. 0 still waiting."); assert.equal(g("status", "--porcelain", "--untracked-files=all").trim(), ""); assert.deepEqual(waitingFiles(store).sort(), before); }); test("lessons decide: a bad decisions file and a choice that does not fit", () => { const dir = repo(); const store = learningDir(); assert.equal(L(dir, ["decide", "--file", path.join(tmp("lessons-none"), "missing.json")], store).code, 3); const bad = path.join(tmp("lessons-bad"), "d.json"); fs.writeFileSync(bad, "{ nope"); assert.equal(L(dir, ["decide", "--file", bad], store).json.error, "invalid-file"); L(dir, lesson("A lesson"), store); const r = decide(dir, store, [{ id: ids(dir, store)[0], choice: "Create" }]); assert.equal(r.json.results[0].outcome, "invalid-choice"); assert.equal(r.json.stillWaiting, 1); }); /* ------------------------------------------- marking: git history as the clock */ // One area file with one lesson about src/app.js. Each fixture is built once // (copyFixture) and copied per test. const WEB_AREA = "# Web\nPaths: src/**\n\n### Keep the handler small\n- Kind: convention\n- About: src/app.js\n- Noted: 2026-11-01, Implement\n"; const WEB_FILE = ".plan2code/lessons/web.md"; const commitAll = (g, msg) => { g("add", "-A"); g("commit", "-q", "-m", msg); }; // A base commit with src/app.js and README.md on main. const baseRepo = (dir) => { const g = gitInit(dir); write(dir, "README.md", "# Fixture\n"); write(dir, "src/app.js", "export const app = 1;\n"); commitAll(g, "base"); return g; }; const marks = (dir) => Object.fromEntries(record.markLessons(dir, record.readLessons(dir)).map((l) => [l.id, { marked: l.marked, gone: l.gone }])); const LESSON_ID = "web/keep-the-handler-small"; // (a) the lesson, then an edit to its file in a later commit. const markA = () => copyFixture("mark-a", "mark-a", (dir) => { const g = baseRepo(dir); write(dir, WEB_FILE, WEB_AREA); commitAll(g, "lesson"); write(dir, "src/app.js", "export const app = 2;\n"); commitAll(g, "edit"); }); test("lessons marking (a): an edit committed after the lesson marks it", () => { assert.deepEqual(marks(markA())[LESSON_ID], { marked: true, gone: false }); }); test("lessons marking (b): the lesson and the edit in one commit do not mark it", () => { const dir = copyFixture("mark-b", "mark-b", (d) => { const g = baseRepo(d); write(d, WEB_FILE, WEB_AREA); write(d, "src/app.js", "export const app = 2;\n"); commitAll(g, "lesson and edit"); }); assert.deepEqual(marks(dir)[LESSON_ID], { marked: false, gone: false }); }); test("lessons marking (c): a squash merge of a branch that kept the lesson and then edited does not mark it on main", () => { const dir = copyFixture("mark-c", "mark-c", (d) => { const g = baseRepo(d); g("checkout", "-q", "-b", "feature"); write(d, WEB_FILE, WEB_AREA); commitAll(g, "lesson"); write(d, "src/app.js", "export const app = 2;\n"); commitAll(g, "edit"); g("checkout", "-q", "main"); write(d, "README.md", "# Fixture moved\n"); commitAll(g, "main moves"); }); const g = gitIn(dir); g("checkout", "-q", "feature"); assert.equal(marks(dir)[LESSON_ID].marked, true, "marked on the branch, where the edit came after the lesson"); g("checkout", "-q", "main"); g("merge", "-q", "--squash", "feature"); g("commit", "-q", "-m", "squash feature"); assert.equal(marks(dir)[LESSON_ID].marked, false, "one squash commit holds both"); }); test("lessons marking (d): a rebase alone does not mark a lesson; a later edit does", () => { const dir = copyFixture("mark-d", "mark-d", (d) => { const g = baseRepo(d); g("checkout", "-q", "-b", "feature"); write(d, "src/app.js", "export const app = 2;\n"); commitAll(g, "edit"); write(d, WEB_FILE, WEB_AREA); commitAll(g, "lesson"); g("checkout", "-q", "main"); write(d, "README.md", "# Fixture moved\n"); commitAll(g, "main moves"); g("checkout", "-q", "feature"); }); const g = gitIn(dir); assert.equal(marks(dir)[LESSON_ID].marked, false, "before the rebase"); g("rebase", "-q", "main"); assert.equal(marks(dir)[LESSON_ID].marked, false, "after the rebase"); write(dir, "src/app.js", "export const app = 3;\n"); commitAll(g, "later edit"); assert.equal(marks(dir)[LESSON_ID].marked, true, "after a later edit"); }); test("lessons marking (e): a shallow clone leaves the lesson unmarked", () => { const source = markA(); const clone = path.join(tmp("mark-e"), "clone"); gitIn(path.dirname(clone))("clone", "-q", "--depth", "1", `file:///${slashed(source).replace(/^\/+/, "")}`, clone); const blame = record.blockCommits(clone, path.join(clone, WEB_FILE), record.readLessons(clone).map((l) => l.block)); assert.equal(blame[0].boundary, true, "the shallow history's edge"); assert.deepEqual(marks(clone)[LESSON_ID], { marked: false, gone: false }); }); test("lessons marking (f): an uncommitted new block beside a committed edit is not marked", () => { const dir = markA(); write(dir, WEB_FILE, WEB_AREA + "\n### Name the handler after its route\n- Kind: convention\n- About: src/app.js\n- Noted: 2026-11-02, Implement\n"); const m = marks(dir); assert.deepEqual(m["web/name-the-handler-after-its-route"], { marked: false, gone: false }); assert.equal(m[LESSON_ID].marked, true, "the committed block beside it still is"); const blame = record.blockCommits(dir, path.join(dir, WEB_FILE), record.readLessons(dir).map((l) => l.block)); assert.deepEqual( blame.map((b) => b.uncommitted), [false, true] ); }); test("lessons marking (g): a folder with no .git is not marked and raises no error", () => { const dir = tmp("mark-g"); write(dir, WEB_FILE, WEB_AREA); write(dir, "src/app.js", "x\n"); assert.equal(record.blockCommits(dir, path.join(dir, WEB_FILE), record.readLessons(dir).map((l) => l.block)), null); assert.deepEqual(marks(dir)[LESSON_ID], { marked: false, gone: false }); }); test("lessons marking (h): a lesson whose only About file was deleted is gone", () => { const dir = markA(); const g = gitIn(dir); g("rm", "-q", "src/app.js"); g("commit", "-q", "-m", "delete app"); assert.equal(marks(dir)[LESSON_ID].gone, true); }); test("lessons marking: a folder About is marked by an edit to a file under it", () => { const dir = copyFixture("mark-folder", "mark-folder", (d) => { const g = baseRepo(d); write(d, WEB_FILE, WEB_AREA.replace("- About: src/app.js", "- About: src/")); commitAll(g, "lesson"); write(d, "src/other.js", "x\n"); commitAll(g, "add a file under src"); }); assert.equal(marks(dir)[LESSON_ID].marked, true); }); test("lessons marking: a lesson in a repository's first commit is a real commit, not a boundary", () => { const dir = copyFixture("mark-root", "mark-root", (d) => { const g = gitInit(d); write(d, "src/app.js", "x\n"); write(d, WEB_FILE, WEB_AREA); commitAll(g, "first"); write(d, "src/app.js", "y\n"); commitAll(g, "edit"); }); assert.equal(marks(dir)[LESSON_ID].marked, true); }); /* ------------------------------------------------------------------ read */ const block = (heading, about, why = "") => `### ${heading}\n- Kind: convention\n- About: ${about}\n${why ? `- Why: ${why}\n` : ""}- Noted: 2026-11-01, Implement\n`; // Learning on, committed on main: two general lessons, one for Web (src/web/**) // and two for Source (src/**), which overlap. const readRepo = () => copyFixture("lessons-read", "read-repo", (dir) => { const g = gitInit(dir); write(dir, ".plan2code/settings.json", JSON.stringify({ format: 1, learning: "on" })); write(dir, "src/web/page.js", "x\n"); write(dir, "src/core.js", "x\n"); write(dir, "docs/a.md", "x\n"); write(dir, ".plan2code/lessons/general.md", "# General\n\n" + block("Answer in US English", "README.md") + "\n" + block("Run the targeted suites", "scripts/", "The full run is slow.")); write(dir, ".plan2code/lessons/web.md", "# Web\nPaths: src/web/**\n\n" + block("Draw the page from state", "src/web/page.js")); write(dir, ".plan2code/lessons/source.md", "# Source\nPaths: src/**\n\n" + block("Keep modules small", "src/core.js") + "\n" + block("Name files in kebab case", "src/")); write(dir, "README.md", "# R\n"); write(dir, "scripts/x.mjs", "x\n"); commitAll(g, "init"); }); const storeListing = (store) => (fs.existsSync(store) ? fs.readdirSync(store, { recursive: true }).map(String).sort() : []); test("lessons read: no paths and no changes give general only, and read writes nothing", () => { const dir = readRepo(); const store = learningDir(); const before = { status: gitIn(dir)("status", "--porcelain"), store: storeListing(store) }; const r = L(dir, ["read"], store); assert.equal(r.code, 0, r.stderr); assert.equal(r.json.state, "on"); assert.deepEqual(r.json.areas, []); assert.deepEqual(r.json.general, [ { id: "general/answer-in-us-english", text: "Answer in US English", why: "", marked: false, gone: false }, { id: "general/run-the-targeted-suites", text: "Run the targeted suites", why: "The full run is slow.", marked: false, gone: false }, ]); assert.equal(r.json.line, "Read 2 general lessons; none yet for these files."); assert.deepEqual(r.json.logLines, []); assert.equal(r.json.headsUp, undefined, "nothing waiting"); assert.deepEqual(record.decodeRun(r.json.run), ["general"]); assert.deepEqual({ status: gitIn(dir)("status", "--porcelain"), store: storeListing(store) }, before, "read writes nothing"); }); test("lessons read: overlapping areas both return, and a second call hands over only the new area", () => { const dir = readRepo(); const store = learningDir(); const first = L(dir, ["read", "--paths", "src/web/page.js"], store).json; assert.deepEqual( first.areas.map((a) => [a.name, a.slug, a.lessons.length]), [ ["Source", "source", 2], ["Web", "web", 1], ] ); assert.equal(first.line, "Read 2 general lessons and 3 for Source and Web."); const lesson = first.areas[1].lessons[0]; assert.deepEqual(Object.keys(lesson).sort(), ["gone", "id", "marked", "text", "why"], "two lines of content and the two marks, nothing else"); // Only Source first, then the web folder: Web alone, with no general list. const one = L(dir, ["read", "--paths", "src/core.js"], store).json; assert.deepEqual( one.areas.map((a) => a.slug), ["source"] ); assert.equal(one.line, "Read 2 general lessons and 2 for Source."); const two = L(dir, ["read", "--paths", "src/web/", "--run", one.run], store).json; assert.deepEqual( two.areas.map((a) => a.slug), ["web"] ); assert.equal(two.general, null); assert.equal(two.line, "Read 1 more for Web."); assert.equal(two.logLines, undefined, "a later call carries no first-call extras"); const three = L(dir, ["read", "--paths", "src/web/page.js", "--run", two.run], store).json; assert.deepEqual(three.areas, []); assert.equal(three.line, "", "nothing new matched"); }); test("lessons read: the changed files on the branch pick the areas", () => { const dir = readRepo(); const store = learningDir(); const g = gitIn(dir); g("checkout", "-q", "-b", "feature/x"); write(dir, "src/web/page.js", "changed\n"); commitAll(g, "change the page"); const r = L(dir, ["read"], store).json; assert.deepEqual( r.areas.map((a) => a.slug), ["source", "web"] ); }); test("lessons read: changedFiles on a feature branch and on the default branch", () => { const dir = readRepo(); const g = gitIn(dir); write(dir, "docs/new.md", "x\n"); assert.deepEqual(record.changedFiles(dir), ["docs/new.md"], "on main: git status only"); g("checkout", "-q", "-b", "feature/x"); commitAll(g, "add docs"); write(dir, "src/core.js", "changed\n"); fs.renameSync(path.join(dir, "docs/a.md"), path.join(dir, "docs/b.md")); assert.deepEqual(record.changedFiles(dir), ["docs/a.md", "docs/b.md", "docs/new.md", "src/core.js"], "the merge base diff plus git status"); assert.deepEqual(record.changedFiles(tmp("changed-nogit")), [], "outside git"); }); test("lessons read: every form of the line, singular and plural", () => { assert.equal(record.readLine({ first: true, general: 1, areas: [], empty: false }), "Read 1 general lesson; none yet for these files."); assert.equal(record.readLine({ first: true, general: 3, areas: [], empty: false }), "Read 3 general lessons; none yet for these files."); assert.equal(record.readLine({ first: true, general: 1, areas: [{ name: "Web", count: 1 }], empty: false }), "Read 1 general lesson and 1 for Web."); assert.equal( record.readLine({ first: true, general: 4, areas: [ { name: "A", count: 2 }, { name: "B", count: 0 }, { name: "C", count: 1 }, { name: "D", count: 3 }, ], empty: false, }), "Read 4 general lessons and 6 for A, C and D." ); assert.equal(record.readLine({ first: true, general: 0, areas: [], empty: true }), "No lessons yet."); assert.equal(record.readLine({ first: false, general: 0, areas: [{ name: "Web", count: 1 }] }), "Read 1 more for Web."); assert.equal( record.readLine({ first: false, general: 0, areas: [ { name: "Web", count: 2 }, { name: "API", count: 1 }, ], }), "Read 3 more for Web and API." ); assert.equal(record.readLine({ first: false, general: 0, areas: [{ name: "Web", count: 0 }] }), ""); assert.equal(record.headsUpLine(1, 1), "1 lesson waiting from an earlier run (oldest 1 day). Review now or Later."); assert.equal(record.headsUpLine(3, 0), "3 lessons waiting from an earlier run (oldest 0 days). Review now or Later."); assert.equal(record.headsUpLine(2, 12), "2 lessons waiting from an earlier run (oldest 12 days). Review now or Later."); const empty = repo(); settings(empty, { format: 1, learning: "on" }); assert.equal(L(empty, ["read"], learningDir()).json.line, "No lessons yet."); }); test("lessons read: headsUp on the first call, left out under --from-banner and on a later call", () => { const dir = readRepo(); const store = learningDir(); waiting(dir, store, daysBefore(3)); waiting(dir, store, daysBefore(1)); const r = L(dir, ["read"], store).json; assert.deepEqual(r.headsUp, { count: 2, oldestDays: 3, line: "2 lessons waiting from an earlier run (oldest 3 days). Review now or Later." }); assert.equal(L(dir, ["read", "--from-banner"], store).json.headsUp, undefined); assert.equal(L(dir, ["read", "--run", r.run], store).json.headsUp, undefined); }); test("lessons read: not on returns no lessons; paused says so; not set up still returns run; a bad handle is exit 2", () => { const dir = readRepo(); const store = learningDir(); assert.equal(L(dir, ["pause", "on"], store).code, 0); assert.deepEqual(L(dir, ["read"], store).json, { ok: true, state: "paused", active: false, line: "Learning is paused for you." }); settings(dir, { format: 1, learning: "off" }); assert.deepEqual(L(dir, ["read"], store).json, { ok: true, state: "off", active: false, line: "" }); fs.rmSync(path.join(dir, ".plan2code/settings.json")); const fresh = L(dir, ["read"], store).json; assert.equal(fresh.state, "not-set-up"); assert.equal(fresh.line, ""); assert.deepEqual(record.decodeRun(fresh.run), []); assert.equal(fresh.general, undefined); const enc = (s) => "r1." + Buffer.from(s).toString("base64url"); for (const bad of ["nope", "r1.!!", enc("{}"), enc(JSON.stringify(["../x"]))]) { const r = L(dir, ["read", "--run", bad], store); assert.equal(r.code, 2, bad); assert.equal(r.json.error, "bad-run", bad); } }); test("lessons read: with no git to find, lessons come back unmarked and exit 0", () => { const dir = markA(); settings(dir, { format: 1, learning: "on" }); const env = scrubbedEnv({ PLAN2CODE_NOW: NOW, PLAN2CODE_LEARNING_DIR: learningDir() }); for (const k of Object.keys(env)) if (/^path$/i.test(k)) delete env[k]; env.PATH = ""; const r = spawnSync(process.execPath, [path.join(SKILLS, "plan2code-quick-task", "scripts", "lessons.mjs"), "read", "--paths", "src/app.js"], { cwd: dir, encoding: "utf8", env }); assert.equal(r.status, 0, r.stderr); const json = JSON.parse(r.stdout); assert.deepEqual(json.areas[0].lessons[0], { id: LESSON_ID, text: "Keep the handler small", why: "", marked: false, gone: false }); assert.equal(L(dir, ["read", "--paths", "src/app.js"], learningDir()).json.areas[0].lessons[0].marked, true, "with git, the same lesson is marked"); }); /* ------------------------------------------------ doubts, gone and report */ const doubt = (target, found = "The handler now does three things.") => ["note", "--type", "doubt", "--target", target, "--found", found, "--skill", "Implement"]; test("lessons note doubt: validated, written once per lesson, and listed with the saved lesson", () => { const dir = markA(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const missing = L(dir, doubt("web/no-such-lesson"), store); assert.equal(missing.code, 4); assert.equal(missing.json.error, "invalid-doubt"); const two = L(dir, doubt(LESSON_ID, "It grew. It now routes too."), store); assert.equal(two.code, 4, "found is one sentence"); const secret = L(dir, doubt(LESSON_ID, `It reads ${SECRETS["stripe-key"][0]} now.`), store); assert.equal(secret.code, 5); assert.ok(!secret.stdout.includes(SECRETS["stripe-key"][0])); assert.deepEqual(waitingFiles(store), [], "nothing written for a refused doubt"); const r = L(dir, doubt(LESSON_ID), store); assert.equal(r.code, 0, r.stderr); assert.equal(r.json.noted, true); assert.equal(r.json.line, `Noted for the end of the run: a doubt about ${LESSON_ID}`); const again = L(dir, doubt(LESSON_ID, "Something else."), store); assert.equal(again.json.noted, false); assert.equal(again.json.already, true); assert.equal(again.json.id, r.json.id); assert.equal(waitingFiles(store).length, 1, "a second doubt for the same lesson is not written"); const list = L(dir, ["list"], store).json; assert.equal(list.items.length, 1); const item = list.items[0]; assert.equal(item.type, "doubt"); assert.equal(item.heading, "This lesson may no longer be true:"); assert.equal(item.text, "Keep the handler small"); assert.equal(item.found, "The handler now does three things."); assert.deepEqual(item.choices, ["Keep", "Reword", "Retire"]); assert.equal(item.area, "Web"); assert.deepEqual( list.rounds.map((round) => round.type), ["doubt"] ); assert.equal(list.card.rows[0].origin, "This lesson may no longer be true: The handler now does three things."); }); test("lessons list: a saved lesson whose files are gone is listed with nothing waiting", () => { const dir = markA(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); fs.rmSync(path.join(dir, "src/app.js")); const list = L(dir, ["list"], store).json; assert.deepEqual( list.items.map((i) => [i.id, i.type, i.heading, i.choices.join(",")]), [[`gone:${LESSON_ID}`, "gone", "Its files no longer exist.", "Keep,Reword,Retire"]] ); // A waiting doubt about the same lesson stands in for it. fs.writeFileSync(path.join(dir, "src/app.js"), "back\n"); L(dir, doubt(LESSON_ID), store); fs.rmSync(path.join(dir, "src/app.js")); assert.deepEqual( L(dir, ["list"], store).json.items.map((i) => i.type), ["doubt"] ); }); test("lessons decide: a doubt kept moves the checked date and nothing else, and the commit unmarks it", () => { const dir = markA(); const store = learningDir(); const g = gitIn(dir); settings(dir, { format: 1, learning: "on" }); write(dir, WEB_FILE, WEB_AREA.replace("- Noted: 2026-11-01, Implement", "- Noted: 2026-11-01, Implement, checked 2026-11-05")); commitAll(g, "an earlier check"); write(dir, "src/app.js", "export const app = 9;\n"); commitAll(g, "edit after the check"); assert.equal(marks(dir)[LESSON_ID].marked, true); L(dir, doubt(LESSON_ID), store); const r = decide(dir, store, [{ id: ids(dir, store)[0], choice: "Keep" }]); assert.equal(r.code, 0, r.stderr); assert.equal(r.json.results[0].outcome, "kept"); assert.equal(r.json.closing, "Kept 1. 0 still waiting."); assert.deepEqual(r.json.written, [WEB_FILE]); assert.equal(read(dir, WEB_FILE), WEB_AREA.replace("- Noted: 2026-11-01, Implement", "- Noted: 2026-11-01, Implement, checked 2026-08-03")); assert.deepEqual(waitingFiles(store), []); commitAll(g, "keep the lesson"); assert.equal(marks(dir)[LESSON_ID].marked, false, "the block's own line moved past the edit"); }); test("lessons decide: Reword a doubted lesson re-sorts it, and Retire empties and removes the area file", () => { const dir = markA(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); write(dir, WEB_FILE, WEB_AREA + "\n### Name the handler after its route\n- Kind: convention\n- About: src/app.js\n- Noted: 2026-11-02, Implement\n"); L(dir, doubt(LESSON_ID), store); const reworded = decide(dir, store, [{ id: ids(dir, store)[0], choice: "Reword", text: "Answer from one small handler" }]); assert.equal(reworded.json.results[0].outcome, "reworded", JSON.stringify(reworded.json.results)); assert.equal(reworded.json.results[0].lesson, "web/answer-from-one-small-handler"); assert.deepEqual(read(dir, WEB_FILE).match(/^### .*$/gm), ["### Answer from one small handler", "### Name the handler after its route"]); assert.match(read(dir, WEB_FILE), /### Answer from one small handler\n- Kind: convention\n- About: src\/app.js\n- Noted: 2026-11-01, Implement, checked 2026-08-03\n/); fs.rmSync(path.join(dir, "src/app.js")); const gone = L(dir, ["list"], store).json.items.map((i) => i.id); assert.equal(gone.length, 2); const r = decide( dir, store, gone.map((id) => ({ id, choice: "Retire" })) ); assert.deepEqual( r.json.results.map((x) => x.outcome), ["retired", "retired"] ); assert.equal(r.json.closing, "Retired 2. 0 still waiting."); assert.deepEqual(r.json.written, [WEB_FILE]); assert.equal(fs.existsSync(path.join(dir, WEB_FILE)), false, "an emptied area file is removed"); assert.deepEqual(L(dir, ["list"], store).json.items, []); }); test("lessons decide: Retire never removes general.md", () => { const dir = readRepo(); const store = learningDir(); fs.rmSync(path.join(dir, "README.md")); fs.rmSync(path.join(dir, "scripts"), { recursive: true }); const items = L(dir, ["list"], store).json.items; assert.deepEqual( items.map((i) => i.id), ["gone:general/answer-in-us-english", "gone:general/run-the-targeted-suites"] ); const r = decide( dir, store, items.map((i) => ({ id: i.id, choice: "Retire" })) ); assert.equal(r.json.closing, "Retired 2. 0 still waiting."); assert.equal(read(dir, ".plan2code/lessons/general.md"), "# General\n"); }); test("lessons report: works while off, with counts, the oldest date, marked and gone", () => { const dir = markA(); const store = learningDir(); settings(dir, { format: 1, learning: "off" }); write(dir, ".plan2code/lessons/general.md", "# General\n\n" + block("Answer in US English", "missing.md")); write(dir, WEB_FILE, WEB_AREA + "\n### Name the handler after its route\n- Kind: convention\n- About: src/app.js\n- Noted: 2026-10-20, Implement, checked 2026-11-09\n"); const r = L(dir, ["report"], store); assert.equal(r.code, 0, r.stderr); assert.deepEqual(r.json, { ok: true, state: "off", active: false, areas: [{ name: "Web", slug: "web", paths: ["src/**"], count: 2, oldest: "2026-10-20" }], general: { count: 1, limit: 25 }, marked: [LESSON_ID], gone: ["general/answer-in-us-english"], }); }); /* ------------------------------------------------------ review fixes */ test("lessons marking: a fixed handful of git calls, however often the About file changed", () => { const dir = copyFixture("mark-busy", "mark-busy", (d) => { const g = baseRepo(d); write(d, ".plan2code/lessons/general.md", "# General\n\n" + block("Answer in US English", "README.md")); commitAll(g, "an older general lesson"); for (let i = 0; i < 12; i++) { write(d, "src/app.js", `export const app = ${i};\n`); commitAll(g, `edit ${i}`); } write(d, WEB_FILE, WEB_AREA); commitAll(g, "lesson"); }); settings(dir, { format: 1, learning: "on" }); const trace = path.join(tmp("git-trace"), "trace.txt"); const r = runScript("plan2code-quick-task", "lessons.mjs", ["read", "--paths", "src/app.js"], { cwd: dir, env: { PLAN2CODE_LEARNING_DIR: learningDir(), GIT_TRACE: trace } }); assert.equal(r.code, 0, r.stderr); assert.equal(r.json.areas[0].lessons[0].marked, false, "every edit came before the lesson"); const calls = fs .readFileSync(trace, "utf8") .split("\n") .map((l) => (l.match(/trace: built-in: git (.*)$/) || [])[1]) .filter(Boolean); const count = (re) => calls.filter((c) => re.test(c)).length; assert.equal(count(/--is-ancestor/), 0, "no ancestry check per commit"); assert.equal(count(/^blame /), 2, "one blame per returned area file"); assert.equal(count(/^merge-base .*--octopus/), 1); assert.equal(count(/^rev-list /), 1); assert.equal(count(/ log /) + count(/^log /), 1); }); test("lessons marking: an About edit on a branch beside another lesson's commit marks it whichever areas are read", () => { const dir = copyFixture("mark-parallel", "mark-parallel", (d) => { const g = baseRepo(d); g("checkout", "-q", "-b", "feature"); write(d, "src/app.js", "export const app = 2;\n"); commitAll(g, "X: edit app on the branch"); write(d, ".plan2code/lessons/lib.md", "# Lib\nPaths: lib/**\n\n" + block("Keep lib pure", "lib/x.js")); write(d, "lib/x.js", "x\n"); commitAll(g, "C1: a lib lesson after X"); g("checkout", "-q", "main"); write(d, WEB_FILE, WEB_AREA); commitAll(g, "C2: the web lesson on main"); g("merge", "-q", "--no-edit", "feature"); }); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const webAlone = L(dir, ["read", "--paths", "src/app.js"], store).json; const both = L(dir, ["read", "--paths", "src/app.js,lib/x.js"], store).json; assert.equal(webAlone.areas.find((a) => a.slug === "web").lessons[0].marked, true); assert.equal(both.areas.find((a) => a.slug === "web").lessons[0].marked, true, "the same answer with Lib read too"); assert.equal(both.areas.find((a) => a.slug === "lib").lessons[0].marked, false); assert.deepEqual(L(dir, ["report"], store).json.marked, [LESSON_ID]); }); test("lessons marking: an About path outside the repository does not unmark the others", () => { const dir = markA(); write(dir, WEB_FILE, WEB_AREA + "\n" + block("Look outside", "../outside.js")); gitIn(dir)("commit", "-q", "-am", "a hand-edited block"); const m = marks(dir); assert.equal(m[LESSON_ID].marked, true); assert.deepEqual(m["web/look-outside"], { marked: false, gone: false }); }); test("lessons read: changedFiles reads a work-tree rename's two paths", () => { const dir = readRepo(); fs.renameSync(path.join(dir, "docs/a.md"), path.join(dir, "docs/b.md")); gitIn(dir)("add", "-N", "docs/b.md"); assert.deepEqual(record.changedFiles(dir), ["docs/a.md", "docs/b.md"]); }); test("lessons read: headsUp leaves out a doubt list would not show, and read never prunes the store", () => { const dir = readRepo(); const store = learningDir(); const noted = L(dir, doubt("web/draw-the-page-from-state", "The page draws itself now."), store); assert.equal(noted.code, 0, noted.stderr); assert.equal(L(dir, ["read"], store).json.headsUp.count, 1); fs.rmSync(path.join(dir, ".plan2code/lessons/web.md")); assert.equal(L(dir, ["read"], store).json.headsUp, undefined, "its lesson was retired since"); assert.deepEqual(L(dir, ["list"], store).json.items, []); // An item past 30 days: a read leaves the file; state (which prunes) removes it. waiting(dir, store, daysBefore(31), "20260702-140500-bbbbbb"); const before = storeListing(store); L(dir, ["read"], store); assert.deepEqual(storeListing(store), before, "read writes nothing on the machine"); L(dir, ["state"], store); assert.ok(!storeListing(store).some((f) => f.includes("bbbbbb")), "the store's own reads still prune"); }); test("lessons note doubt: the target is stored as the lesson's own id", () => { const dir = markA(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const r = L(dir, doubt("web/extra/keep-the-handler-small"), store); assert.equal(r.code, 0, r.stderr); assert.equal(r.json.line, `Noted for the end of the run: a doubt about ${LESSON_ID}`); assert.equal(L(dir, doubt(LESSON_ID, "Something else."), store).json.already, true, "the same lesson, however it was named"); }); /* ------------------------------------------- AGENTS.md and the failure log */ const KEEPING = "## Keeping this file current"; const agentsDoc = ({ keeping = true, log = ["- Old line one.", "- Old line two. A second incident here."] } = {}) => [ "# AGENTS.md", "", "Intro.", "", "## Code style", "", "Use two spaces.", "", ...(keeping ? [KEEPING, "", "When you make a mistake, add a line below.", ""] : []), "## Failure log", "", ...log, ].join("\n") + "\n"; const crlf = (s) => s.replace(/\r?\n/g, "\r\n"); const readBytes = (dir, rel) => fs.readFileSync(path.join(dir, rel)); test("lessons switch: on adds the pointer line and the upkeep sentence, off gives back the same bytes", () => { const shapes = { "LF with Keeping": agentsDoc(), "CRLF with Keeping": crlf(agentsDoc()), "LF without Keeping": agentsDoc({ keeping: false }), "CRLF without Keeping": crlf(agentsDoc({ keeping: false })), "neither section": "# AGENTS.md\n\nIntro.\n", "neither, no last line break": "# AGENTS.md\n\nIntro.", "neither, ends on a blank line": "# AGENTS.md\n\nIntro.\n\n", "heading right under text": "# AGENTS.md\nIntro.\n## Keeping this file current\nAdd a line.\n", "Keeping is the last line": "# AGENTS.md\n\n## Keeping this file current", "mixed line endings": "# AGENTS.md\r\n\nIntro.\r\n\n## Keeping this file current\n\nAdd a line.\r\n", "empty file": "", }; for (const [name, text] of Object.entries(shapes)) { const dir = tmp("lessons-wording"); write(dir, "AGENTS.md", text); const original = readBytes(dir, "AGENTS.md"); const on = record.syncAgentsWording(dir, true); const after = read(dir, "AGENTS.md"); assert.deepEqual(on.written, ["AGENTS.md"], name); assert.ok(after.includes(record.POINTER_LINE), `${name}: the pointer line`); const lines = after.split(/\r?\n/); if (text.includes(KEEPING)) { assert.ok(after.includes(record.UPKEEP_SENTENCE), `${name}: the upkeep sentence`); const k = lines.indexOf(KEEPING); assert.equal(lines.slice(0, k).filter((l) => l.trim()).pop(), record.POINTER_LINE, `${name}: the pointer sits directly above the heading`); assert.equal(lines.slice(k + 1).find((l) => l.trim()), record.UPKEEP_SENTENCE, `${name}: the upkeep sentence is the first paragraph under it`); } else { assert.equal(on.skipped, "no-keeping-section", name); assert.ok(!after.includes(record.UPKEEP_SENTENCE), name); if (text.includes("## Failure log")) assert.ok(after.indexOf(record.POINTER_LINE) < after.indexOf("## Failure log"), `${name}: above the failure log`); } if (text.includes("\r\n") && !text.includes("\r\n\n")) assert.ok(!/[^\r]\n/.test(after), `${name}: CRLF kept`); assert.deepEqual(record.syncAgentsWording(dir, true).written, [], `${name}: on twice adds nothing`); record.syncAgentsWording(dir, false); assert.ok(readBytes(dir, "AGENTS.md").equals(original), `${name}: off gives back the original bytes`); } }); test("lessons switch: on writes AGENTS.md too, off takes it back; no AGENTS.md points at Init and still switches", () => { const dir = repo(); const store = learningDir(); write(dir, "AGENTS.md", agentsDoc()); const original = read(dir, "AGENTS.md"); const on = L(dir, ["switch", "on"], store); assert.equal(on.code, 0, on.stderr); assert.deepEqual(on.json.written, [".plan2code/settings.json", "AGENTS.md"]); assert.equal(on.json.next, undefined); const off = L(dir, ["switch", "off"], store); assert.deepEqual(off.json.written, [".plan2code/settings.json", "AGENTS.md"]); assert.equal(read(dir, "AGENTS.md"), original); assert.equal(gitIn(dir)("diff", "--cached", "--name-only").trim(), "", "nothing staged"); const bare = repo(); const r = L(bare, ["switch", "on"], store); assert.equal(r.json.next, "plan2code-init"); assert.equal(r.json.skipped, "no-agents"); assert.equal(r.json.state, "on"); assert.ok(fs.existsSync(path.join(bare, ".plan2code", "settings.json"))); assert.equal(fs.existsSync(path.join(bare, "AGENTS.md")), false); }); test("lessons switch: offerLogMove only when this call turns it on and the log has an unmarked line; firstOn until a commit says on", () => { const dir = repo(); const store = learningDir(); const g = gitIn(dir); write(dir, "AGENTS.md", agentsDoc()); const first = L(dir, ["switch", "on"], store).json; assert.equal(first.offerLogMove, true); assert.equal(first.firstOn, true); assert.equal(L(dir, ["switch", "on"], store).json.offerLogMove, false, "already on"); commitAll(g, "learning on"); L(dir, ["switch", "off"], store); const again = L(dir, ["switch", "on"], store).json; assert.equal(again.offerLogMove, true, "off to on offers again"); assert.equal(again.firstOn, undefined, "a commit already records it on"); assert.equal(L(dir, ["switch", "off"], store).json.offerLogMove, undefined, "off never offers"); const none = repo(); write(none, "AGENTS.md", agentsDoc({ log: ["- Only line. (kept in the log)"] })); assert.equal(L(none, ["switch", "on"], store).json.offerLogMove, false, "every line is marked"); }); // A repository whose AGENTS.md failure log holds two old lines, then Learning // switched on and committed, then one new line committed. const logRepo = () => copyFixture("lessons-log", "log-history", (d) => { const g = gitInit(d); write(d, "AGENTS.md", agentsDoc()); write(d, "src/a.js", "a\n"); commitAll(g, "old log"); write(d, ".plan2code/settings.json", '{\n "format": 1,\n "learning": "on"\n}\n'); commitAll(g, "learning on"); write(d, "AGENTS.md", read(d, "AGENTS.md") + "- A new line.\n"); commitAll(g, "new line"); }); const texts = (lines) => lines.map((l) => l.text); test("lessons log-lines: only lines added since the first switch-on commit; --all gives every unmarked line", () => { const dir = logRepo(); const store = learningDir(); const r = L(dir, ["log-lines"], store); assert.equal(r.code, 0, r.stderr); assert.deepEqual(texts(r.json.lines), ["A new line."]); assert.deepEqual(r.json.lines[0].incidents, [{ text: "A new line.", kind: "correction" }]); assert.equal(r.json.lines[0].n, 17); const all = L(dir, ["log-lines", "--all"], store).json.lines; assert.deepEqual(texts(all), ["Old line one.", "Old line two. A second incident here.", "A new line."]); assert.deepEqual( all[1].incidents.map((i) => i.text), ["Old line two.", "A second incident here."] ); // An uncommitted line is new too, and read's first call carries the same lines. write(dir, "AGENTS.md", read(dir, "AGENTS.md") + "- Uncommitted line.\n"); const first = L(dir, ["read"], store).json; assert.deepEqual(texts(first.logLines), ["A new line.", "Uncommitted line."]); assert.equal(L(dir, ["read", "--run", first.run], store).json.logLines, undefined, "only the first read"); // list: one item per new line; --log-all every unmarked one. const list = L(dir, ["list"], store).json; const items = list.items.filter((i) => i.type === "log-line"); assert.deepEqual(texts(items), ["A new line.", "Uncommitted line."]); assert.deepEqual(items[0].choices, ["Move", "Reword and move", "Leave in the log"]); assert.deepEqual(items[0].lessons, [{ text: "A new line.", kind: "correction" }]); assert.match(items[0].id, /^log:[0-9a-f]{12}$/); assert.equal(list.rounds.find((x) => x.type === "log-line").items.length, 2); assert.equal(L(dir, ["list", "--log-all"], store).json.items.filter((i) => i.type === "log-line").length, 4); // Off: the list offers no line. settings(dir, { format: 1, learning: "off" }); assert.deepEqual(L(dir, ["list"], store).json.items, []); }); test("lessons log-lines: a line written while switched off is still new later; outside git or never committed on, none", () => { const dir = logRepo(); const store = learningDir(); const g = gitIn(dir); settings(dir, { format: 1, learning: "off" }); commitAll(g, "off"); write(dir, "AGENTS.md", read(dir, "AGENTS.md") + "- Written while off.\n"); commitAll(g, "while off"); settings(dir, { format: 1, learning: "on" }); commitAll(g, "on again"); assert.deepEqual(texts(L(dir, ["log-lines"], store).json.lines), ["A new line.", "Written while off."]); const outside = tmp("lessons-log-nogit"); write(outside, "AGENTS.md", agentsDoc()); settings(outside, { format: 1, learning: "on" }); assert.deepEqual(L(outside, ["log-lines"], store).json.lines, [], "outside git no line is offered"); assert.equal(L(outside, ["log-lines", "--all"], store).json.lines.length, 2, "the by-hand move still sees them"); assert.deepEqual(L(outside, ["read"], store).json.logLines, []); const uncommitted = repo(); write(uncommitted, "AGENTS.md", agentsDoc()); settings(uncommitted, { format: 1, learning: "on" }); assert.deepEqual(L(uncommitted, ["log-lines"], store).json.lines, [], "the switch is not committed on yet"); }); test("lessons decide: Leave in the log marks the line once and it is never offered again; a hand-typed mark mid-line is not trusted", () => { const dir = logRepo(); const store = learningDir(); const before = read(dir, "AGENTS.md"); const id = L(dir, ["list"], store).json.items.find((i) => i.text === "A new line.").id; const r = decide(dir, store, [{ id, choice: "Leave in the log" }]); assert.equal(r.code, 0, r.stderr); assert.deepEqual(r.json.results, [{ id, outcome: "left", file: "AGENTS.md" }]); assert.deepEqual(r.json.written, ["AGENTS.md"]); assert.equal(read(dir, "AGENTS.md"), before.replace("- A new line.\n", "- A new line. (kept in the log)\n"), "only that line changed"); assert.deepEqual(L(dir, ["log-lines"], store).json.lines, []); assert.ok(!texts(L(dir, ["log-lines", "--all"], store).json.lines).some((t) => t.startsWith("A new line")), "--all leaves it out too"); write(dir, "AGENTS.md", read(dir, "AGENTS.md") + "- Typed (kept in the log) by hand, mid-line.\n"); assert.ok(texts(L(dir, ["log-lines"], store).json.lines).includes("Typed (kept in the log) by hand, mid-line.")); }); test("lessons decide: Move turns a two-incident line into two lessons and takes the line out; a changed line is out of date", () => { const dir = logRepo(); const store = learningDir(); const before = read(dir, "AGENTS.md"); const item = L(dir, ["list", "--log-all"], store).json.items.find((i) => i.text.startsWith("Old line two.")); const missing = decide(dir, store, [{ id: item.id, choice: "Move" }]); assert.equal(missing.json.results[0].outcome, "invalid", "a correction needs a why and about"); assert.equal(read(dir, "AGENTS.md"), before, "nothing changed"); const r = decide(dir, store, [{ id: item.id, choice: "Move", why: "It broke a build once.", about: "src/a.js" }]); assert.equal(r.code, 0, r.stderr); assert.equal(r.json.results[0].outcome, "moved"); assert.equal(r.json.results[0].lessons.length, 2); assert.deepEqual(r.json.written, [".plan2code/lessons/general.md", "AGENTS.md"]); assert.equal(read(dir, "AGENTS.md"), before.replace("- Old line two. A second incident here.\n", ""), "only the bullet went"); const general = read(dir, ".plan2code/lessons/general.md"); assert.match(general, /### A second incident here\.\n- Kind: correction\n- About: src\/a\.js\n- Why: It broke a build once\.\n- Noted: 2026-08-03, Failure log\n/); assert.match(general, /### Old line two\./); assert.match(r.json.closing, /^Moved 1 from the failure log\./); assert.equal(gitIn(dir)("diff", "--cached", "--name-only").trim(), "", "nothing staged"); // An id whose line changed since the list was read is out of date; Reword and move takes the person's lessons. const one = L(dir, ["list", "--log-all"], store).json.items.find((i) => i.text === "Old line one."); write(dir, "AGENTS.md", read(dir, "AGENTS.md").replace("- Old line one.", "- Old line one, edited.")); assert.deepEqual(decide(dir, store, [{ id: one.id, choice: "Leave in the log" }]).json.results, [{ id: one.id, outcome: "outOfDate" }]); const edited = L(dir, ["list", "--log-all"], store).json.items.find((i) => i.text === "Old line one, edited."); const rw = decide(dir, store, [{ id: edited.id, choice: "Reword and move", lessons: [{ text: "Say it plainly", why: "It was unclear.", about: "src/a.js" }] }]); assert.equal(rw.json.results[0].outcome, "moved"); assert.ok(!read(dir, "AGENTS.md").includes("Old line one")); assert.match(read(dir, ".plan2code/lessons/general.md"), /### Say it plainly\n- Kind: correction/); }); test("lessons note agents-fix: the before must match once, the after is checked, and the list shows file, before and after", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); write(dir, "AGENTS.md", "# AGENTS.md\n\nRun `npm test` for everything.\nUse two spaces.\nUse two spaces.\n"); write(dir, ".agents-docs/AGENTS-x.md", "# X\n\nThe build is `npm run old`.\n"); const fix = (extra) => L(dir, ["note", "--type", "agents-fix", "--skill", "Implement", ...extra], store); assert.equal(fix(["--before", "nowhere", "--after", "x"]).json.error, "no-match"); assert.equal(fix(["--before", "Use two spaces.", "--after", "x"]).code, 4, "twice is not once"); assert.equal(fix(["--before", "npm", "--after", "x", "--file", "../outside.md"]).json.error, "bad-file"); assert.equal(fix(["--before", "x"]).code, 2, "after is required"); const secret = fix(["--before", "Run `npm test` for everything.", "--after", `Use ${SECRETS["github-token"][0]}`]); assert.equal(secret.code, 5); assert.equal(secret.json.error, "secret"); assert.ok(!secret.stdout.includes(SECRETS["github-token"][0])); assert.equal(waitingFiles(store).length, 0, "nothing written"); const ok = fix(["--before", "Run `npm test` for everything.", "--after", "Run `npm run test:fast` while working."]); assert.equal(ok.code, 0, ok.stderr); assert.equal(ok.json.line, "Noted for the end of the run: a fix to AGENTS.md"); assert.equal(fix(["--before", "`npm run old`", "--after", "`npm run build`", "--file", ".agents-docs/AGENTS-x.md"]).code, 0); const items = L(dir, ["list"], store).json.items; const a = items.find((i) => i.file === "AGENTS.md"); assert.equal(a.type, "agents-fix"); assert.equal(a.before, "Run `npm test` for everything."); assert.equal(a.after, "Run `npm run test:fast` while working."); assert.deepEqual(a.choices, ["Apply", "Reword", "Drop"]); assert.ok(items.some((i) => i.file === ".agents-docs/AGENTS-x.md")); }); test("lessons decide agents-fix: Apply replaces the before once, an edited-away before is out of date and keeps waiting", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); write(dir, "AGENTS.md", "# AGENTS.md\r\n\r\nRun `npm test` for everything.\r\nKeep this line.\r\n"); write(dir, ".agents-docs/AGENTS-x.md", "# X\n\nThe build is `npm run old`.\n"); const fix = (extra) => L(dir, ["note", "--type", "agents-fix", "--skill", "Implement", ...extra], store); fix(["--before", "Run `npm test` for everything.", "--after", "Run `npm run test:fast` while working."]); fix(["--before", "`npm run old`", "--after", "`npm run build`", "--file", ".agents-docs/AGENTS-x.md"]); const items = L(dir, ["list"], store).json.items; const inAgents = items.find((i) => i.file === "AGENTS.md").id; const inDocs = items.find((i) => i.file !== "AGENTS.md").id; write(dir, ".agents-docs/AGENTS-x.md", "# X\n\nThe build is `make`.\n"); const r = decide(dir, store, [ { id: inAgents, choice: "Apply" }, { id: inDocs, choice: "Apply" }, ]); assert.equal(r.code, 0, r.stderr); assert.deepEqual( r.json.results.map((x) => x.outcome), ["applied", "outOfDate"] ); assert.equal(read(dir, "AGENTS.md"), "# AGENTS.md\r\n\r\nRun `npm run test:fast` while working.\r\nKeep this line.\r\n"); assert.equal(r.json.stillWaiting, 1, "the out-of-date fix keeps waiting"); assert.match(r.json.closing, /^Applied 1 fix\. 1 still waiting\.$/); // Reword applies the person's after, checked first. write(dir, ".agents-docs/AGENTS-x.md", "# X\n\nThe build is `npm run old`.\n"); const refused = decide(dir, store, [{ id: inDocs, choice: "Reword", after: `Use ${SECRETS["aws-access-key"][0]}` }]); assert.equal(refused.json.results[0].outcome, "refused"); assert.equal(read(dir, ".agents-docs/AGENTS-x.md"), "# X\n\nThe build is `npm run old`.\n"); const rw = decide(dir, store, [{ id: inDocs, choice: "Reword", after: "`npm run build:all`" }]); assert.equal(rw.json.results[0].outcome, "applied"); assert.equal(read(dir, ".agents-docs/AGENTS-x.md"), "# X\n\nThe build is `npm run build:all`.\n"); }); test("lessons agents-fix: a test map row fix leaves every line outside the table byte-identical", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const doc = [ "# AGENTS.md", "", "## Test map", "", "Which checks cover which files.", "", "| Area | Paths | Run | Shared |", "|---|---|---|---|", "| Web | `src/web/**` | `npm run test:web` | no |", "| Docs | `docs/**` | `npm run docs` | no |", "", "## After", "", "Text with odd spacing.", "", ].join("\n"); write(dir, "AGENTS.md", doc); const row = (r) => L(dir, ["note", "--type", "agents-fix", "--skill", "Test", "--test-map-row", JSON.stringify(r)], store); assert.equal(row({ area: "Web", paths: [], run: "x" }).json.error, "invalid-rows"); assert.equal(row({ area: "Web", paths: ["src/**"], run: `deploy ${SECRETS["stripe-key"][0]}` }).code, 5); assert.equal(row({ area: "Web", paths: ["src/web/**"], run: "npm run test:web:fast", shared: false }).code, 0); assert.equal(row({ area: "Api", paths: ["src/api/**"], run: "npm run test:api", shared: true }).code, 0); const items = L(dir, ["list"], store).json.items; const web = items.find((i) => i.after.includes("Web")); assert.equal(web.before, "| Web | `src/web/**` | `npm run test:web` | no |"); assert.equal(web.after, "| Web | `src/web/**` | `npm run test:web:fast` | no |"); assert.equal(items.find((i) => i.after.includes("Api")).before, ""); const r = decide( dir, store, items.map((i) => ({ id: i.id, choice: "Apply" })) ); assert.equal(r.code, 0, r.stderr); assert.deepEqual(r.json.written, ["AGENTS.md"]); const lines = read(dir, "AGENTS.md").split("\n"); const was = doc.split("\n"); assert.deepEqual(lines.slice(0, 8), was.slice(0, 8), "everything above the rows"); assert.deepEqual(lines.slice(-5), was.slice(-5), "everything below the table"); assert.deepEqual(lines.slice(8, 11), ["| Web | `src/web/**` | `npm run test:web:fast` | no |", "| Docs | `docs/**` | `npm run docs` | no |", "| Api | `src/api/**` | `npm run test:api` | yes |"]); assert.match(r.json.closing, /^Applied 2 fixes\./); }); test("lessons failure log: Init's empty placeholder line is not a line", () => { const dir = repo(); const store = learningDir(); write(dir, "AGENTS.md", agentsDoc({ log: ["- "] })); const on = L(dir, ["switch", "on"], store).json; assert.equal(on.offerLogMove, false, "nothing to move"); assert.deepEqual(L(dir, ["log-lines", "--all"], store).json.lines, []); assert.deepEqual(L(dir, ["list", "--log-all"], store).json.items, []); }); test("lessons agents-fix: a test map the read cannot take whole holds a row fix back, and a bad row names the note", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const doc = "# AGENTS.md\n\n## Test map\n\n| Area | Paths | Run |\n|---|---|---|\n| Web | `src/web/**` | `npm run test:web` |\n"; write(dir, "AGENTS.md", doc); const bad = L(dir, ["note", "--type", "agents-fix", "--skill", "Test", "--test-map-row", JSON.stringify({ area: "Web", paths: [], run: "x" })], store); assert.equal(bad.json.error, "invalid-rows"); assert.match(bad.json.next, /--test-map-row/); assert.equal(L(dir, ["note", "--type", "agents-fix", "--skill", "Test", "--test-map-row", JSON.stringify({ area: "Api", paths: ["src/api/**"], run: "npm run test:api" })], store).code, 0); const item = L(dir, ["list"], store).json.items[0]; assert.match(item.note, /test map has problems/); const r = decide(dir, store, [{ id: item.id, choice: "Apply" }]); assert.equal(r.json.results[0].outcome, "outOfDate"); assert.equal(r.json.results[0].reason, "test-map-problems"); assert.equal(read(dir, "AGENTS.md"), doc, "the table is left as it was"); assert.equal(r.json.stillWaiting, 1); }); test("lessons agents-fix: a test map row is reworded with row, or with after as its table line, and checked again at Apply", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const head = "# AGENTS.md\n\n## Test map\n\n| Area | Paths | Run | Shared |\n|---|---|---|---|\n"; write(dir, "AGENTS.md", head + "| Web | `src/web/**` | `npm run test:web` | no |\n"); const note = (r) => L(dir, ["note", "--type", "agents-fix", "--skill", "Test", "--test-map-row", JSON.stringify(r)], store); assert.equal(note({ area: "Web", paths: ["src/web/**"], run: "npm run test:web:fast", shared: false }).code, 0); assert.equal(note({ area: "Api", paths: ["src/api/**"], run: "npm run test:api", shared: false }).code, 0); assert.equal(note({ area: "Docs", paths: ["docs/**"], run: "npm run docs", shared: false }).code, 0); const list = L(dir, ["list"], store).json; const by = (name) => list.items.find((i) => i.after.includes(`| ${name} |`)); assert.deepEqual(by("Web").row, { area: "Web", paths: ["src/web/**"], run: "npm run test:web:fast", shared: false }, "the item says it is a row"); assert.deepEqual(list.card.rows.find((r) => r.id === by("Api").id).row, by("Api").row, "and so does its card row"); // A line that is no table row, and a row with no run command, are invalid and keep waiting. const bad = decide(dir, store, [ { id: by("Web").id, choice: "Reword", after: "Run the fast web tests" }, { id: by("Api").id, choice: "Reword", after: "| Api | `src/api/**` | | yes |" }, ]); assert.deepEqual(bad.json.results.map((r) => r.outcome), ["invalid", "invalid"]); assert.match(bad.json.results[0].problems[0].message, /one table line/); assert.equal(bad.json.stillWaiting, 3); // A reworded row is secret-checked whichever way it comes. const leaked = decide(dir, store, [{ id: by("Web").id, choice: "Reword", after: `| Web | \`src/web/**\` | \`deploy ${SECRETS["stripe-key"][0]}\` | no |` }]); assert.equal(leaked.json.results[0].outcome, "refused"); assert.ok(!leaked.stdout.includes(SECRETS["stripe-key"][0])); // The card sends `after`, the edited table line; an agent may send `row`. const r = decide(dir, store, [ { id: by("Web").id, choice: "Reword", after: "| Web | `src/web/**`, `scripts/web-*.mjs` | `npm run test:web:quick` | yes |" }, { id: by("Api").id, choice: "Reword", row: { area: "Api", paths: ["src/api/**"], run: "npm run test:api:all", shared: true } }, ]); assert.equal(r.code, 0, r.stderr); assert.deepEqual(r.json.results.map((x) => x.outcome), ["applied", "applied"]); assert.equal(read(dir, "AGENTS.md"), head + "| Web | `src/web/**`, `scripts/web-*.mjs` | `npm run test:web:quick` | yes |\n| Api | `src/api/**` | `npm run test:api:all` | yes |\n"); // Apply reads the waiting file as it is now: one changed by hand since it was noted is checked again. const files = fs.readdirSync(store, { recursive: true }).map((f) => path.join(store, String(f))).filter((f) => f.endsWith(`${by("Docs").id}.json`)); assert.equal(files.length, 1, "the Docs fix's waiting file"); const saved = JSON.parse(fs.readFileSync(files[0], "utf8")); fs.writeFileSync(files[0], JSON.stringify({ ...saved, row: { ...saved.row, run: `deploy ${SECRETS["stripe-key"][0]}` } })); const before = read(dir, "AGENTS.md"); const tampered = decide(dir, store, [{ id: by("Docs").id, choice: "Apply" }]); assert.equal(tampered.json.results[0].outcome, "refused"); assert.ok(!tampered.stdout.includes(SECRETS["stripe-key"][0])); fs.writeFileSync(files[0], JSON.stringify({ ...saved, row: { ...saved.row, paths: [] } })); assert.equal(decide(dir, store, [{ id: by("Docs").id, choice: "Apply" }]).json.results[0].outcome, "invalid"); assert.equal(read(dir, "AGENTS.md"), before, "nothing written"); }); test("lessons decide: a missing decisions file, a lesson an area already holds, and a fix note with a bad --skill", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); const missing = L(dir, ["decide", "--file", path.join(tmp("lessons-decide"), "nothing.json")], store); assert.equal(missing.code, 3); assert.equal(missing.json.error, "no-file"); assert.equal(L(dir, lesson("Build the skills before the script tests"), store).code, 0); let item = L(dir, ["list"], store).json.items[0]; assert.equal(decide(dir, store, [{ id: item.id, choice: "Keep" }]).json.results[0].outcome, "kept"); // The same words noted again: Keep finds them in the area and leaves the item waiting. const again = L(dir, lesson("Build the skills before the script tests"), store); assert.equal(again.code, 0, again.stderr); item = L(dir, ["list"], store).json.items.find((i) => i.type === "lesson"); const dup = decide(dir, store, [{ id: item.id, choice: "Keep" }]); assert.equal(dup.json.results[0].outcome, "duplicate"); assert.equal(dup.json.stillWaiting, 1); assert.deepEqual(dup.json.written, []); write(dir, "AGENTS.md", "# AGENTS.md\n\nThe build is `npm run build`.\n"); const fix = L(dir, ["note", "--type", "agents-fix", "--before", "npm run build", "--after", "npm run build:all", "--skill", "x".repeat(41)], store); assert.equal(fix.code, 4); assert.equal(fix.json.error, "invalid-fix"); }); const correction = (text, extra = []) => ["note", "--type", "lesson", "--text", text, "--kind", "correction", "--why", "It broke once.", "--about", "src/a.js", "--source", "said", "--skill", "Implement", ...extra]; test("lessons first ask: list --first-ask leads with the newest lesson; Yes switches on and lists with offerLogMove", () => { const dir = repo(); const store = learningDir(); write(dir, "AGENTS.md", agentsDoc()); L(dir, lesson("An older lesson"), store); // A minute later, so the newest is not left to the ids' random part. const later = runScript("plan2code-quick-task", "lessons.mjs", correction("Run the fixer for line endings"), { cwd: dir, env: { PLAN2CODE_LEARNING_DIR: store, PLAN2CODE_NOW: "2026-08-03 14:06" } }); assert.equal(later.code, 0, later.stderr); const ask = L(dir, ["list", "--first-ask"], store).json; assert.equal(ask.firstAsk.lesson.text, "Run the fixer for line endings", "the newest waiting lesson"); assert.deepEqual(ask.firstAsk.sentences, [ "Plan2Code can keep lessons like this with the repository (in `.plan2code/lessons/`), so your next run, and your teammates', starts out knowing them.", "Nothing is saved without your approval.", "Lessons are about the code, never about you.", ]); assert.equal(ask.firstAsk.yes, "Switch Learning on"); assert.equal(ask.firstAsk.no, "Not for this project"); assert.equal(ask.firstAsk.later, "You can change this later on the dashboard."); assert.equal(L(dir, ["list"], store).json.firstAsk, undefined, "only with --first-ask"); const yes = L(dir, ["decide", "--first-ask", "yes"], store); assert.equal(yes.code, 0, yes.stderr); assert.equal(yes.json.state, "on"); assert.equal(yes.json.offerLogMove, true); assert.deepEqual(yes.json.written, [".plan2code/settings.json", "AGENTS.md"]); assert.equal(yes.json.items.length, 2, "the normal list follows"); assert.equal(yes.json.firstAsk, undefined); assert.ok(read(dir, "AGENTS.md").includes(record.POINTER_LINE)); assert.equal(L(dir, ["list", "--first-ask"], store).json.firstAsk, undefined, "once on, list --first-ask is the list"); assert.equal(L(dir, ["decide", "--first-ask", "yes"], store).json.error, "not-first-ask"); }); test("lessons first ask: No switches off and sends this run's correction to the failure log", () => { const dir = repo(); const store = learningDir(); write(dir, "AGENTS.md", agentsDoc()); const before = read(dir, "AGENTS.md"); L(dir, correction("Run the fixer for line endings"), store); L(dir, lesson("A convention that waits"), store); L(dir, correction("Another skill's correction", ["--skill", "Review"]), store); assert.equal(L(dir, ["decide", "--first-ask", "no"], store).code, 2, "needs --skill"); const no = L(dir, ["decide", "--first-ask", "no", "--skill", "Implement"], store); assert.equal(no.code, 0, no.stderr); assert.equal(no.json.state, "off"); assert.equal(no.json.logged, 1); assert.deepEqual(no.json.written, [".plan2code/settings.json", "AGENTS.md"]); assert.equal(read(dir, "AGENTS.md"), before + "- Run the fixer for line endings. It broke once.\n"); assert.equal(no.json.stillWaiting, 2, "the convention and the other skill's correction wait"); assert.deepEqual( L(dir, ["list"], store) .json.items.map((i) => i.text) .sort(), ["A convention that waits", "Another skill's correction"] ); // No failure log: the correction keeps waiting. const bare = repo(); write(bare, "AGENTS.md", "# AGENTS.md\n"); L(bare, correction("Keep me"), store); const r = L(bare, ["decide", "--first-ask", "no", "--skill", "Implement"], store).json; assert.equal(r.results[0].outcome, "skipped"); assert.equal(r.results[0].reason, "no-failure-log"); assert.equal(read(bare, "AGENTS.md"), "# AGENTS.md\n"); }); test("lessons remove: needs --confirm, then deletes only .plan2code/lessons/ and stages nothing", () => { const dir = repo(); const store = learningDir(); settings(dir, { format: 1, learning: "on" }); write(dir, "AGENTS.md", "# AGENTS.md\n"); write(dir, ".plan2code/lessons/general.md", "# General\n"); write(dir, ".plan2code/lessons/web.md", WEB_AREA); L(dir, lesson("Still waiting"), store); const no = L(dir, ["remove"], store); assert.equal(no.code, 2); assert.equal(no.json.error, "needs-confirm"); assert.ok(fs.existsSync(path.join(dir, ".plan2code/lessons/web.md")), "nothing deleted"); const dry = L(dir, ["remove", "--confirm", "--dry-run"], store); assert.deepEqual(dry.json.removed, [".plan2code/lessons/general.md", ".plan2code/lessons/web.md"]); assert.ok(fs.existsSync(path.join(dir, ".plan2code/lessons/web.md")), "a dry run deletes nothing"); const r = L(dir, ["remove", "--confirm"], store); assert.equal(r.code, 0, r.stderr); assert.deepEqual(r.json.removed, [".plan2code/lessons/general.md", ".plan2code/lessons/web.md"]); assert.equal(fs.existsSync(path.join(dir, ".plan2code/lessons")), false); assert.ok(fs.existsSync(path.join(dir, ".plan2code/settings.json"))); assert.equal(read(dir, "AGENTS.md"), "# AGENTS.md\n"); assert.equal(waitingFiles(store).length, 1, "the machine store is left"); assert.equal(gitIn(dir)("diff", "--cached", "--name-only").trim(), ""); }); /* --------------------------------------------- the reference's wording */ test("lessons.md: every line it tells a skill to print is a line the script prints", () => { // The built reference, as a skill reads it: its quoted examples of printed lines. const ref = fs.readFileSync(path.join(SKILLS, "plan2code-quick-task", "references", "lessons.md"), "utf8"); const quoted = [...ref.matchAll(/"((?:Read |Noted for the end of the run: |Learning is paused|Kept )[^"]*)"/g)].map((m) => m[1]); const pick = (prefix) => { const found = quoted.filter((q) => q.startsWith(prefix)); assert.ok(found.length, `lessons.md shows a line starting "${prefix}"`); return found; }; // "Learning is paused for you.", word for word from a paused read. const dir = readRepo(); const store = learningDir(); assert.equal(L(dir, ["pause", "on"], store).code, 0); const paused = L(dir, ["read"], store).json.line; assert.deepEqual(pick("Learning is paused"), [paused]); L(dir, ["pause", "off"], store); // "Read ...": each example is what readLine gives for its own counts, and the CLI prints readLine. for (const line of pick("Read ")) { const more = line.match(/^Read (\d+) more for (.+)\.$/); const start = line.match(/^Read (\d+) general lessons? and (\d+) for (.+)\.$/); assert.ok(more || start, `an example read line the script can print: ${line}`); const expected = more ? record.readLine({ first: false, general: 0, areas: [{ name: more[2], count: +more[1] }], empty: false }) : record.readLine({ first: true, general: +start[1], areas: [{ name: start[3], count: +start[2] }], empty: false }); assert.equal(line, expected); } const first = L(dir, ["read", "--paths", "src/web/page.js"], store).json; assert.match(first.line, /^Read \d+ general lessons? and \d+ for .+\.$/); assert.equal(first.line, record.readLine({ first: true, general: first.general.length, areas: first.areas.map((a) => ({ name: a.name, count: a.lessons.length })), empty: false })); // "Noted for the end of the run: ", from a real note. const [noted] = pick("Noted for the end of the run: "); const note = L(dir, ["note", "--type", "lesson", "--text", "Draw the page from the state object", "--kind", "convention", "--about", "src/web/page.js", "--source", "said", "--skill", "Implement"], store); assert.equal(note.code, 0, note.stderr); assert.equal(note.json.line, noted.replace("", "Draw the page from the state object")); // The closing line: the example is closingLine's own wording, and decide prints closingLine. const [closing] = pick("Kept "); assert.equal(closing, record.closingLine({ kept: 2, reworded: 1, retired: 1 }, 1)); const r = decide(dir, store, [{ id: ids(dir, store)[0], choice: "Keep" }]); assert.equal(r.code, 0, r.stderr); assert.equal(r.json.closing, record.closingLine({ kept: 1 }, 0)); }); test("lessons.mjs: no output string says pending or queued (the fixed word is waiting)", () => { // The built script, whole: it never says either word, comments included, // so no string it prints can. Then the output of a real run. const BANNED = /\b(pending|queued)\b/i; const src = fs.readFileSync(path.join(SKILLS, "plan2code-quick-task", "scripts", "lessons.mjs"), "utf8"); assert.ok(src.length > 1000, "the built script was read"); assert.doesNotMatch(src, BANNED, "lessons.mjs never says pending or queued"); const dir = repo(); const store = learningDir(); const outputs = [L(dir, ["state"], store), L(dir, ["list", "--first-ask"], store)]; settings(dir, { format: 1, learning: "on" }); outputs.push( L(dir, ["note", "--type", "lesson", "--text", "Draw the page from the state object", "--kind", "convention", "--about", "README.md", "--source", "said", "--skill", "Implement"], store), L(dir, ["read"], store), L(dir, ["list"], store), L(dir, ["remove"], store) ); for (const out of outputs) assert.doesNotMatch(out.stdout + out.stderr, BANNED); });