@phren/cli 0.1.40 → 0.1.42

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.
Files changed (119) hide show
  1. package/dist/auth/profiles.js +59 -5
  2. package/dist/cli/actions.js +12 -16
  3. package/dist/cli/config-access.js +8 -1
  4. package/dist/cli/extract.d.ts +27 -1
  5. package/dist/cli/extract.js +244 -9
  6. package/dist/cli/govern.js +6 -87
  7. package/dist/cli/hooks-context.d.ts +1 -1
  8. package/dist/cli/hooks-context.js +1 -1
  9. package/dist/cli/namespaces-review.js +14 -1
  10. package/dist/cli/namespaces-utils.js +1 -1
  11. package/dist/cli/session-git.d.ts +18 -0
  12. package/dist/cli/session-git.js +47 -0
  13. package/dist/cli/session-start.js +2 -2
  14. package/dist/cli/session-stop.d.ts +11 -0
  15. package/dist/cli/session-stop.js +141 -33
  16. package/dist/cli/session-tool-hook.js +17 -5
  17. package/dist/cli-registry.d.ts +1 -1
  18. package/dist/cli-registry.js +1 -0
  19. package/dist/content/archive.js +3 -2
  20. package/dist/content/dedup.d.ts +1 -4
  21. package/dist/content/dedup.js +11 -66
  22. package/dist/content/learning.d.ts +20 -2
  23. package/dist/content/learning.js +26 -7
  24. package/dist/content/quality.d.ts +23 -0
  25. package/dist/content/quality.js +123 -0
  26. package/dist/content/secrets.d.ts +52 -0
  27. package/dist/content/secrets.js +196 -0
  28. package/dist/data/access.d.ts +56 -2
  29. package/dist/data/access.js +255 -32
  30. package/dist/data/tasks.js +46 -6
  31. package/dist/entrypoint.js +5 -1
  32. package/dist/finding/impact.js +170 -43
  33. package/dist/finding/lifecycle.d.ts +19 -2
  34. package/dist/finding/lifecycle.js +18 -5
  35. package/dist/git-worktree.d.ts +19 -0
  36. package/dist/git-worktree.js +117 -0
  37. package/dist/governance/policy.d.ts +84 -4
  38. package/dist/governance/policy.js +213 -17
  39. package/dist/governance/rbac.d.ts +8 -0
  40. package/dist/governance/rbac.js +26 -0
  41. package/dist/hooks.d.ts +20 -0
  42. package/dist/hooks.js +113 -3
  43. package/dist/index.js +5 -1
  44. package/dist/init/guard-globals.d.ts +20 -0
  45. package/dist/init/guard-globals.js +72 -6
  46. package/dist/init/init-configure.js +6 -6
  47. package/dist/init/init.js +10 -6
  48. package/dist/init/setup.d.ts +4 -3
  49. package/dist/init/setup.js +120 -16
  50. package/dist/init/store-gitignore.d.ts +29 -0
  51. package/dist/init/store-gitignore.js +48 -0
  52. package/dist/link/doctor.js +86 -20
  53. package/dist/phren-core.d.ts +35 -8
  54. package/dist/phren-core.js +35 -8
  55. package/dist/phren-paths.d.ts +90 -1
  56. package/dist/phren-paths.js +150 -5
  57. package/dist/proactivity.js +1 -1
  58. package/dist/project-config.js +3 -2
  59. package/dist/project-topics.js +13 -12
  60. package/dist/shared/data-utils.js +13 -3
  61. package/dist/shared/embedding-cache.d.ts +16 -0
  62. package/dist/shared/embedding-cache.js +24 -0
  63. package/dist/shared/fragment-graph.js +10 -0
  64. package/dist/shared/index.d.ts +6 -0
  65. package/dist/shared/index.js +523 -138
  66. package/dist/shared/ollama.d.ts +14 -2
  67. package/dist/shared/ollama.js +84 -5
  68. package/dist/shared/retrieval.d.ts +22 -1
  69. package/dist/shared/retrieval.js +30 -1
  70. package/dist/shared/search-fallback.js +15 -3
  71. package/dist/shared/vector-index.d.ts +20 -1
  72. package/dist/shared/vector-index.js +18 -4
  73. package/dist/shared.d.ts +1 -1
  74. package/dist/shared.js +1 -1
  75. package/dist/status.js +18 -1
  76. package/dist/store-registry.d.ts +22 -0
  77. package/dist/store-registry.js +36 -3
  78. package/dist/store-routing.d.ts +8 -0
  79. package/dist/store-routing.js +23 -1
  80. package/dist/task/lifecycle.js +31 -0
  81. package/dist/tools/config.js +19 -9
  82. package/dist/tools/data.js +1 -1
  83. package/dist/tools/extract-facts.js +3 -2
  84. package/dist/tools/extract.js +2 -2
  85. package/dist/tools/finding.js +20 -8
  86. package/dist/tools/graph.js +9 -1
  87. package/dist/tools/memory.js +1 -1
  88. package/dist/tools/notes.js +3 -3
  89. package/dist/tools/ops.js +19 -18
  90. package/dist/tools/search.js +2 -2
  91. package/dist/tools/session.js +2 -2
  92. package/dist/tools/tasks.js +2 -2
  93. package/dist/tools/types.d.ts +32 -2
  94. package/dist/tools/types.js +41 -8
  95. package/dist/ui/scripts.js +2 -2
  96. package/dist/ui/server.js +7 -6
  97. package/dist/utils-fts.js +3 -2
  98. package/dist/utils-paths.d.ts +1 -0
  99. package/dist/utils-paths.js +1 -1
  100. package/dist/utils.d.ts +1 -1
  101. package/dist/utils.js +1 -1
  102. package/package.json +1 -1
  103. package/dist/cli-hooks-git.d.ts +0 -50
  104. package/dist/cli-hooks-git.js +0 -288
  105. package/starter/my-api/.claude/skills/README.md +0 -7
  106. package/starter/my-api/CLAUDE.md +0 -33
  107. package/starter/my-api/FINDINGS.md +0 -9
  108. package/starter/my-api/summary.md +0 -7
  109. package/starter/my-api/tasks.md +0 -7
  110. package/starter/my-first-project/.claude/skills/README.md +0 -7
  111. package/starter/my-first-project/CLAUDE.md +0 -49
  112. package/starter/my-first-project/FINDINGS.md +0 -24
  113. package/starter/my-first-project/summary.md +0 -11
  114. package/starter/my-first-project/tasks.md +0 -25
  115. package/starter/my-frontend/.claude/skills/README.md +0 -7
  116. package/starter/my-frontend/CLAUDE.md +0 -33
  117. package/starter/my-frontend/FINDINGS.md +0 -9
  118. package/starter/my-frontend/summary.md +0 -7
  119. package/starter/my-frontend/tasks.md +0 -7
