@phren/cli 0.1.30 → 0.1.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -22,3 +22,4 @@ export declare const FINDING_SENSITIVITY_CONFIG: Record<FindingSensitivityLevel,
22
22
  export declare function handleIndexPolicy(args: string[]): Promise<void>;
23
23
  export declare function handleRetentionPolicy(args: string[]): Promise<void>;
24
24
  export declare function handleWorkflowPolicy(args: string[]): Promise<void>;
25
+ export declare function handleConfigAccess(args: string[]): void;
@@ -5,7 +5,11 @@ import { listMachines as listMachinesStore, listProfiles as listProfilesStore, l
5
5
  import { setTelemetryEnabled, getTelemetrySummary, resetTelemetry } from "../telemetry.js";
6
6
  import { governanceInstallPreferencesFile, readInstallPreferences, readGovernanceInstallPreferences, writeInstallPreferences, writeGovernanceInstallPreferences, } from "../init/preferences.js";
7
7
  import { PROACTIVITY_LEVELS, getProactivityLevel, getProactivityLevelForTask, getProactivityLevelForFindings, } from "../proactivity.js";
8
- import { PROJECT_OWNERSHIP_MODES, getProjectOwnershipDefault, parseProjectOwnershipMode, updateProjectConfigOverrides, } from "../project-config.js";
8
+ import { PROJECT_OWNERSHIP_MODES, getProjectOwnershipDefault, parseProjectOwnershipMode, updateProjectConfigOverrides, readProjectConfig, writeProjectConfig, } from "../project-config.js";
9
+ import * as fs from "fs";
10
+ import * as path from "path";
11
+ import { buildConfigView } from "../config/resolve.js";
12
+ import { CONFIG_DOMAINS } from "../config/schema.js";
9
13
  import { isValidProjectName, learnedSynonymsPath, learnSynonym, loadLearnedSynonyms, removeLearnedSynonym, } from "../utils.js";
10
14
  // ── Shared helpers ────────────────────────────────────────────────────────────
11
15
  function parseProjectArg(args) {
@@ -46,79 +50,84 @@ export function buildProactivitySnapshot(phrenPath) {
46
50
  };
47
51
  }
48
52
  // ── Config show ───────────────────────────────────────────────────────────────
49
- function formatConfigAsTable(label, rows) {
50
- const maxKey = Math.max(...rows.map(([k]) => k.length));
51
- console.log(`\n${label}`);
52
- for (const [k, v] of rows) {
53
- console.log(` ${k.padEnd(maxKey)} ${v}`);
53
+ function formatConfigValue(value) {
54
+ if (value === undefined || value === null)
55
+ return "(unset)";
56
+ if (Array.isArray(value))
57
+ return value.length ? value.join(", ") : "(none)";
58
+ if (typeof value === "boolean")
59
+ return value ? "true" : "false";
60
+ return String(value);
61
+ }
62
+ /**
63
+ * Render a resolved {@link ConfigView} grouped by domain, with a source column
64
+ * that names where each value came from (default / global / project) and the
65
+ * file that set it.
66
+ */
67
+ function renderConfigView(view, opts) {
68
+ const heading = view.scope === "project"
69
+ ? `phren config — project: ${view.project}`
70
+ : "phren config — global (applies to all projects unless overridden)";
71
+ console.log(`\n${heading}`);
72
+ if (opts.diff)
73
+ console.log("(showing only values customised away from defaults)");
74
+ let shownAny = false;
75
+ for (const domain of CONFIG_DOMAINS) {
76
+ const rows = [];
77
+ for (const field of domain.fields) {
78
+ const resolved = view.fields[field.key];
79
+ if (!resolved)
80
+ continue; // topic fields are resolved separately
81
+ if (opts.diff && resolved.source === "default")
82
+ continue;
83
+ const file = resolved.sourcePath ? path.basename(resolved.sourcePath) : "";
84
+ rows.push({
85
+ label: field.label,
86
+ value: formatConfigValue(resolved.value),
87
+ source: resolved.source === "default"
88
+ ? "default"
89
+ : `${resolved.source}${file ? ` (${file})` : ""}`,
90
+ });
91
+ }
92
+ if (!rows.length)
93
+ continue;
94
+ shownAny = true;
95
+ console.log(`\n${domain.label} — ${domain.summary}`);
96
+ const labelW = Math.max(...rows.map((r) => r.label.length));
97
+ const valueW = Math.max(...rows.map((r) => r.value.length), 6);
98
+ for (const r of rows) {
99
+ console.log(` ${r.label.padEnd(labelW)} ${r.value.padEnd(valueW)} ${r.source}`);
100
+ }
101
+ }
102
+ if (!shownAny) {
103
+ console.log(opts.diff ? "\nEverything is at its default value." : "\n(no config)");
54
104
  }
105
+ console.log("");
55
106
  }
56
107
  function handleConfigShow(args) {
57
108
  const phrenPath = getPhrenPath();
58
- const { project: projectArg } = parseProjectArg(args);
109
+ const { project: projectArg, rest } = parseProjectArg(args);
110
+ const asJson = rest.includes("--json");
111
+ const diff = rest.includes("--diff");
112
+ if (projectArg && !isValidProjectName(projectArg)) {
113
+ console.error(`Invalid project name: "${projectArg}"`);
114
+ process.exit(1);
115
+ }
116
+ const view = buildConfigView(phrenPath, projectArg);
117
+ if (asJson) {
118
+ console.log(JSON.stringify(view, null, 2));
119
+ return;
120
+ }
121
+ renderConfigView(view, { diff });
59
122
  if (projectArg) {
60
- if (!isValidProjectName(projectArg)) {
61
- console.error(`Invalid project name: "${projectArg}"`);
62
- process.exit(1);
123
+ const notRegistered = checkProjectInProfile(phrenPath, projectArg);
124
+ if (notRegistered) {
125
+ console.error(`Run 'phren add /path/to/${projectArg}' to register this project.\n`);
63
126
  }
64
- const resolved = mergeConfig(phrenPath, projectArg);
65
- const inProfile = checkProjectInProfile(phrenPath, projectArg);
66
- console.log(`\nConfig for project: ${projectArg}${inProfile ? "" : " (not in active profile)"}`);
67
- formatConfigAsTable("Finding capture", [
68
- ["sensitivity", resolved.findingSensitivity],
69
- ["proactivity", resolved.proactivity.base ?? "(global)"],
70
- ["proactivity.findings", resolved.proactivity.findings ?? "(global)"],
71
- ["proactivity.tasks", resolved.proactivity.tasks ?? "(global)"],
72
- ]);
73
- formatConfigAsTable("Task automation", [
74
- ["taskMode", resolved.taskMode],
75
- ]);
76
- formatConfigAsTable("Retention policy", [
77
- ["ttlDays", String(resolved.retentionPolicy.ttlDays)],
78
- ["retentionDays", String(resolved.retentionPolicy.retentionDays)],
79
- ["autoAcceptThreshold", String(resolved.retentionPolicy.autoAcceptThreshold)],
80
- ["minInjectConfidence", String(resolved.retentionPolicy.minInjectConfidence)],
81
- ["decay.d30", String(resolved.retentionPolicy.decay.d30)],
82
- ["decay.d60", String(resolved.retentionPolicy.decay.d60)],
83
- ["decay.d90", String(resolved.retentionPolicy.decay.d90)],
84
- ["decay.d120", String(resolved.retentionPolicy.decay.d120)],
85
- ]);
86
- formatConfigAsTable("Workflow policy", [
87
- ["lowConfidenceThreshold", String(resolved.workflowPolicy.lowConfidenceThreshold)],
88
- ["riskySections", resolved.workflowPolicy.riskySections.join(", ")],
89
- ]);
90
- if (!inProfile) {
91
- console.error(`\nRun 'phren add /path/to/${projectArg}' to register this project.`);
92
- }
93
- console.log("");
94
- return;
95
127
  }
96
- // Global config — no project
97
- const retention = getRetentionPolicy(phrenPath);
98
- const workflow = getWorkflowPolicy(phrenPath);
99
- console.log("\nGlobal config (applies to all projects unless overridden)");
100
- formatConfigAsTable("Finding capture", [
101
- ["findingSensitivity", workflow.findingSensitivity],
102
- ]);
103
- formatConfigAsTable("Task automation", [
104
- ["taskMode", workflow.taskMode],
105
- ]);
106
- formatConfigAsTable("Retention policy", [
107
- ["ttlDays", String(retention.ttlDays)],
108
- ["retentionDays", String(retention.retentionDays)],
109
- ["autoAcceptThreshold", String(retention.autoAcceptThreshold)],
110
- ["minInjectConfidence", String(retention.minInjectConfidence)],
111
- ["decay.d30", String(retention.decay.d30)],
112
- ["decay.d60", String(retention.decay.d60)],
113
- ["decay.d90", String(retention.decay.d90)],
114
- ["decay.d120", String(retention.decay.d120)],
115
- ]);
116
- formatConfigAsTable("Workflow policy", [
117
- ["lowConfidenceThreshold", String(workflow.lowConfidenceThreshold)],
118
- ["riskySections", workflow.riskySections.join(", ")],
119
- ]);
120
- console.log(`\nUse '--project <name>' to see merged config for a specific project.`);
121
- console.log("");
128
+ else {
129
+ console.log("Tips: '--project <name>' for a project's merged config, '--diff' for only customised values, '--json' for machine-readable output.\n");
130
+ }
122
131
  }
123
132
  // ── Config router ────────────────────────────────────────────────────────────
124
133
  export async function handleConfig(args) {
@@ -149,6 +158,8 @@ export async function handleConfig(args) {
149
158
  return handleConfigTaskMode(rest);
150
159
  case "finding-sensitivity":
151
160
  return handleConfigFindingSensitivity(rest);
161
+ case "access":
162
+ return handleConfigAccess(rest);
152
163
  case "llm":
153
164
  return handleConfigLlm(rest);
154
165
  case "synonyms":
@@ -157,7 +168,9 @@ export async function handleConfig(args) {
157
168
  console.log(`phren config - manage settings and policies
158
169
 
159
170
  Subcommands:
160
- phren config show [--project <name>] Full merged config summary (what's actually active)
171
+ phren config show [--project <name>] [--diff] [--json]
172
+ Full merged config grouped by domain, with the
173
+ source (default/global/project) of every value
161
174
  phren config policy [get|set ...] Memory retention, TTL, confidence, decay
162
175
  phren config workflow [get|set ...] Risky-memory thresholds, task automation mode
163
176
  phren config index [get|set ...] Indexer include/exclude globs
@@ -170,6 +183,8 @@ Subcommands:
170
183
  Task automation mode (off|manual|suggest|auto)
171
184
  phren config finding-sensitivity [get|set <level>]
172
185
  Finding capture level (minimal|conservative|balanced|aggressive)
186
+ phren config access [--project <name>] [get|set --admins=...]
187
+ Role-based access lists (admins|contributors|readers)
173
188
  phren config project-ownership [mode]
174
189
  Default ownership for future project enrollments
175
190
  phren config llm [get|set model|endpoint|key]
@@ -730,6 +745,85 @@ export async function handleWorkflowPolicy(args) {
730
745
  console.error("Usage: phren config workflow [--project <name>] [get|set --lowConfidenceThreshold=0.7 --riskySections=Stale,Conflicts --taskMode=manual]");
731
746
  process.exit(1);
732
747
  }
748
+ // ── Access control ───────────────────────────────────────────────────────────
749
+ const ACCESS_ROLES = ["admins", "contributors", "readers"];
750
+ function globalAccessFile(phrenPath) {
751
+ return path.join(phrenPath, ".config", "access-control.json");
752
+ }
753
+ function readGlobalAccess(phrenPath) {
754
+ const file = globalAccessFile(phrenPath);
755
+ if (!fs.existsSync(file))
756
+ return {};
757
+ try {
758
+ const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
759
+ return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
760
+ }
761
+ catch {
762
+ return {};
763
+ }
764
+ }
765
+ function parseRoleList(raw) {
766
+ return raw.split(",").map((s) => s.trim()).filter(Boolean);
767
+ }
768
+ function printAccessSnapshot(phrenPath, projectArg) {
769
+ const view = buildConfigView(phrenPath, projectArg);
770
+ console.log(JSON.stringify({
771
+ _project: projectArg ?? null,
772
+ _note: "Effective lists are the union of global and per-project roles. All lists empty everywhere = open mode.",
773
+ admins: view.fields["access.admins"].value,
774
+ contributors: view.fields["access.contributors"].value,
775
+ readers: view.fields["access.readers"].value,
776
+ }, null, 2));
777
+ }
778
+ export function handleConfigAccess(args) {
779
+ const phrenPath = getPhrenPath();
780
+ const { project: projectArg, rest } = parseProjectArg(args);
781
+ const action = rest[0];
782
+ if (projectArg && !isValidProjectName(projectArg)) {
783
+ console.error(`Invalid project name: "${projectArg}"`);
784
+ process.exit(1);
785
+ }
786
+ if (!action || action === "get") {
787
+ printAccessSnapshot(phrenPath, projectArg);
788
+ return;
789
+ }
790
+ if (action === "set") {
791
+ const patch = {};
792
+ let touched = false;
793
+ for (const arg of rest.slice(1)) {
794
+ if (!arg.startsWith("--"))
795
+ continue;
796
+ const [k, v] = arg.slice(2).split("=");
797
+ if (!k || v === undefined)
798
+ continue;
799
+ if (ACCESS_ROLES.includes(k)) {
800
+ patch[k] = parseRoleList(v);
801
+ touched = true;
802
+ }
803
+ }
804
+ if (!touched) {
805
+ console.error("Usage: phren config access [--project <name>] set --admins=a,b --contributors=c --readers=d");
806
+ process.exit(1);
807
+ }
808
+ if (projectArg) {
809
+ warnIfUnregistered(phrenPath, projectArg);
810
+ const current = readProjectConfig(phrenPath, projectArg);
811
+ writeProjectConfig(phrenPath, projectArg, {
812
+ access: { ...(current.access ?? {}), ...patch },
813
+ });
814
+ }
815
+ else {
816
+ const next = { ...readGlobalAccess(phrenPath), ...patch };
817
+ const file = globalAccessFile(phrenPath);
818
+ fs.mkdirSync(path.dirname(file), { recursive: true });
819
+ fs.writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
820
+ }
821
+ printAccessSnapshot(phrenPath, projectArg);
822
+ return;
823
+ }
824
+ console.error("Usage: phren config access [--project <name>] [get|set --admins=a,b --contributors=c --readers=d]");
825
+ process.exit(1);
826
+ }
733
827
  // ── Machines and profiles ────────────────────────────────────────────────────
734
828
  function handleConfigMachines() {
735
829
  const manifest = readRootManifest(getPhrenPath());
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Config resolver — turns the 3-level precedence chain (default → global/profile
3
+ * → project) into a uniform, per-field view that every surface renders the same.
4
+ *
5
+ * `buildConfigView` is consumed by the `get_config` MCP tool, `phren config show`,
6
+ * the Web UI settings tab, and the VS Code settings webview, so the "where did
7
+ * this value come from" answer is computed in exactly one place.
8
+ */
9
+ import type { ConfigDomainId } from "./schema.js";
10
+ /** One field, resolved across the precedence chain. */
11
+ export interface ResolvedField {
12
+ key: string;
13
+ value: unknown;
14
+ /** Where the winning value came from. `global` covers both global files and profile defaults. */
15
+ source: "default" | "global" | "project";
16
+ /** The value this field would resolve to if the winning override were removed. */
17
+ inheritedValue: unknown;
18
+ /** File that supplied the winning value, when not a default. */
19
+ sourcePath?: string;
20
+ }
21
+ /** The resolved view of every field at a given scope. */
22
+ export interface ConfigView {
23
+ scope: "global" | "project";
24
+ project?: string;
25
+ /** Resolved fields keyed by dotted field key. */
26
+ fields: Record<string, ResolvedField>;
27
+ }
28
+ type Tier = "project" | "profile" | "global" | "default";
29
+ interface Level {
30
+ tier: Tier;
31
+ value: unknown;
32
+ path?: string;
33
+ }
34
+ /**
35
+ * Resolve one field from a precedence-ordered list of levels that actually set
36
+ * it. `levels` must be ordered highest-precedence first and must NOT include the
37
+ * default tier — the default is appended here.
38
+ *
39
+ * Redundant levels are collapsed: a level whose value equals the value of the
40
+ * level below it is a no-op (e.g. a global policy file that merely mirrors the
41
+ * defaults), so the source reflects the first level that genuinely changes the
42
+ * value — never a level that just restates what it would already be.
43
+ */
44
+ export declare function resolveConfigField(key: string, def: unknown, levels: Level[]): ResolvedField;
45
+ /**
46
+ * Build the full resolved config view for a scope. When `project` is given, the
47
+ * view reflects that project's merged config with override provenance; otherwise
48
+ * it reflects the global defaults.
49
+ *
50
+ * Note: the `topic` domain is project-specific and stored separately — it is not
51
+ * included here; use the `get_config` topic branch for that.
52
+ */
53
+ export declare function buildConfigView(phrenPath: string, project?: string): ConfigView;
54
+ /** Field keys belonging to a domain, in schema order. Excludes `topic`. */
55
+ export declare function fieldKeysForDomain(domain: ConfigDomainId): string[];
56
+ export {};
@@ -0,0 +1,241 @@
1
+ /**
2
+ * Config resolver — turns the 3-level precedence chain (default → global/profile
3
+ * → project) into a uniform, per-field view that every surface renders the same.
4
+ *
5
+ * `buildConfigView` is consumed by the `get_config` MCP tool, `phren config show`,
6
+ * the Web UI settings tab, and the VS Code settings webview, so the "where did
7
+ * this value come from" answer is computed in exactly one place.
8
+ */
9
+ import * as fs from "fs";
10
+ import * as path from "path";
11
+ import { getIndexPolicy } from "../governance/policy.js";
12
+ import { getProjectConfigOverrides } from "../governance/policy.js";
13
+ import { getActiveProfileDefaults } from "../profile-store.js";
14
+ import { readGovernanceInstallPreferences } from "../init/preferences.js";
15
+ import { readProjectConfig } from "../project-config.js";
16
+ import { isRecord } from "../shared.js";
17
+ import { allConfigFields, getConfigField } from "./schema.js";
18
+ /** Structural equality good enough for config values (scalars + flat arrays). */
19
+ function valuesEqual(a, b) {
20
+ if (a === b)
21
+ return true;
22
+ if (Array.isArray(a) && Array.isArray(b)) {
23
+ return a.length === b.length && a.every((v, i) => v === b[i]);
24
+ }
25
+ return false;
26
+ }
27
+ /**
28
+ * Resolve one field from a precedence-ordered list of levels that actually set
29
+ * it. `levels` must be ordered highest-precedence first and must NOT include the
30
+ * default tier — the default is appended here.
31
+ *
32
+ * Redundant levels are collapsed: a level whose value equals the value of the
33
+ * level below it is a no-op (e.g. a global policy file that merely mirrors the
34
+ * defaults), so the source reflects the first level that genuinely changes the
35
+ * value — never a level that just restates what it would already be.
36
+ */
37
+ export function resolveConfigField(key, def, levels) {
38
+ const chain = [...levels, { tier: "default", value: def }];
39
+ const value = chain[0].value;
40
+ // The source is the highest level whose value differs from the level below it.
41
+ let sourceIdx = chain.length - 1; // default, unless something overrides it
42
+ for (let i = 0; i < chain.length - 1; i++) {
43
+ if (!valuesEqual(chain[i].value, chain[i + 1].value)) {
44
+ sourceIdx = i;
45
+ break;
46
+ }
47
+ }
48
+ const winner = chain[sourceIdx];
49
+ const inherited = chain[sourceIdx + 1] ?? { tier: "default", value: def };
50
+ const source = winner.tier === "project" ? "project" : winner.tier === "default" ? "default" : "global";
51
+ return {
52
+ key,
53
+ value,
54
+ source,
55
+ inheritedValue: inherited.value,
56
+ ...(winner.path ? { sourcePath: winner.path } : {}),
57
+ };
58
+ }
59
+ function readRawJson(file) {
60
+ try {
61
+ if (!fs.existsSync(file))
62
+ return {};
63
+ const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
64
+ return isRecord(parsed) ? parsed : {};
65
+ }
66
+ catch {
67
+ return {};
68
+ }
69
+ }
70
+ /** A nested-path getter that returns `undefined` for any missing segment. */
71
+ function dig(obj, ...segments) {
72
+ let cur = obj;
73
+ for (const seg of segments) {
74
+ if (!isRecord(cur))
75
+ return undefined;
76
+ cur = cur[seg];
77
+ }
78
+ return cur;
79
+ }
80
+ /** Push a level only when the value is actually set (not undefined/null). */
81
+ function pushIfSet(levels, tier, value, path) {
82
+ if (value !== undefined && value !== null)
83
+ levels.push({ tier, value, path });
84
+ }
85
+ /**
86
+ * Build the full resolved config view for a scope. When `project` is given, the
87
+ * view reflects that project's merged config with override provenance; otherwise
88
+ * it reflects the global defaults.
89
+ *
90
+ * Note: the `topic` domain is project-specific and stored separately — it is not
91
+ * included here; use the `get_config` topic branch for that.
92
+ */
93
+ export function buildConfigView(phrenPath, project) {
94
+ const configDir = path.join(phrenPath, ".config");
95
+ const retentionPath = path.join(configDir, "retention-policy.json");
96
+ const workflowPath = path.join(configDir, "workflow-policy.json");
97
+ const indexPath = path.join(configDir, "index-policy.json");
98
+ const accessPath = path.join(configDir, "access-control.json");
99
+ const proactivityPath = path.join(configDir, "install-preferences.json");
100
+ const rawRetention = readRawJson(retentionPath);
101
+ const rawWorkflow = readRawJson(workflowPath);
102
+ const rawAccess = readRawJson(accessPath);
103
+ const govPrefs = readGovernanceInstallPreferences(phrenPath);
104
+ const indexPolicy = getIndexPolicy(phrenPath);
105
+ let profileDefaults;
106
+ try {
107
+ profileDefaults = getActiveProfileDefaults(phrenPath);
108
+ }
109
+ catch {
110
+ profileDefaults = undefined;
111
+ }
112
+ const overrides = project ? getProjectConfigOverrides(phrenPath, project) : null;
113
+ const projectAccess = project ? readProjectConfig(phrenPath, project).access : undefined;
114
+ const projectConfigPath = project
115
+ ? path.join(phrenPath, project, "phren.project.yaml")
116
+ : undefined;
117
+ const fields = {};
118
+ // ── proactivity ────────────────────────────────────────────────────────────
119
+ const proactivityKeyMap = {
120
+ "proactivity.base": "proactivity",
121
+ "proactivity.findings": "proactivityFindings",
122
+ "proactivity.tasks": "proactivityTask",
123
+ };
124
+ const baseLevels = [];
125
+ pushIfSet(baseLevels, "project", overrides?.proactivity, projectConfigPath);
126
+ pushIfSet(baseLevels, "profile", profileDefaults?.proactivity);
127
+ pushIfSet(baseLevels, "global", govPrefs.proactivity, proactivityPath);
128
+ const baseResolved = resolveConfigField("proactivity.base", "high", baseLevels);
129
+ fields["proactivity.base"] = baseResolved;
130
+ for (const key of ["proactivity.findings", "proactivity.tasks"]) {
131
+ const ovKey = proactivityKeyMap[key];
132
+ const levels = [];
133
+ pushIfSet(levels, "project", overrides?.[ovKey], projectConfigPath);
134
+ pushIfSet(levels, "profile", profileDefaults?.[ovKey]);
135
+ pushIfSet(levels, "global", govPrefs[ovKey], proactivityPath);
136
+ if (levels.length === 0) {
137
+ // No own override at any level: inherit the resolved base verbatim.
138
+ fields[key] = {
139
+ key,
140
+ value: baseResolved.value,
141
+ source: baseResolved.source,
142
+ inheritedValue: baseResolved.value,
143
+ ...(baseResolved.sourcePath ? { sourcePath: baseResolved.sourcePath } : {}),
144
+ };
145
+ }
146
+ else {
147
+ // Resolve against the base value, so a findings/tasks override only counts
148
+ // as a source when it genuinely diverges from the inherited base level.
149
+ fields[key] = resolveConfigField(key, baseResolved.value, levels);
150
+ }
151
+ }
152
+ // ── findingSensitivity & taskMode (live in workflow-policy.json) ────────────
153
+ const fsLevels = [];
154
+ pushIfSet(fsLevels, "project", overrides?.findingSensitivity, projectConfigPath);
155
+ pushIfSet(fsLevels, "profile", profileDefaults?.findingSensitivity);
156
+ pushIfSet(fsLevels, "global", rawWorkflow.findingSensitivity, workflowPath);
157
+ fields.findingSensitivity = resolveConfigField("findingSensitivity", getConfigField("findingSensitivity")?.default, fsLevels);
158
+ const tmLevels = [];
159
+ pushIfSet(tmLevels, "project", overrides?.taskMode, projectConfigPath);
160
+ pushIfSet(tmLevels, "profile", profileDefaults?.taskMode);
161
+ pushIfSet(tmLevels, "global", rawWorkflow.taskMode, workflowPath);
162
+ fields.taskMode = resolveConfigField("taskMode", getConfigField("taskMode")?.default, tmLevels);
163
+ // ── retention ──────────────────────────────────────────────────────────────
164
+ const retentionScalars = [
165
+ ["retention.ttlDays", "ttlDays"],
166
+ ["retention.retentionDays", "retentionDays"],
167
+ ["retention.autoAcceptThreshold", "autoAcceptThreshold"],
168
+ ["retention.minInjectConfidence", "minInjectConfidence"],
169
+ ];
170
+ for (const [fieldKey, prop] of retentionScalars) {
171
+ const levels = [];
172
+ pushIfSet(levels, "project", dig(overrides?.retentionPolicy, prop), projectConfigPath);
173
+ pushIfSet(levels, "profile", dig(profileDefaults?.retentionPolicy, prop));
174
+ pushIfSet(levels, "global", rawRetention[prop], retentionPath);
175
+ fields[fieldKey] = resolveConfigField(fieldKey, getConfigField(fieldKey)?.default, levels);
176
+ }
177
+ for (const milestone of ["d30", "d60", "d90", "d120"]) {
178
+ const fieldKey = `retention.decay.${milestone}`;
179
+ const levels = [];
180
+ pushIfSet(levels, "project", dig(overrides?.retentionPolicy, "decay", milestone), projectConfigPath);
181
+ pushIfSet(levels, "profile", dig(profileDefaults?.retentionPolicy, "decay", milestone));
182
+ pushIfSet(levels, "global", dig(rawRetention, "decay", milestone), retentionPath);
183
+ fields[fieldKey] = resolveConfigField(fieldKey, getConfigField(fieldKey)?.default, levels);
184
+ }
185
+ // ── workflow ───────────────────────────────────────────────────────────────
186
+ const lctLevels = [];
187
+ pushIfSet(lctLevels, "project", dig(overrides?.workflowPolicy, "lowConfidenceThreshold"), projectConfigPath);
188
+ pushIfSet(lctLevels, "profile", dig(profileDefaults?.workflowPolicy, "lowConfidenceThreshold"));
189
+ pushIfSet(lctLevels, "global", rawWorkflow.lowConfidenceThreshold, workflowPath);
190
+ fields["workflow.lowConfidenceThreshold"] = resolveConfigField("workflow.lowConfidenceThreshold", getConfigField("workflow.lowConfidenceThreshold")?.default, lctLevels);
191
+ const rsLevels = [];
192
+ const projectRisky = dig(overrides?.workflowPolicy, "riskySections");
193
+ pushIfSet(rsLevels, "project", Array.isArray(projectRisky) && projectRisky.length ? projectRisky : undefined, projectConfigPath);
194
+ const profileRisky = dig(profileDefaults?.workflowPolicy, "riskySections");
195
+ pushIfSet(rsLevels, "profile", Array.isArray(profileRisky) && profileRisky.length ? profileRisky : undefined);
196
+ const globalRisky = rawWorkflow.riskySections;
197
+ pushIfSet(rsLevels, "global", Array.isArray(globalRisky) && globalRisky.length ? globalRisky : undefined, workflowPath);
198
+ fields["workflow.riskySections"] = resolveConfigField("workflow.riskySections", getConfigField("workflow.riskySections")?.default, rsLevels);
199
+ // ── index (global-only) ────────────────────────────────────────────────────
200
+ const rawIndex = readRawJson(indexPath);
201
+ for (const [fieldKey, prop] of [
202
+ ["index.includeGlobs", "includeGlobs"],
203
+ ["index.excludeGlobs", "excludeGlobs"],
204
+ ["index.includeHidden", "includeHidden"],
205
+ ]) {
206
+ const levels = [];
207
+ pushIfSet(levels, "global", rawIndex[prop], indexPath);
208
+ const resolved = resolveConfigField(fieldKey, getConfigField(fieldKey)?.default, levels);
209
+ // Always report the normalized effective value for index.
210
+ fields[fieldKey] = { ...resolved, value: indexPolicy[prop] };
211
+ }
212
+ // ── access ─────────────────────────────────────────────────────────────────
213
+ for (const [fieldKey, role] of [
214
+ ["access.admins", "admins"],
215
+ ["access.contributors", "contributors"],
216
+ ["access.readers", "readers"],
217
+ ]) {
218
+ const globalList = Array.isArray(rawAccess[role]) ? rawAccess[role] : undefined;
219
+ const projectList = Array.isArray(dig(projectAccess, role))
220
+ ? dig(projectAccess, role)
221
+ : undefined;
222
+ const levels = [];
223
+ pushIfSet(levels, "project", projectList && projectList.length ? projectList : undefined, projectConfigPath);
224
+ pushIfSet(levels, "global", globalList && globalList.length ? globalList : undefined, accessPath);
225
+ // Effective value is the union of every level that contributes.
226
+ const union = [...new Set([...(globalList ?? []), ...(projectList ?? [])])];
227
+ const resolved = resolveConfigField(fieldKey, [], levels);
228
+ fields[fieldKey] = { ...resolved, value: union };
229
+ }
230
+ return {
231
+ scope: project ? "project" : "global",
232
+ ...(project ? { project } : {}),
233
+ fields,
234
+ };
235
+ }
236
+ /** Field keys belonging to a domain, in schema order. Excludes `topic`. */
237
+ export function fieldKeysForDomain(domain) {
238
+ return allConfigFields()
239
+ .filter((f) => f.domain === domain && f.domain !== "topic")
240
+ .map((f) => f.key);
241
+ }
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Shared config schema — the single source of truth every surface renders from.
3
+ *
4
+ * The CLI (`phren config`), the Web UI settings tab, and the VS Code settings
5
+ * webview all import these descriptors so their labels, help text, option lists,
6
+ * defaults, and ranges can never drift apart.
7
+ *
8
+ * Each field is a {@link ConfigFieldDescriptor}; fields are grouped into the
9
+ * eight {@link CONFIG_DOMAINS}. Nothing here renders UI — descriptors are pure
10
+ * data so every surface can present them in its own idiom.
11
+ */
12
+ /** The eight configurable domains, named to match the `get_config`/`set_config` MCP tools. */
13
+ export type ConfigDomainId = "proactivity" | "taskMode" | "findingSensitivity" | "retention" | "workflow" | "index" | "topic" | "access";
14
+ /** How a field's value is entered. Surfaces pick a widget from this. */
15
+ export type ConfigControl = "enum" | "number" | "boolean" | "string-list" | "object";
16
+ /** Where a field may be set. `global+project` fields support per-project overrides. */
17
+ export type ConfigScope = "global+project" | "global-only" | "project-only";
18
+ /** One choice for an `enum` field, with plain-English copy. */
19
+ export interface ConfigOption {
20
+ value: string;
21
+ label: string;
22
+ /** One sentence explaining what choosing this does. */
23
+ blurb: string;
24
+ /** True for the safe default most users should keep. */
25
+ recommended?: boolean;
26
+ }
27
+ /** A single configurable setting. */
28
+ export interface ConfigFieldDescriptor {
29
+ /** Dotted, stable identifier — e.g. `retention.ttlDays`, `proactivity.base`. */
30
+ key: string;
31
+ domain: ConfigDomainId;
32
+ /** Short human label. */
33
+ label: string;
34
+ /** One line shown inline next to the control. */
35
+ summary: string;
36
+ /** A paragraph shown on a help disclosure. */
37
+ help: string;
38
+ control: ConfigControl;
39
+ /** Present for `enum` and `string-list` (constrained) fields. */
40
+ options?: ConfigOption[];
41
+ /** Present for `number` fields. */
42
+ range?: {
43
+ min: number;
44
+ max: number;
45
+ step: number;
46
+ };
47
+ /** The value used when nothing is configured at any level. */
48
+ default: unknown;
49
+ scope: ConfigScope;
50
+ /** Plain-English description of what changing this affects. */
51
+ impact: string;
52
+ /** `caution` fields trigger a confirm step before applying. */
53
+ risk: "safe" | "caution";
54
+ }
55
+ /** A group of related fields. */
56
+ export interface ConfigDomainDescriptor {
57
+ id: ConfigDomainId;
58
+ label: string;
59
+ /** A codicon-style icon name (used by VS Code; ignored elsewhere). */
60
+ icon: string;
61
+ summary: string;
62
+ scope: ConfigScope;
63
+ fields: ConfigFieldDescriptor[];
64
+ }
65
+ export declare const CONFIG_DOMAINS: ConfigDomainDescriptor[];
66
+ /** Look up a domain descriptor by id. */
67
+ export declare function getConfigDomain(id: ConfigDomainId): ConfigDomainDescriptor | undefined;
68
+ /** Look up a field descriptor by its dotted key. */
69
+ export declare function getConfigField(key: string): ConfigFieldDescriptor | undefined;
70
+ /** Every field across every domain, in domain order. */
71
+ export declare function allConfigFields(): ConfigFieldDescriptor[];
72
+ /**
73
+ * Aliases mapping the historical hyphenated `phren config` subcommands to the
74
+ * canonical domain ids. Help text and routing are generated from this so the
75
+ * CLI surface can never drift from the schema.
76
+ */
77
+ export declare const CONFIG_DOMAIN_ALIASES: Record<string, ConfigDomainId>;
78
+ /** Resolve a user-supplied domain/subcommand token to a canonical domain id. */
79
+ export declare function resolveConfigDomainAlias(token: string): ConfigDomainId | undefined;