Files
plan2code/src/web-console/loop-setup.mjs
T

203 lines
9.3 KiB
JavaScript
Raw Normal View History

// Plan2Code Web Console - the Implementation Loop's setup, remembered per project.
import fs from "node:fs";
import path from "node:path";
import { ensureDir, HOME_DIR, readJson, withStateLock, writeJsonAtomic } from "./files.mjs";
import { foldKey } from "./workspace.mjs";
// One file for the person, beside workspaces.json and looks.json, keyed by the
// folder a session runs in (FR-4: one entry per project, used for any spec):
//
// { "schema": 1, "projects": { "<folded worktree>": { ...setup, "saved": "<iso>" } } }
//
// Never under specs/: the server never writes into a project. The quick check
// is stored text only; nothing in the console ever runs it.
export const LOOP_SETUP_FILE = path.join(HOME_DIR, "loop-setup.json");
export const LOOP_SETUP_LOCK = "loop-setup.json.lock";
const LEVELS = ["critical", "warning", "suggestion"];
const FIX_MODES = ["levels", "smart"];
const ON_QUESTION = ["pause", "stop", "guess"];
const AFTER_LAST = ["offer-finalize", "run-finalize"];
const NOTIFY_KINDS = ["query", "discord", "slack", "teams", "google-chat", "json"];
// The kinds where the person names the parameter or field that holds the message.
const NAMED_KINDS = ["query", "json"];
const STRENGTH_WORDS = ["thrifty", "balanced", "best"];
// A spec folder directly under specs/, no leading dot (the route's own rule).
const SPEC_KEY = /^specs\/[^/\\.][^/\\]*$/;
export const LOOP_DEFAULTS = Object.freeze({
review: true,
fixMode: "smart",
fix: Object.freeze([...LEVELS]),
commit: true,
onQuestion: "guess",
afterLast: "offer-finalize",
quickCheck: "",
retryOnce: true,
silenceMinutes: 20,
notifyKind: "query",
notifyUrl: "",
notifyParam: "message",
notifyPhases: false,
phaseStrength: false,
strengths: Object.freeze({}),
});
/** An http or https address in printable ASCII, with a host and no user name or password (the app's `valid_url`). */
function isNotifyUrl(text) {
if (text.length > 2000 || !/^https?:\/\/[^/?#@]+([/?#][!-~]*)?$/i.test(text) || /[^!-~]/.test(text)) return false;
try {
return Boolean(new URL(text).hostname);
} catch {
return false;
}
}
/** Problems with a setup entry, as sentences naming the field; empty when it is good. */
export function loopSetupProblems(entry) {
if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return ["the setup must be an object"];
const problems = [];
for (const key of Object.keys(entry)) {
if (!Object.hasOwn(LOOP_DEFAULTS, key)) problems.push(`"${key}" is not a setup field`);
}
for (const key of ["review", "commit", "retryOnce", "notifyPhases"]) {
if (typeof entry[key] !== "boolean") problems.push(`"${key}" must be true or false`);
}
if (!Array.isArray(entry.fix) || !entry.fix.every((l) => LEVELS.includes(l)) || new Set(entry.fix).size !== entry.fix.length) {
problems.push(`"fix" must list distinct levels from ${LEVELS.join(", ")}`);
}
if (!FIX_MODES.includes(entry.fixMode)) problems.push(`"fixMode" must be one of ${FIX_MODES.join(", ")}`);
if (!ON_QUESTION.includes(entry.onQuestion)) problems.push(`"onQuestion" must be one of ${ON_QUESTION.join(", ")}`);
if (!AFTER_LAST.includes(entry.afterLast)) problems.push(`"afterLast" must be one of ${AFTER_LAST.join(", ")}`);
if (typeof entry.quickCheck !== "string" || /[\r\n]/.test(entry.quickCheck) || entry.quickCheck.length > 500) {
problems.push('"quickCheck" must be one line of at most 500 characters (empty for none)');
}
if (!Number.isInteger(entry.silenceMinutes) || entry.silenceMinutes < 1 || entry.silenceMinutes > 60) {
problems.push('"silenceMinutes" must be a whole number from 1 to 60');
}
if (typeof entry.notifyUrl !== "string" || (entry.notifyUrl !== "" && !isNotifyUrl(entry.notifyUrl))) {
problems.push('"notifyUrl" must be an http or https web address, without a user name or password (empty for none)');
}
if (!NOTIFY_KINDS.includes(entry.notifyKind)) problems.push(`"notifyKind" must be one of ${NOTIFY_KINDS.join(", ")}`);
// The name only matters beside an address and for a kind that uses it: the field is hidden otherwise.
if (typeof entry.notifyParam !== "string" || (entry.notifyUrl && NAMED_KINDS.includes(entry.notifyKind) && !/^[A-Za-z0-9._~-]{1,64}$/.test(entry.notifyParam))) {
problems.push('"notifyParam" must be 1 to 64 letters, digits, or - _ . ~');
}
if (typeof entry.phaseStrength !== "boolean") problems.push('"phaseStrength" must be true or false');
problems.push(...strengthsProblems(entry.strengths));
return problems;
}
/** Problems with the per-spec phase picks; empty when they are good. */
function strengthsProblems(strengths) {
if (strengths === null || typeof strengths !== "object" || Array.isArray(strengths)) return ['"strengths" must be an object'];
const problems = [];
for (const [key, picks] of Object.entries(strengths)) {
if (!SPEC_KEY.test(key)) {
problems.push(`"strengths" key "${key}" must be a folder directly under specs/`);
continue;
}
if (!Array.isArray(picks) || picks.length > 100) {
problems.push(`"strengths.${key}" must list at most 100 phase picks`);
continue;
}
const seen = new Set();
for (const pick of picks) {
const ok = pick && typeof pick === "object" && !Array.isArray(pick);
if (!ok || !Number.isInteger(pick.n) || pick.n < 1) {
problems.push(`"strengths.${key}" picks need a phase number "n" (a positive whole number)`);
} else if (seen.has(pick.n)) {
problems.push(`"strengths.${key}" has Phase ${pick.n} twice`);
} else {
seen.add(pick.n);
}
if (!ok) continue;
if (typeof pick.name !== "string" || pick.name.length > 200) problems.push(`"strengths.${key}" pick names must be text of at most 200 characters`);
if (!STRENGTH_WORDS.includes(pick.strength)) problems.push(`"strengths.${key}" picks need a strength of ${STRENGTH_WORDS.join(", ")}`);
}
}
return problems;
}
/**
* Drop picks that no longer mean anything (FR-12, FR-13): a spec key whose folder
* is gone from the project, and, for a spec whose phases can be read, picks whose
* number and name match no phase left. `phasesFor(spec)` returns the phases left
* as [{ n, name }], or null when the overview cannot be read (its picks stay).
* Returns a fresh object; the input is never changed.
*/
export function pruneStrengths(project, strengths, phasesFor) {
const out = {};
for (const [spec, picks] of Object.entries(strengths && typeof strengths === "object" ? strengths : {})) {
if (!SPEC_KEY.test(spec) || !Array.isArray(picks)) continue;
let isDir = false;
try {
isDir = fs.statSync(path.join(project, spec)).isDirectory();
} catch {
/* gone */
}
if (!isDir) continue;
let left = null;
try {
left = typeof phasesFor === "function" ? phasesFor(spec) : null;
} catch {
left = null;
}
const kept = Array.isArray(left) ? picks.filter((p) => left.some((l) => l.n === p.n && l.name === p.name)) : picks;
if (kept.length) out[spec] = kept.map((p) => ({ ...p }));
}
return out;
}
function readStore() {
const saved = readJson(LOOP_SETUP_FILE, null);
const ok = saved && saved.schema === 1 && saved.projects && typeof saved.projects === "object" && !Array.isArray(saved.projects);
return ok ? saved : { schema: 1, projects: {} };
}
/**
* The setup for this project: the saved entry over the defaults, or the
* defaults alone. `remembered` says which, so the setup screen can tell a
* first visit from a returning one. A missing, unreadable or foreign-schema
* file reads as empty. An entry saved before `fixMode` existed fixed by level,
* so it keeps doing that rather than taking the newer default.
*/
export function readLoopSetup(project, phasesFor) {
const saved = readStore().projects[foldKey(project)];
const base = { ...LOOP_DEFAULTS, fix: [...LOOP_DEFAULTS.fix], strengths: {} };
if (saved && typeof saved === "object") {
const setup = { ...base, fixMode: "levels", ...saved, remembered: true };
// Deep-copied and pruned like `fix`: the caller may change it freely.
const strengths = saved.strengths && typeof saved.strengths === "object" && !Array.isArray(saved.strengths) ? saved.strengths : {};
setup.strengths = pruneStrengths(project, strengths, phasesFor);
if (typeof setup.phaseStrength !== "boolean") setup.phaseStrength = false;
return setup;
}
return { ...base, remembered: false };
}
/** Validate and save this project's setup; throws an Error listing the problems. */
export function saveLoopSetup(project, entry, phasesFor) {
const problems = loopSetupProblems(entry);
if (problems.length) {
const err = new Error(`the loop setup is not valid: ${problems.join("; ")}`);
err.problems = problems;
throw err;
}
ensureDir(path.dirname(LOOP_SETUP_FILE));
return withStateLock(
path.dirname(LOOP_SETUP_FILE),
() => {
const store = readStore();
// Only the known fields are kept, in the defaults' order.
const known = Object.fromEntries(Object.keys(LOOP_DEFAULTS).map((key) => [key, entry[key]]));
known.strengths = pruneStrengths(project, known.strengths, phasesFor);
store.projects[foldKey(project)] = { ...known, saved: new Date().toISOString() };
writeJsonAtomic(LOOP_SETUP_FILE, { schema: 1, projects: store.projects });
return readLoopSetup(project, phasesFor);
},
LOOP_SETUP_LOCK,
);
}