@@ -7,8 +7,9 @@ import { PROACTIVITY_LEVELS, } from "../proactivity.js";
7
7
  import { writeGovernanceInstallPreferences, } from "../init/preferences.js";
8
8
  import { FINDING_SENSITIVITY_CONFIG, buildProactivitySnapshot, checkProjectInProfile } from "../cli/config.js";
9
9
  import { readProjectConfig, updateProjectConfigOverrides, } from "../project-config.js";
10
- import { isValidProjectName, safeProjectPath } from "../utils.js";
11
- import { ACCESS_ROLE_KEYS, setAccessRoles } from "../governance/rbac.js";
10
+ import { errorMessage, isValidProjectName } from "../utils.js";
11
+ import { storeAwareProjectPath } from "../store-routing.js";
12
+ import { ACCESS_ROLE_KEYS, ACL_LOCKOUT_HINT, permissionDeniedError, setAccessRoles } from "../governance/rbac.js";
12
13
  import { readProjectTopics, writeProjectTopics, } from "../project-topics.js";
13
14
  import { buildConfigView } from "../config/resolve.js";
14
15
  import { getConfigField, CONFIG_DOMAINS } from "../config/schema.js";
@@ -41,7 +42,7 @@ function hasOwnOverride(overrides, key) {
41
42
  const projectParam = z.string().optional().describe("Project name. When provided, writes to that project's phren.project.yaml instead of global .config/.");
42
43
  // ── Topic helpers (shared by get_config topic domain and set_config topic domain) ──
43
44
  function getTopicConfigData(phrenPath, project) {
44
- const projectDir = safeProjectPath(phrenPath, project);
45
+ const projectDir = storeAwareProjectPath(phrenPath, project);
45
46
  if (!projectDir || !fs.existsSync(projectDir)) {
46
47
  return { ok: false, error: `Project "${project}" not found in phren.` };
47
48
  }
@@ -101,7 +102,7 @@ async function handleGetConfig(ctx, { domain, project }) {
101
102
  let resolvedPhrenPath = phrenPath;
102
103
  let resolvedProject = project;
103
104
  try {
104
- const resolved = resolveStoreForProject(ctx, project);
105
+ const resolved = resolveStoreForProject(ctx, project, "read");
105
106
  resolvedPhrenPath = resolved.phrenPath;
106
107
  resolvedProject = resolved.project;
107
108
  }
@@ -454,6 +455,11 @@ async function handleSetConfig(ctx, { domain, settings, project }) {
454
455
  }
455
456
  // ── access ────────────────────────────────────────────────────
456
457
  case "access": {
458
+ // Rewriting the ACL is admin-only. Without this an actor the ACL denies
459
+ // every mutating action could still add itself to `admins` here.
460
+ const accessDenied = permissionDeniedError(phrenPath, "manage_config", project);
461
+ if (accessDenied)
462
+ return mcpResponse({ ok: false, error: `${accessDenied} ${ACL_LOCKOUT_HINT}` });
457
463
  const patch = {};
458
464
  let touched = false;
459
465
  for (const key of ACCESS_ROLE_KEYS) {
@@ -515,16 +521,20 @@ async function handleSetConfig(ctx, { domain, settings, project }) {
515
521
  const err = validateProject(project);
516
522
  if (err)
517
523
  return mcpResponse({ ok: false, error: err });
518
- // Resolve store-qualified project names for team stores
519
- let topicPhrenPath = phrenPath;
520
- let topicProject = project;
524
+ // Resolve store-qualified project names for team stores. This branch
525
+ // writes topic-config.json, so a failed resolution must surface instead
526
+ // of quietly writing into the primary store.
527
+ let topicPhrenPath;
528
+ let topicProject;
521
529
  try {
522
530
  const resolved = resolveStoreForProject(ctx, project);
523
531
  topicPhrenPath = resolved.phrenPath;
524
532
  topicProject = resolved.project;
525
533
  }
526
- catch { /* fall back to primary */ }
527
- const projectDir = safeProjectPath(topicPhrenPath, topicProject);
534
+ catch (err) {
535
+ return mcpResponse({ ok: false, error: errorMessage(err) });
536
+ }
537
+ const projectDir = storeAwareProjectPath(topicPhrenPath, topicProject);
528
538
  if (!projectDir || !fs.existsSync(projectDir)) {
529
539
  return mcpResponse({ ok: false, error: `Project "${topicProject}" not found in phren.` });
530
540
  }
@@ -40,7 +40,7 @@ export function register(server, ctx) {
40
40
  let resolvedPhrenPath;
41
41
  let project;
42
42
  try {
43
- const resolved = resolveStoreForProject(ctx, projectInput);
43
+ const resolved = resolveStoreForProject(ctx, projectInput, "read");
44
44
  resolvedPhrenPath = resolved.phrenPath;
45
45
  project = resolved.project;
46
46
  }
@@ -7,14 +7,15 @@
7
7
  import * as fs from "fs";
8
8
  import * as path from "path";
9
9
  import { debugLog } from "../shared.js";
10
- import { safeProjectPath, isFeatureEnabled, errorMessage } from "../utils.js";
10
+ import { isFeatureEnabled, errorMessage } from "../utils.js";
11
+ import { storeAwareProjectPath } from "../store-routing.js";
11
12
  import { callLlm } from "../content/dedup.js";
12
13
  import { withFileLock } from "../shared/governance.js";
13
14
  import { logger } from "../logger.js";
14
15
  const FACT_EXTRACT_FLAG = "PHREN_FEATURE_FACT_EXTRACT";
15
16
  const MAX_FACTS = 50;
16
17
  function preferencesPath(phrenPath, project) {
17
- const dir = safeProjectPath(phrenPath, project);
18
+ const dir = storeAwareProjectPath(phrenPath, project);
18
19
  return dir ? path.join(dir, "preferences.json") : null;
19
20
  }
20
21
  export function readExtractedFacts(phrenPath, project) {
@@ -15,7 +15,7 @@ Rules:
15
15
  - Do NOT extract obvious facts or things any developer would know
16
16
  - Do NOT extract credentials, API keys, or personal information
17
17
  - Each finding must be self-contained (understandable without seeing the source text)
18
- - Prefix each finding with its type in brackets: [decision], [pitfall], [pattern], [tradeoff], [bug], or [architecture]
18
+ - Prefix each finding with its type in brackets: [decision], [pitfall], [pattern], [bug], or [workaround]
19
19
  - Maximum 10 findings
20
20
  - If nothing is worth extracting, return []
21
21
  - Return ONLY the JSON array, no explanation, no markdown
@@ -45,7 +45,7 @@ export function register(server, ctx) {
45
45
  title: "◆ phren · auto-extract findings",
46
46
  description: "Use a local Ollama LLM to automatically extract non-obvious findings from text. " +
47
47
  "Pass conversation snippets, code review notes, error logs, or any engineering text. " +
48
- "The model identifies patterns, pitfalls, decisions, and bugs worth remembering. " +
48
+ "The model identifies patterns, pitfalls, decisions, bugs, and workarounds worth remembering. " +
49
49
  "Requires Ollama running locally. Set PHREN_EXTRACT_MODEL env var to choose model (default: llama3.2). " +
50
50
  "Set PHREN_OLLAMA_URL=off to disable.",
51
51
  inputSchema: z.object({
@@ -3,7 +3,8 @@ import { z } from "zod";
3
3
  import * as fs from "fs";
4
4
  import * as path from "path";
5
5
  import { logger } from "../logger.js";
6
- import { isValidProjectName, safeProjectPath, errorMessage } from "../utils.js";
6
+ import { isValidProjectName, errorMessage } from "../utils.js";
7
+ import { storeAwareProjectPath } from "../store-routing.js";
7
8
  import { removeFinding as removeFindingCore, removeFindings as removeFindingsCore, applyFindingTypePrefix, } from "../core/finding.js";
8
9
  import { debugLog, EXEC_TIMEOUT_MS, FINDING_TYPES, normalizeMemoryScope, } from "../shared.js";
9
10
  import { getCurrentActor, getMachineName } from "../machine-identity.js";
@@ -17,7 +18,7 @@ import { appendChildFinding, editFinding as editFindingCore, readFindings, FINDI
17
18
  import { getActiveTaskForSession } from "../task/lifecycle.js";
18
19
  import { isInactiveFindingLine, supersedeFinding, retractFinding as retractFindingLifecycle, resolveFindingContradiction, } from "../finding/lifecycle.js";
19
20
  import { permissionDeniedError } from "../governance/rbac.js";
20
- import { TEAM_STORE_PATHSPECS } from "../cli-hooks-git.js";
21
+ import { TEAM_STORE_PATHSPECS } from "../cli/session-git.js";
21
22
  const JACCARD_MAYBE_LOW = 0.25;
22
23
  const JACCARD_MAYBE_HIGH = 0.40; // above this isDuplicateFinding already catches it
23
24
  function findJaccardCandidates(phrenPath, project, finding) {
@@ -101,7 +102,7 @@ function withLifecycleMutation(phrenPath, project, writeQueue, updateIndex, hand
101
102
  const result = handler();
102
103
  if (!result.ok)
103
104
  return mcpResponse({ ok: false, error: result.error });
104
- const resolvedFindingsDir = safeProjectPath(phrenPath, project);
105
+ const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
105
106
  if (resolvedFindingsDir)
106
107
  updateIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
107
108
  const mapped = mapResponse(result.data);
@@ -382,7 +383,7 @@ async function handleGetContradictions(ctx, { project, finding_text }) {
382
383
  // Build project list from all stores (primary + team)
383
384
  let projectsWithPaths;
384
385
  if (project) {
385
- const resolved = resolveStoreForProject(ctx, project);
386
+ const resolved = resolveStoreForProject(ctx, project, "read");
386
387
  projectsWithPaths = [{ project: resolved.project, storePath: resolved.phrenPath }];
387
388
  }
388
389
  else {
@@ -445,7 +446,7 @@ async function handleEditFinding(ctx, { project: projectInput, old_text, new_tex
445
446
  const result = editFindingCore(phrenPath, project, old_text, new_text);
446
447
  if (!result.ok)
447
448
  return mcpResponse({ ok: false, error: result.error });
448
- const resolvedFindingsDir = safeProjectPath(phrenPath, project);
449
+ const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
449
450
  if (resolvedFindingsDir)
450
451
  updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
451
452
  return mcpResponse({
@@ -477,7 +478,7 @@ async function handleRemoveFinding(ctx, { project: projectInput, finding }) {
477
478
  const result = removeFindingsCore(phrenPath, project, finding);
478
479
  if (!result.ok)
479
480
  return mcpResponse({ ok: false, error: result.message });
480
- const resolvedFindingsDir = safeProjectPath(phrenPath, project);
481
+ const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
481
482
  if (resolvedFindingsDir)
482
483
  updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
483
484
  return mcpResponse({ ok: true, message: result.message, data: result.data });
@@ -487,7 +488,7 @@ async function handleRemoveFinding(ctx, { project: projectInput, finding }) {
487
488
  const result = removeFindingCore(phrenPath, project, finding);
488
489
  if (!result.ok)
489
490
  return mcpResponse({ ok: false, error: result.message });
490
- const resolvedFindingsDir = safeProjectPath(phrenPath, project);
491
+ const resolvedFindingsDir = storeAwareProjectPath(phrenPath, project);
491
492
  if (resolvedFindingsDir)
492
493
  updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
493
494
  return mcpResponse({ ok: true, message: result.message, data: result.data });
@@ -516,6 +517,17 @@ async function handlePushChanges(ctx, { message }) {
516
517
  runCustomHooks(phrenPath, "pre-save");
517
518
  // Stage all files including untracked (new project dirs, first FINDINGS.md, etc.)
518
519
  runGit(["add", "--sparse", "-A"]);
520
+ // Belt-and-suspenders: unstage sensitive files that .gitignore should
521
+ // already block (mirrors the same defensive reset in cli/session-stop.ts's
522
+ // auto-save). .config/auth-profiles.json is the legacy path for
523
+ // auth/profiles.ts's credential store (API keys, OpenAI Codex OAuth
524
+ // tokens) — this catches a store where the file was already tracked
525
+ // before it was gitignored, so a later token refresh doesn't get
526
+ // re-staged and pushed. Failures here are non-fatal (files may not exist).
527
+ try {
528
+ runGit(["reset", "HEAD", "--", ".env", "**/.env", "*.pem", "*.key", ".config/auth-profiles.json"]);
529
+ }
530
+ catch { /* best effort */ }
519
531
  runGit(["commit", "-m", commitMsg]);
520
532
  let hasRemote = false;
521
533
  try {
@@ -679,7 +691,7 @@ export function register(server, ctx) {
679
691
  sessionId: z.string().optional().describe("Optional session ID from session_start. Pass this if you want session metrics to include this write."),
680
692
  findingType: z.enum(FINDING_TYPES)
681
693
  .optional()
682
- .describe("Classify this finding: 'decision' (architectural choice with rationale), 'pitfall' (bug or failure mode to avoid), 'pattern' (reusable approach that works well), 'tradeoff' (deliberate compromise), 'architecture' (structural design note), 'bug' (confirmed defect or failure)."),
694
+ .describe("Classify this finding: 'decision' (architectural choice with rationale), 'pitfall' (bug or failure mode to avoid), 'pattern' (reusable approach that works well), 'bug' (confirmed defect or failure)."),
683
695
  scope: z.string().optional().describe("Optional memory scope label. Defaults to 'shared'. Example: 'researcher' or 'builder'."),
684
696
  }),
685
697
  }, (params) => handleAddFinding(ctx, params));
@@ -7,6 +7,14 @@ import { queryDocBySourceKey, queryRows, queryFragmentLinks, queryCrossProjectFr
7
7
  import { runtimeFile } from "../shared.js";
8
8
  import { withFileLock } from "../shared/governance.js";
9
9
  import { logger } from "../logger.js";
10
+ // NOTE on naming: titles/descriptions below all say "fragment" (the entity ->
11
+ // fragment rename, CHANGELOG 0.0.5), but the actual input schema key on
12
+ // get_related_docs, link_findings, and cross_project_fragments is still
13
+ // `entity` / `entity_type` — renaming it is a breaking change to a live MCP
14
+ // tool contract, plus link_findings persists that same shape to
15
+ // .runtime/manual-links.json (read back in shared/index.ts), so it is not a
16
+ // same-PR-safe rename. Left as-is; flagged for a product decision rather than
17
+ // changed unilaterally.
10
18
  export function register(server, ctx) {
11
19
  // ── search_fragments ──────────────────────────────────────────────────
12
20
  server.registerTool("search_fragments", {
@@ -88,7 +96,7 @@ export function register(server, ctx) {
88
96
  const docProject = doc.split("/")[0];
89
97
  let docPhrenPath = ctx.phrenPath;
90
98
  try {
91
- docPhrenPath = resolveStoreForProject(ctx, docProject).phrenPath;
99
+ docPhrenPath = resolveStoreForProject(ctx, docProject, "read").phrenPath;
92
100
  }
93
101
  catch { /* fall back to primary */ }
94
102
  const docRow = queryDocBySourceKey(db, docPhrenPath, doc);
@@ -47,7 +47,7 @@ export function register(server, ctx) {
47
47
  let phrenPath;
48
48
  let project;
49
49
  try {
50
- const resolved = resolveStoreForProject(ctx, projectInput);
50
+ const resolved = resolveStoreForProject(ctx, projectInput, "read");
51
51
  phrenPath = resolved.phrenPath;
52
52
  project = resolved.project;
53
53
  }
@@ -6,9 +6,9 @@ import { addNote, editNote, listNotes, removeNote } from "../data/notes.js";
6
6
  import { promoteNote } from "../core/note.js";
7
7
  import { permissionDeniedError } from "../governance/rbac.js";
8
8
  import { mcpResponse, resolveStoreForProject } from "./types.js";
9
- function resolve(ctx, projectInput) {
9
+ function resolve(ctx, projectInput, mode = "write") {
10
10
  try {
11
- return { ok: true, value: resolveStoreForProject(ctx, projectInput) };
11
+ return { ok: true, value: resolveStoreForProject(ctx, projectInput, mode) };
12
12
  }
13
13
  catch (err) {
14
14
  return { ok: false, error: err instanceof Error ? err.message : String(err) };
@@ -38,7 +38,7 @@ export function register(server, ctx) {
38
38
  limit: z.number().int().min(1).max(500).optional().describe("Maximum notes to return. Defaults to 100."),
39
39
  }),
40
40
  }, async ({ project: projectInput, date, limit }) => {
41
- const target = resolve(ctx, projectInput);
41
+ const target = resolve(ctx, projectInput, "read");
42
42
  if (!target.ok)
43
43
  return mcpResponse({ ok: false, error: target.error });
44
44
  const { phrenPath, project } = target.value;
package/dist/tools/ops.js CHANGED
@@ -1,8 +1,8 @@
1
- import { mcpResponse } from "./types.js";
1
+ import { mcpResponse, resolveStoreForProject } from "./types.js";
2
2
  import { z } from "zod";
3
3
  import * as fs from "fs";
4
4
  import * as path from "path";
5
- import { runtimeFile, getProjectDirs } from "../shared.js";
5
+ import { runtimeFile, getProjectDirs, projectSlugFromPath } from "../shared.js";
6
6
  import { findFtsCacheForPath } from "../shared/index.js";
7
7
  import { isValidProjectName, errorMessage } from "../utils.js";
8
8
  import { readReviewQueue, readReviewQueueAcrossProjects, approveQueueItem, rejectQueueItem, editQueueItem } from "../data/access.js";
@@ -10,11 +10,11 @@ import { addProjectFromPath } from "../core/project.js";
10
10
  import { PROJECT_OWNERSHIP_MODES, parseProjectOwnershipMode } from "../project-config.js";
11
11
  import { resolveRuntimeProfile } from "../runtime-profile.js";
12
12
  import { getMachineName } from "../machine-identity.js";
13
- import { resolveAllStores } from "../store-registry.js";
13
+ import { resolveAllStores, describeUnavailableStore } from "../store-registry.js";
14
14
  import { getProjectConsolidationStatus, CONSOLIDATION_ENTRY_THRESHOLD } from "../content/validate.js";
15
15
  import { logger } from "../logger.js";
16
16
  import { getRuntimeHealth } from "../governance/policy.js";
17
- import { countUnsyncedCommits } from "../cli-hooks-git.js";
17
+ import { countUnsyncedCommits } from "../cli/session-git.js";
18
18
  // ── Handlers ─────────────────────────────────────────────────────────────────
19
19
  async function handleAddProject(ctx, { path: targetPath, profile: requestedProfile, ownership, store: storeName }) {
20
20
  const { phrenPath, profile, withWriteQueue } = ctx;
@@ -23,6 +23,7 @@ async function handleAddProject(ctx, { path: targetPath, profile: requestedProfi
23
23
  // Resolve the target store path: explicit store > auto-route by project claim > primary
24
24
  let targetPhrenPath = phrenPath;
25
25
  let storeRole = "primary";
26
+ const projectName = targetPath ? projectSlugFromPath(targetPath) : undefined;
26
27
  if (storeName) {
27
28
  const stores = resolveAllStores(phrenPath);
28
29
  const store = stores.find((s) => s.name === storeName);
@@ -32,23 +33,23 @@ async function handleAddProject(ctx, { path: targetPath, profile: requestedProfi
32
33
  if (store.role === "readonly") {
33
34
  return mcpResponse({ ok: false, error: `Store "${storeName}" is read-only` });
34
35
  }
36
+ if (store.available === false) {
37
+ return mcpResponse({ ok: false, error: describeUnavailableStore(store) });
38
+ }
35
39
  targetPhrenPath = store.path;
36
40
  storeRole = store.role;
37
41
  }
38
- else {
39
- // Check if any non-primary writable store claims this project
40
- const projectName = targetPath
41
- ? path.basename(path.resolve(targetPath)).toLowerCase().replace(/[^a-z0-9_-]/g, "-")
42
- : undefined;
43
- if (projectName) {
44
- const stores = resolveAllStores(phrenPath);
45
- for (const store of stores) {
46
- if (store.role !== "readonly" && store.role !== "primary" && store.projects?.includes(projectName)) {
47
- targetPhrenPath = store.path;
48
- storeRole = store.role;
49
- break;
50
- }
51
- }
42
+ else if (projectName) {
43
+ // Same rule as every other write: a store that claims this project but
44
+ // is not attached here must fail, never fall through to the primary
45
+ // store — that is what copied work projects into the personal store.
46
+ try {
47
+ const resolved = resolveStoreForProject(ctx, projectName);
48
+ targetPhrenPath = resolved.phrenPath;
49
+ storeRole = resolved.storeRole;
50
+ }
51
+ catch (err) {
52
+ return mcpResponse({ ok: false, error: errorMessage(err) });
52
53
  }
53
54
  }
54
55
  const added = addProjectFromPath(phrenPath, targetPath, requestedProfile || profile || undefined, parseProjectOwnershipMode(ownership) ?? undefined, { writeToPath: targetPhrenPath });
@@ -643,7 +643,7 @@ async function handleListProjects(ctx, { page, page_size }) {
643
643
  async function handleGetFindings(ctx, { project, limit, include_superseded, include_history, status }) {
644
644
  if (!isValidProjectName(project))
645
645
  return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
646
- const resolved = resolveStoreForProject(ctx, project);
646
+ const resolved = resolveStoreForProject(ctx, project, "read");
647
647
  const { phrenPath } = resolved;
648
648
  const includeHistory = include_history ?? include_superseded ?? false;
649
649
  // Always read with archive so we can compute historyCount without a second read
@@ -763,7 +763,7 @@ export function register(server, ctx) {
763
763
  .describe("Filter by document type: claude, findings, reference, summary, task, skill"),
764
764
  tag: z.preprocess(value => typeof value === "string" ? value.toLowerCase() : value, z.enum(FINDING_TAGS))
765
765
  .optional()
766
- .describe("Filter findings by type tag: decision, pitfall, pattern, tradeoff, architecture, bug."),
766
+ .describe("Filter findings by type tag: decision, pitfall, pattern, bug, workaround, context."),
767
767
  since: z.string().optional().describe('Filter findings by creation date. Formats: "7d" (last 7 days), "30d" (last 30 days), "YYYY-MM" (since start of month), "YYYY-MM-DD" (since date).'),
768
768
  status: z.enum(FINDING_LIFECYCLE_STATUSES).optional().describe("Filter findings by lifecycle status: active, superseded, contradicted, stale, invalid_citation, or retracted."),
769
769
  include_history: z.boolean().optional().describe("When true, include historical findings (superseded/retracted). Default false."),
@@ -410,7 +410,7 @@ export function register(server, ctx) {
410
410
  if (activeProject && isValidProjectName(activeProject)) {
411
411
  const projectStorePath = (() => {
412
412
  try {
413
- return resolveStoreForProject(ctx, activeProject).phrenPath;
413
+ return resolveStoreForProject(ctx, activeProject, "read").phrenPath;
414
414
  }
415
415
  catch {
416
416
  return phrenPath;
@@ -572,7 +572,7 @@ export function register(server, ctx) {
572
572
  if (!endedState.project)
573
573
  return phrenPath;
574
574
  try {
575
- return resolveStoreForProject(ctx, endedState.project).phrenPath;
575
+ return resolveStoreForProject(ctx, endedState.project, "read").phrenPath;
576
576
  }
577
577
  catch {
578
578
  return phrenPath;
@@ -109,7 +109,7 @@ export function register(server, ctx) {
109
109
  return mcpResponse({ ok: false, error: "Provide `project` when looking up a single item." });
110
110
  if (!isValidProjectName(project))
111
111
  return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
112
- const resolvedPath = resolveStoreForProject(ctx, project).phrenPath;
112
+ const resolvedPath = resolveStoreForProject(ctx, project, "read").phrenPath;
113
113
  const result = readTasks(resolvedPath, project);
114
114
  if (!result.ok)
115
115
  return mcpResponse({ ok: false, error: result.error });
@@ -142,7 +142,7 @@ export function register(server, ctx) {
142
142
  if (project) {
143
143
  if (!isValidProjectName(project))
144
144
  return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
145
- const resolvedPath = resolveStoreForProject(ctx, project).phrenPath;
145
+ const resolvedPath = resolveStoreForProject(ctx, project, "read").phrenPath;
146
146
  const result = readTasks(resolvedPath, project);
147
147
  if (!result.ok)
148
148
  return mcpResponse({ ok: false, error: result.error });
@@ -1,4 +1,5 @@
1
1
  import type { SqlJsDatabase } from "../shared/index.js";
2
+ import { type StoreEntry } from "../store-registry.js";
2
3
  export interface McpContext {
3
4
  phrenPath: string;
4
5
  profile: string;
@@ -12,12 +13,41 @@ export interface McpContext {
12
13
  }[];
13
14
  }>;
14
15
  }
16
+ /**
17
+ * How the caller intends to use the resolved store.
18
+ *
19
+ * - `"write"` (default) — the resolution must be exact. If a store claims the
20
+ * project but is not attached on this machine, resolution **fails loudly**
21
+ * rather than silently redirecting the write somewhere else.
22
+ * - `"read"` — the caller only reads. Missing team stores degrade to the
23
+ * primary store so search/list surfaces keep working offline; nothing leaves
24
+ * the machine, so a wrong answer here is a gap, not a leak.
25
+ *
26
+ * Defaulting to `"write"` is deliberate: an unclassified call site should get
27
+ * the safe behavior, not the lossy one.
28
+ */
29
+ export type StoreAccessMode = "read" | "write";
30
+ /**
31
+ * Error raised when a project is claimed by a store that is declared in
32
+ * stores.yaml but has no directory on this machine. Distinct class so callers
33
+ * can special-case it if they ever want to offer an interactive fix.
34
+ */
35
+ export declare class StoreUnavailableError extends Error {
36
+ readonly storeName: string;
37
+ readonly storePath: string;
38
+ constructor(store: StoreEntry, project: string);
39
+ }
15
40
  /**
16
41
  * Resolve the effective phrenPath and bare project name for a project input.
17
42
  * Handles store-qualified names ("store/project") by routing to the correct store.
18
- * Returns the primary store path for bare names.
43
+ * Returns the primary store path for bare names that no store claims.
44
+ *
45
+ * Note on the bare-name path: a store that claims the project but is missing
46
+ * locally used to fall through to the primary store, which quietly relocated
47
+ * team-store projects into the user's personal store. That fallback is gone for
48
+ * writes — see {@link StoreAccessMode}.
19
49
  */
20
- export declare function resolveStoreForProject(ctx: McpContext, projectInput: string): {
50
+ export declare function resolveStoreForProject(ctx: McpContext, projectInput: string, mode?: StoreAccessMode): {
21
51
  phrenPath: string;
22
52
  project: string;
23
53
  storeRole: string;
@@ -1,26 +1,54 @@
1
1
  import { parseStoreQualified } from "../store-routing.js";
2
- import { resolveAllStores } from "../store-registry.js";
2
+ import { describeUnavailableStore, resolveAllStores } from "../store-registry.js";
3
+ import { logger } from "../logger.js";
4
+ /**
5
+ * Error raised when a project is claimed by a store that is declared in
6
+ * stores.yaml but has no directory on this machine. Distinct class so callers
7
+ * can special-case it if they ever want to offer an interactive fix.
8
+ */
9
+ export class StoreUnavailableError extends Error {
10
+ storeName;
11
+ storePath;
12
+ constructor(store, project) {
13
+ super(`Refusing to write "${project}": it belongs to a store that is not available here. ` +
14
+ `${describeUnavailableStore(store)} ` +
15
+ `Writing it to the primary store instead would copy ${store.role}-store data into your personal store, ` +
16
+ `so phren stopped instead. Re-run once the store is attached, or use "phren team unsubscribe ${store.name} ${project}" ` +
17
+ `if this project should no longer live there.`);
18
+ this.name = "StoreUnavailableError";
19
+ this.storeName = store.name;
20
+ this.storePath = store.path;
21
+ }
22
+ }
3
23
  /**
4
24
  * Resolve the effective phrenPath and bare project name for a project input.
5
25
  * Handles store-qualified names ("store/project") by routing to the correct store.
6
- * Returns the primary store path for bare names.
26
+ * Returns the primary store path for bare names that no store claims.
27
+ *
28
+ * Note on the bare-name path: a store that claims the project but is missing
29
+ * locally used to fall through to the primary store, which quietly relocated
30
+ * team-store projects into the user's personal store. That fallback is gone for
31
+ * writes — see {@link StoreAccessMode}.
7
32
  */
8
- export function resolveStoreForProject(ctx, projectInput) {
33
+ export function resolveStoreForProject(ctx, projectInput, mode = "write") {
9
34
  const { storeName, projectName } = parseStoreQualified(projectInput);
35
+ const stores = resolveAllStores(ctx.phrenPath);
10
36
  if (!storeName) {
11
37
  // Check if any non-readonly store claims this project via projects[] array.
12
38
  // This enables automatic write routing: once a project is claimed by a team
13
39
  // store (via `phren team add-project`), writes go there without needing the
14
40
  // store-qualified prefix.
15
- const stores = resolveAllStores(ctx.phrenPath);
16
- for (const store of stores) {
17
- if (store.role !== "readonly" && store.role !== "primary" && store.projects?.includes(projectName)) {
18
- return { phrenPath: store.path, project: projectName, storeRole: store.role };
41
+ const claiming = stores.find((s) => s.role !== "readonly" && s.role !== "primary" && s.projects?.includes(projectName));
42
+ if (claiming) {
43
+ if (claiming.available !== false) {
44
+ return { phrenPath: claiming.path, project: projectName, storeRole: claiming.role };
19
45
  }
46
+ if (mode === "write")
47
+ throw new StoreUnavailableError(claiming, projectName);
48
+ logger.debug("store-routing", `read for "${projectName}" fell back to primary: ${describeUnavailableStore(claiming)}`);
20
49
  }
21
50
  return { phrenPath: ctx.phrenPath, project: projectName, storeRole: "primary" };
22
51
  }
23
- const stores = resolveAllStores(ctx.phrenPath);
24
52
  const store = stores.find((s) => s.name === storeName);
25
53
  if (!store) {
26
54
  throw new Error(`Store "${storeName}" not found`);
@@ -28,6 +56,11 @@ export function resolveStoreForProject(ctx, projectInput) {
28
56
  if (store.role === "readonly") {
29
57
  throw new Error(`Store "${storeName}" is read-only`);
30
58
  }
59
+ // An explicitly named store has no defensible fallback — the caller asked for
60
+ // that store by name, so say it isn't here rather than answering from another.
61
+ if (store.available === false) {
62
+ throw new StoreUnavailableError(store, projectName);
63
+ }
31
64
  return { phrenPath: store.path, project: projectName, storeRole: store.role };
32
65
  }
33
66
  /**
@@ -319,10 +319,10 @@ export function renderNotesEnhancementScript() {
319
319
  if (!confirm('Remove this note?')) return;
320
320
  request(project, 'DELETE', { note: note }, function() { loadNotes(false); });
321
321
  } else if (action === 'promote') {
322
- var findingType = prompt('Finding type (optional): decision, pitfall, pattern, tradeoff, architecture, bug', '');
322
+ var findingType = prompt('Finding type (optional): decision, pitfall, pattern, bug', '');
323
323
  if (findingType === null) return;
324
324
  findingType = findingType.trim().toLowerCase();
325
- var valid = ['', 'decision', 'pitfall', 'pattern', 'tradeoff', 'architecture', 'bug'];
325
+ var valid = ['', 'decision', 'pitfall', 'pattern', 'bug'];
326
326
  if (valid.indexOf(findingType) === -1) { alert('Unknown finding type.'); return; }
327
327
  request(project, 'POST', { action: 'promote', note: note, finding_type: findingType }, function() { loadNotes(false); });
328
328
  }
package/dist/ui/server.js CHANGED
@@ -15,7 +15,8 @@ import { buildGraph, collectProjectsForUI, collectSkillsForUI, getHooksData, isA
15
15
  import { lookupEventsLogFile } from "../shared.js";
16
16
  import { CONSOLIDATION_ENTRY_THRESHOLD } from "../content/validate.js";
17
17
  import { ensureTopicReferenceDoc, getProjectTopicsResponse, listProjectReferenceDocs, pinProjectTopicSuggestion, readReferenceContent, reclassifyLegacyTopicDocs, unpinProjectTopicSuggestion, writeProjectTopics, } from "../project-topics.js";
18
- import { getWorkflowPolicy, updateWorkflowPolicy, mergeConfig, getRetentionPolicy, getProjectConfigOverrides, getIndexPolicy, updateIndexPolicy, VALID_TASK_MODES } from "../governance/policy.js";
18
+ import { getWorkflowPolicy, updateWorkflowPolicy, updateRetentionPolicy, mergeConfig, getRetentionPolicy, getProjectConfigOverrides, getIndexPolicy, updateIndexPolicy, VALID_TASK_MODES } from "../governance/policy.js";
19
+ import { listProfiles, setMachineProfile, getDefaultMachineAlias } from "../profile-store.js";
19
20
  import { setAccessRoles, ACCESS_ROLE_KEYS, permissionDeniedError } from "../governance/rbac.js";
20
21
  import { readProjectConfig, updateProjectConfigOverrides } from "../project-config.js";
21
22
  import { buildConfigView } from "../config/resolve.js";
@@ -986,6 +987,11 @@ function handlePostSettingsAccess(req, res, url, ctx) {
986
987
  }
987
988
  if (!Object.keys(patch).length)
988
989
  return jsonErr(res, "Provide at least one of: admins, contributors, readers");
990
+ // Rewriting the ACL is admin-only — otherwise a denied actor could POST
991
+ // itself into `admins` here and undo every other check on this server.
992
+ const denied = permissionDeniedError(ctx.phrenPath, "manage_config", project || undefined);
993
+ if (denied)
994
+ return jsonErr(res, denied, 403);
989
995
  try {
990
996
  const written = setAccessRoles(ctx.phrenPath, patch, project || undefined);
991
997
  jsonOk(res, { ok: true, access: written });
@@ -1004,7 +1010,6 @@ function handlePostSettingsMcpEnabled(req, res, url, ctx) {
1004
1010
  }
1005
1011
  function handleGetProfiles(res, ctx) {
1006
1012
  try {
1007
- const { listProfiles } = require("../profile-store.js");
1008
1013
  const profileResult = listProfiles(ctx.phrenPath);
1009
1014
  if (!profileResult.ok) {
1010
1015
  return jsonOk(res, { ok: false, error: profileResult.error, profiles: [] });
@@ -1022,7 +1027,6 @@ function handlePostProfile(req, res, url, ctx) {
1022
1027
  if (!profileName)
1023
1028
  return jsonErr(res, "Profile name required", 400);
1024
1029
  try {
1025
- const { setMachineProfile, getDefaultMachineAlias } = require("../profile-store.js");
1026
1030
  const machineAlias = getDefaultMachineAlias();
1027
1031
  const result = setMachineProfile(ctx.phrenPath, machineAlias, profileName);
1028
1032
  if (!result.ok)
@@ -1077,7 +1081,6 @@ function handlePostSettingsProjectOverrides(req, res, url, ctx) {
1077
1081
  if (globalUpdate) {
1078
1082
  try {
1079
1083
  if (NUMERIC_RETENTION_FIELDS.includes(field)) {
1080
- const { updateRetentionPolicy } = require("../governance/policy.js");
1081
1084
  let updateData = {};
1082
1085
  if (!clearField) {
1083
1086
  const num = parseFloat(value);
@@ -1091,7 +1094,6 @@ function handlePostSettingsProjectOverrides(req, res, url, ctx) {
1091
1094
  return jsonOk(res, { ok: true, retentionPolicy: result.data });
1092
1095
  }
1093
1096
  else if (field.startsWith("decay.")) {
1094
- const { updateRetentionPolicy } = require("../governance/policy.js");
1095
1097
  const point = field.slice("decay.".length);
1096
1098
  let updateData = {};
1097
1099
  if (!clearField) {
@@ -1113,7 +1115,6 @@ function handlePostSettingsProjectOverrides(req, res, url, ctx) {
1113
1115
  return jsonOk(res, { ok: true, workflowPolicy: result.data });
1114
1116
  }
1115
1117
  else if (NUMERIC_WORKFLOW_FIELDS.includes(field)) {
1116
- const { updateWorkflowPolicy } = require("../governance/policy.js");
1117
1118
  let updateData = {};
1118
1119
  if (!clearField) {
1119
1120
  const num = parseFloat(value);
package/dist/utils-fts.js CHANGED
@@ -3,7 +3,8 @@ import * as path from "path";
3
3
  import * as yaml from "js-yaml";
4
4
  import { fileURLToPath } from "url";
5
5
  import { findPhrenPath } from "./phren-paths.js";
6
- import { isValidProjectName, safeProjectPath } from "./utils-paths.js";
6
+ import { isValidProjectName } from "./utils-paths.js";
7
+ import { storeAwareProjectPath } from "./store-routing.js";
7
8
  // Lazy import of logDebug to break circular dependency:
8
9
  // utils.ts -> phren-paths.ts -> logger.ts -> phren-paths.ts -> utils.ts
9
10
  let _logDebug;
@@ -184,7 +185,7 @@ function parseLearnedSynonymsJson(filePath) {
184
185
  export function learnedSynonymsPath(phrenPath, project) {
185
186
  if (!isValidProjectName(project))
186
187
  return null;
187
- return safeProjectPath(phrenPath, project, LEARNED_SYNONYMS_FILE);
188
+ return storeAwareProjectPath(phrenPath, project, LEARNED_SYNONYMS_FILE);
188
189
  }
189
190
  export function loadLearnedSynonyms(project, phrenPath) {
190
191
  if (!project || !isValidProjectName(project))
@@ -1,3 +1,4 @@
1
1
  export declare function isValidProjectName(name: string): boolean;
2
2
  export declare function safeProjectPath(base: string, ...segments: string[]): string | null;
3
+ export declare const QUEUE_FILENAME = "review.md";
3
4
  export declare function queueFilePath(phrenPath: string, project: string): string;
@@ -48,7 +48,7 @@ export function safeProjectPath(base, ...segments) {
48
48
  }
49
49
  return resolved;
50
50
  }
51
- const QUEUE_FILENAME = "review.md";
51
+ export const QUEUE_FILENAME = "review.md";
52
52
  export function queueFilePath(phrenPath, project) {
53
53
  if (!isValidProjectName(project)) {
54
54
  throw new Error(`Invalid project name: ${project}`);