@phren/cli 0.1.39 → 0.1.41

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 (124) hide show
  1. package/dist/auth/profiles.js +59 -5
  2. package/dist/cli/actions.js +11 -3
  3. package/dist/cli/config-access.js +8 -1
  4. package/dist/cli/extract.d.ts +27 -1
  5. package/dist/cli/extract.js +243 -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/session-background.js +4 -0
  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 +157 -33
  16. package/dist/cli/session-tool-hook.js +17 -5
  17. package/dist/cli-handlers.d.ts +2 -0
  18. package/dist/cli-handlers.js +40 -0
  19. package/dist/cli-registry.d.ts +1 -1
  20. package/dist/cli-registry.js +16 -1
  21. package/dist/content/dedup.d.ts +1 -4
  22. package/dist/content/dedup.js +7 -63
  23. package/dist/content/learning.d.ts +20 -2
  24. package/dist/content/learning.js +21 -3
  25. package/dist/content/quality.d.ts +23 -0
  26. package/dist/content/quality.js +123 -0
  27. package/dist/content/secrets.d.ts +52 -0
  28. package/dist/content/secrets.js +193 -0
  29. package/dist/data/access.d.ts +56 -2
  30. package/dist/data/access.js +246 -24
  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 +15 -3
  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 +209 -14
  39. package/dist/governance/rbac.d.ts +8 -0
  40. package/dist/governance/rbac.js +26 -0
  41. package/dist/hooks.d.ts +26 -0
  42. package/dist/hooks.js +119 -6
  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.d.ts +7 -2
  47. package/dist/init/init-configure.js +42 -16
  48. package/dist/init/init-preset.d.ts +3 -0
  49. package/dist/init/init-preset.js +122 -0
  50. package/dist/init/init-uninstall.js +9 -0
  51. package/dist/init/init-walkthrough.d.ts +2 -0
  52. package/dist/init/init-walkthrough.js +42 -17
  53. package/dist/init/init.d.ts +5 -0
  54. package/dist/init/init.js +71 -19
  55. package/dist/init/management-preset.d.ts +42 -0
  56. package/dist/init/management-preset.js +122 -0
  57. package/dist/init/preferences.d.ts +17 -0
  58. package/dist/init/preferences.js +3 -0
  59. package/dist/init/self-wiring.d.ts +5 -0
  60. package/dist/init/self-wiring.js +52 -0
  61. package/dist/init/setup.d.ts +9 -4
  62. package/dist/init/setup.js +139 -23
  63. package/dist/init/store-gitignore.d.ts +29 -0
  64. package/dist/init/store-gitignore.js +48 -0
  65. package/dist/init/teardown.d.ts +15 -0
  66. package/dist/init/teardown.js +241 -0
  67. package/dist/link/doctor.js +127 -34
  68. package/dist/link/link.js +49 -26
  69. package/dist/phren-core.d.ts +35 -8
  70. package/dist/phren-core.js +35 -8
  71. package/dist/phren-paths.d.ts +90 -1
  72. package/dist/phren-paths.js +150 -5
  73. package/dist/proactivity.js +1 -1
  74. package/dist/shared/embedding-cache.d.ts +16 -0
  75. package/dist/shared/embedding-cache.js +24 -0
  76. package/dist/shared/fragment-graph.js +10 -0
  77. package/dist/shared/index.d.ts +6 -0
  78. package/dist/shared/index.js +523 -138
  79. package/dist/shared/ollama.d.ts +14 -2
  80. package/dist/shared/ollama.js +84 -5
  81. package/dist/shared/retrieval.d.ts +22 -1
  82. package/dist/shared/retrieval.js +30 -1
  83. package/dist/shared/search-fallback.js +15 -3
  84. package/dist/shared/vector-index.d.ts +20 -1
  85. package/dist/shared/vector-index.js +18 -4
  86. package/dist/shared.d.ts +1 -1
  87. package/dist/shared.js +1 -1
  88. package/dist/status.js +31 -2
  89. package/dist/store-registry.d.ts +22 -0
  90. package/dist/store-registry.js +36 -3
  91. package/dist/task/lifecycle.js +31 -0
  92. package/dist/tools/config.js +16 -7
  93. package/dist/tools/data.js +1 -1
  94. package/dist/tools/extract.js +2 -2
  95. package/dist/tools/finding.js +14 -3
  96. package/dist/tools/graph.js +9 -1
  97. package/dist/tools/memory.js +1 -1
  98. package/dist/tools/notes.js +3 -3
  99. package/dist/tools/ops.js +19 -18
  100. package/dist/tools/search.js +2 -2
  101. package/dist/tools/session.js +2 -2
  102. package/dist/tools/tasks.js +2 -2
  103. package/dist/tools/types.d.ts +32 -2
  104. package/dist/tools/types.js +41 -8
  105. package/dist/ui/scripts.js +2 -2
  106. package/dist/ui/server.js +5 -0
  107. package/package.json +1 -1
  108. package/dist/cli-hooks-git.d.ts +0 -50
  109. package/dist/cli-hooks-git.js +0 -288
  110. package/starter/my-api/.claude/skills/README.md +0 -7
  111. package/starter/my-api/CLAUDE.md +0 -33
  112. package/starter/my-api/FINDINGS.md +0 -9
  113. package/starter/my-api/summary.md +0 -7
  114. package/starter/my-api/tasks.md +0 -7
  115. package/starter/my-first-project/.claude/skills/README.md +0 -7
  116. package/starter/my-first-project/CLAUDE.md +0 -49
  117. package/starter/my-first-project/FINDINGS.md +0 -24
  118. package/starter/my-first-project/summary.md +0 -11
  119. package/starter/my-first-project/tasks.md +0 -25
  120. package/starter/my-frontend/.claude/skills/README.md +0 -7
  121. package/starter/my-frontend/CLAUDE.md +0 -33
  122. package/starter/my-frontend/FINDINGS.md +0 -9
  123. package/starter/my-frontend/summary.md +0 -7
  124. package/starter/my-frontend/tasks.md +0 -7
package/dist/init/init.js CHANGED
@@ -7,7 +7,7 @@ import * as fs from "fs";
7
7
  import * as path from "path";
8
8
  import { execFileSync } from "child_process";
9
9
  import { getMachineName, persistMachineName } from "../machine-identity.js";
10
- import { atomicWriteText, debugLog, expandHomePath, writeRootManifest, } from "../shared.js";
10
+ import { atomicWriteText, debugLog, expandHomePath, homePath, projectSlugFromPath, writeRootManifest, } from "../shared.js";
11
11
  import { isValidProjectName, errorMessage } from "../utils.js";
12
12
  import { logger } from "../logger.js";
13
13
  export { configureClaude, configureVSCode, configureCursorMcp, configureCopilotMcp, configureCodexMcp, logMcpTargetStatus, resetVSCodeProbeCache, patchJsonFile, } from "./config.js";
@@ -19,17 +19,21 @@ export { ensureGovernanceFiles, repairPreexistingInstall, runPostInitVerify, get
19
19
  export { configureMcpTargets, warmSemanticSearch, runProjectLocalInit } from "./init-configure.js";
20
20
  export { runMcpMode } from "./init-mcp-mode.js";
21
21
  export { runHooksMode } from "./init-hooks-mode.js";
22
+ export { runPreset } from "./init-preset.js";
23
+ export { printSelfWiringSnippet } from "./self-wiring.js";
22
24
  export { runUninstall } from "./init-uninstall.js";
23
25
  // Internal imports from extracted modules (used by runInit)
24
26
  import { configureMcpTargets, configureHooksIfEnabled, applyOnboardingPreferences, writeWalkthroughEnvDefaults, collectRepairedAssetLabels, applyProjectStorageBindings, warmSemanticSearch, runProjectLocalInit, } from "./init-configure.js";
25
27
  import { runWalkthrough, createWalkthroughPrompts, createWalkthroughStyle } from "./init-walkthrough.js";
26
28
  import { assertNoGlobalWiringConflict } from "./guard-globals.js";
27
- import { getMcpEnabledPreference, getHooksEnabledPreference, writeInstallPreferences, readInstallPreferences, } from "./preferences.js";
29
+ import { getMcpEnabledPreference, getHooksEnabledPreference, writeInstallPreferences, readInstallPreferences, setManagementPresetPreference, } from "./preferences.js";
28
30
  import { ensureGovernanceFiles, repairPreexistingInstall, runPostInitVerify, applyStarterTemplateUpdates, listTemplates, applyTemplate, ensureProjectScaffold, ensureLocalGitRepo, bootstrapFromExisting, updateMachinesYaml, detectProjectDir, isProjectTracked, } from "./setup.js";
29
- import { DEFAULT_PHREN_PATH, STARTER_DIR, VERSION, log } from "./shared.js";
31
+ import { STARTER_DIR, VERSION, log } from "./shared.js";
30
32
  import { PROJECT_OWNERSHIP_MODES, getProjectOwnershipDefault, } from "../project-config.js";
31
33
  import { getWorkflowPolicy } from "../shared/governance.js";
32
34
  import { addProjectToProfile } from "../profile-store.js";
35
+ import { DEFAULT_MANAGEMENT_PRESET, capabilitiesForPreset, getManagementPreset, parseManagementPreset, presetSummaryLines, } from "./management-preset.js";
36
+ import { printSelfWiringSnippet } from "./self-wiring.js";
33
37
  export { parseMcpMode } from "./shared.js";
34
38
  function parseVersion(version) {
35
39
  const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?/);
@@ -66,7 +70,7 @@ export function isVersionNewer(current, previous) {
66
70
  return c.pre > p.pre;
67
71
  }
68
72
  function normalizedBootstrapProjectName(projectPath) {
69
- return path.basename(projectPath).toLowerCase().replace(/[^a-z0-9_-]/g, "-");
73
+ return projectSlugFromPath(projectPath);
70
74
  }
71
75
  export function getPendingBootstrapTarget(phrenPath, _opts) {
72
76
  const cwdProject = detectProjectDir(process.cwd(), phrenPath);
@@ -92,7 +96,12 @@ function hasInstallMarkers(phrenPath) {
92
96
  return found >= 2;
93
97
  }
94
98
  function resolveInitPhrenPath(opts) {
95
- const raw = opts._walkthroughStoragePath || (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
99
+ // Resolve the default store path live (homePath reads HOME at call time) rather
100
+ // than via the import-frozen DEFAULT_PHREN_PATH const. The const is captured at
101
+ // module load, so any caller that changes HOME afterward — notably test suites
102
+ // that point HOME at a temp dir in beforeEach — would otherwise resolve to the
103
+ // real ~/.phren and mutate the developer's live install.
104
+ const raw = opts._walkthroughStoragePath || (process.env.PHREN_PATH) || homePath(".phren");
96
105
  return path.resolve(expandHomePath(raw));
97
106
  }
98
107
  export async function runInit(opts = {}) {
@@ -102,6 +111,10 @@ export async function runInit(opts = {}) {
102
111
  }
103
112
  let phrenPath = resolveInitPhrenPath(opts);
104
113
  const dryRun = Boolean(opts.dryRun);
114
+ // Capture whether ownership/preset came from an explicit CLI flag BEFORE the
115
+ // walkthrough merges its own answers into opts — needed to decide whether an
116
+ // assisted/manual preset may override a fast-path (express/clone) ownership.
117
+ const cliOwnershipExplicit = opts.projectOwnershipDefault !== undefined;
105
118
  if (!dryRun) {
106
119
  assertNoGlobalWiringConflict(phrenPath, Boolean(opts.force));
107
120
  }
@@ -158,6 +171,7 @@ export async function runInit(opts = {}) {
158
171
  opts.mcp = opts.mcp || answers.mcp;
159
172
  opts.hooks = opts.hooks || answers.hooks;
160
173
  opts.projectOwnershipDefault = opts.projectOwnershipDefault || answers.projectOwnershipDefault;
174
+ opts.managementPreset = opts.managementPreset || answers.managementPreset;
161
175
  opts.findingsProactivity = opts.findingsProactivity || answers.findingsProactivity;
162
176
  opts.taskProactivity = opts.taskProactivity || answers.taskProactivity;
163
177
  if (typeof opts.lowConfidenceThreshold !== "number")
@@ -227,13 +241,29 @@ export async function runInit(opts = {}) {
227
241
  // On re-runs of existing installs, preserve the existing syncIntent unless the user provided a new clone URL.
228
242
  const existingSyncIntent = hasExistingInstall ? readInstallPreferences(phrenPath).syncIntent : undefined;
229
243
  const syncIntent = opts._walkthroughCloneUrl ? "sync" : (existingSyncIntent ?? "local");
244
+ // Resolve the management preset for this run: explicit flag/walkthrough answer,
245
+ // else the stored preset on existing installs, else the default (managed).
246
+ const managementPreset = parseManagementPreset(opts.managementPreset)
247
+ ?? (hasExistingInstall ? getManagementPreset(phrenPath) : DEFAULT_MANAGEMENT_PRESET);
248
+ const managementCaps = capabilitiesForPreset(phrenPath, managementPreset);
230
249
  const mcpEnabled = opts.mcp ? opts.mcp === "on" : getMcpEnabledPreference(phrenPath);
231
- const hooksEnabled = opts.hooks ? opts.hooks === "on" : getHooksEnabledPreference(phrenPath);
250
+ // Under presets whose hooksDefault is false (manual), hooks stay off unless the
251
+ // user explicitly passed --hooks on. Otherwise fall back to the stored preference.
252
+ const hooksEnabled = opts.hooks
253
+ ? opts.hooks === "on"
254
+ : managementCaps.hooksDefault && getHooksEnabledPreference(phrenPath);
232
255
  const skillsScope = opts.skillsScope ?? "global";
233
256
  const storageChoice = opts._walkthroughStorageChoice;
234
257
  const storageRepoRoot = opts._walkthroughStorageRepoRoot;
235
- const ownershipDefault = opts.projectOwnershipDefault
258
+ let ownershipDefault = opts.projectOwnershipDefault
236
259
  ?? (hasExistingInstall ? getProjectOwnershipDefault(phrenPath) : "detached");
260
+ // Assisted/manual presets never write into project repos, so fresh installs
261
+ // default to detached ownership — overriding even the express/clone fast-paths,
262
+ // unless the user explicitly set --project-ownership.
263
+ if (managementCaps.ownershipForcedDetached && !cliOwnershipExplicit && ownershipDefault !== "detached") {
264
+ ownershipDefault = "detached";
265
+ opts.projectOwnershipDefault = "detached";
266
+ }
237
267
  if (!hasExistingInstall && !opts.projectOwnershipDefault) {
238
268
  opts.projectOwnershipDefault = ownershipDefault;
239
269
  }
@@ -339,19 +369,23 @@ export async function runInit(opts = {}) {
339
369
  syncMode: "managed-git",
340
370
  });
341
371
  ensureGovernanceFiles(phrenPath);
342
- const repaired = repairPreexistingInstall(phrenPath);
372
+ // Persist the preset before repair so the every-session self-heal and any
373
+ // caps resolution see the intended value.
374
+ setManagementPresetPreference(phrenPath, managementPreset);
375
+ const repaired = repairPreexistingInstall(phrenPath, { caps: managementCaps, preset: managementPreset });
343
376
  applyOnboardingPreferences(phrenPath, opts);
344
377
  const existingGitRepo = ensureLocalGitRepo(phrenPath);
345
378
  log(`\nphren already exists at ${phrenPath}`);
346
379
  log(`Updating configuration...\n`);
380
+ log(` Management preset: ${managementPreset} — ${presetSummaryLines(managementPreset)}`);
347
381
  log(` MCP mode: ${mcpLabel}`);
348
382
  log(` Hooks mode: ${hooksLabel}`);
349
383
  log(` Default project ownership: ${ownershipDefault}`);
350
384
  log(` Task mode: ${getWorkflowPolicy(phrenPath).taskMode}`);
351
385
  log(` Git repo: ${existingGitRepo.detail}`);
352
386
  // Always reconfigure MCP and hooks (picks up new features on upgrade)
353
- configureMcpTargets(phrenPath, { mcpEnabled, hooksEnabled }, "Updated");
354
- configureHooksIfEnabled(phrenPath, hooksEnabled, "Updated");
387
+ configureMcpTargets(phrenPath, { mcpEnabled, hooksEnabled, caps: managementCaps }, "Updated");
388
+ configureHooksIfEnabled(phrenPath, hooksEnabled, "Updated", managementCaps);
355
389
  const prefs = readInstallPreferences(phrenPath);
356
390
  const previousVersion = prefs.installedVersion;
357
391
  if (isVersionNewer(VERSION, previousVersion)) {
@@ -393,9 +427,15 @@ export async function runInit(opts = {}) {
393
427
  debugLog(`Bootstrap from CWD failed: ${e instanceof Error ? e.message : String(e)}`);
394
428
  }
395
429
  }
396
- for (const envLabel of writeWalkthroughEnvDefaults(phrenPath, opts)) {
430
+ for (const envLabel of writeWalkthroughEnvDefaults(phrenPath, opts, {
431
+ preset: managementPreset,
432
+ explicit: Boolean(opts.managementPreset),
433
+ })) {
397
434
  log(` ${envLabel}`);
398
435
  }
436
+ if (managementPreset !== "managed") {
437
+ printSelfWiringSnippet(phrenPath, managementPreset);
438
+ }
399
439
  log(`\n\x1b[95m◆\x1b[0m phren updated successfully`);
400
440
  log(`\nNext steps:`);
401
441
  log(` 1. Start a new Claude session in your project directory — phren injects context automatically`);
@@ -428,13 +468,17 @@ export async function runInit(opts = {}) {
428
468
  const useTemplateProject = Boolean(walkthroughProject) || Boolean(opts.template);
429
469
  const firstProjectName = walkthroughProject || "my-first-project";
430
470
  const firstProjectDomain = opts._walkthroughDomain ?? "software";
431
- // Copy bundled starter to ~/.phren
471
+ // Copy bundled starter to ~/.phren.
472
+ //
473
+ // Note: packages/cli/starter/ no longer ships my-api/my-frontend/
474
+ // my-first-project sample-project directories — they were bundled but
475
+ // never copied (this loop used to skip them by name) and ensureProjectScaffold()
476
+ // below generates the real first-project content instead. Those three names
477
+ // still appear in LEGACY_SAMPLE_PROJECTS (init/setup.ts) purely to prune them
478
+ // out of profiles left behind by installs that predate this cleanup.
432
479
  function copyDir(src, dest) {
433
480
  fs.mkdirSync(dest, { recursive: true });
434
481
  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
435
- if (src === STARTER_DIR && entry.isDirectory() && ["my-api", "my-frontend", "my-first-project"].includes(entry.name)) {
436
- continue;
437
- }
438
482
  const srcPath = path.join(src, entry.name);
439
483
  const destPath = path.join(dest, entry.name);
440
484
  if (entry.isDirectory()) {
@@ -515,10 +559,12 @@ export async function runInit(opts = {}) {
515
559
  persistMachineName(effectiveMachine);
516
560
  updateMachinesYaml(phrenPath, effectiveMachine, opts.profile);
517
561
  ensureGovernanceFiles(phrenPath);
518
- const repaired = repairPreexistingInstall(phrenPath);
562
+ setManagementPresetPreference(phrenPath, managementPreset);
563
+ const repaired = repairPreexistingInstall(phrenPath, { caps: managementCaps, preset: managementPreset });
519
564
  applyOnboardingPreferences(phrenPath, opts);
520
565
  const localGitRepo = ensureLocalGitRepo(phrenPath);
521
566
  log(` Updated machines.yaml with machine "${effectiveMachine}"`);
567
+ log(` Management preset: ${managementPreset} — ${presetSummaryLines(managementPreset)}`);
522
568
  log(` MCP mode: ${mcpLabel}`);
523
569
  log(` Hooks mode: ${hooksLabel}`);
524
570
  log(` Default project ownership: ${ownershipDefault}`);
@@ -532,8 +578,8 @@ export async function runInit(opts = {}) {
532
578
  log(` Recreated missing generated assets: ${repairedAssets.join(", ")}`);
533
579
  }
534
580
  // Configure MCP for all detected AI coding tools and hooks
535
- configureMcpTargets(phrenPath, { mcpEnabled, hooksEnabled }, "Configured");
536
- configureHooksIfEnabled(phrenPath, hooksEnabled, "Configured");
581
+ configureMcpTargets(phrenPath, { mcpEnabled, hooksEnabled, caps: managementCaps }, "Configured");
582
+ configureHooksIfEnabled(phrenPath, hooksEnabled, "Configured", managementCaps);
537
583
  writeInstallPreferences(phrenPath, { mcpEnabled, hooksEnabled, skillsScope, installedVersion: VERSION, syncIntent });
538
584
  // Post-init verification
539
585
  log(`\nVerifying setup...`);
@@ -569,9 +615,15 @@ export async function runInit(opts = {}) {
569
615
  logger.debug("init", `init ollamaInstallHint: ${errorMessage(err)}`);
570
616
  }
571
617
  }
572
- for (const envLabel of writeWalkthroughEnvDefaults(phrenPath, opts)) {
618
+ for (const envLabel of writeWalkthroughEnvDefaults(phrenPath, opts, {
619
+ preset: managementPreset,
620
+ explicit: Boolean(opts.managementPreset),
621
+ })) {
573
622
  log(` ${envLabel}`);
574
623
  }
624
+ if (managementPreset !== "managed") {
625
+ printSelfWiringSnippet(phrenPath, managementPreset);
626
+ }
575
627
  if (opts._walkthroughSemanticSearch) {
576
628
  log(`\nWarming semantic search...`);
577
629
  try {
@@ -0,0 +1,42 @@
1
+ export type ManagementPreset = "managed" | "assisted" | "manual";
2
+ export declare const MANAGEMENT_PRESETS: readonly ManagementPreset[];
3
+ export declare const DEFAULT_MANAGEMENT_PRESET: ManagementPreset;
4
+ /** Structural + behavioral capabilities a preset expands into. */
5
+ export interface ManagementCapabilities {
6
+ /** Symlink global/CLAUDE.md into ~/.claude/CLAUDE.md (+ copilot instructions). */
7
+ linkGlobalClaudeMd: boolean;
8
+ /** Symlink managed skills into ~/.claude/skills (+ other agent skill dirs). */
9
+ installSkillLinks: boolean;
10
+ /** Install ~/.local/bin/{phren,copilot,cursor,codex} wrappers. */
11
+ installWrappers: boolean;
12
+ /** Re-create home symlinks/skills every SessionStart. */
13
+ selfHeal: boolean;
14
+ /** Mirror phren docs/skills into phren-managed project repos (still ownership-gated). */
15
+ repoMirroring: boolean;
16
+ /** Daily maintenance + Stop auto-commit/push of the store. */
17
+ lifecycleAutomations: boolean;
18
+ /** Whether lifecycle hooks are installed/active by default under this preset. */
19
+ hooksDefault: boolean;
20
+ /** Whether fresh-install project ownership is forced to "detached". */
21
+ ownershipForcedDetached: boolean;
22
+ }
23
+ /** Parse a user-supplied preset name; undefined for invalid/empty input. */
24
+ export declare function parseManagementPreset(value?: string | null): ManagementPreset | undefined;
25
+ /** The capability bundle for a preset (no per-user overrides applied). */
26
+ export declare function presetCapabilities(preset: ManagementPreset): ManagementCapabilities;
27
+ /** Current preset from install preferences; absent → managed. */
28
+ export declare function getManagementPreset(phrenPath: string): ManagementPreset;
29
+ /**
30
+ * Capabilities for a given preset overlaid with any explicit per-capability
31
+ * booleans already present in install-preferences.json. Use this when applying
32
+ * a preset (e.g. during init) that may not yet be persisted, so the caller can
33
+ * pass the intended preset while still honoring existing power-user overrides.
34
+ */
35
+ export declare function capabilitiesForPreset(phrenPath: string, preset: ManagementPreset): ManagementCapabilities;
36
+ /**
37
+ * Resolve effective capabilities: the persisted preset bundle overlaid with
38
+ * any explicit per-capability booleans set in install-preferences.json.
39
+ */
40
+ export declare function resolveManagementCapabilities(phrenPath: string): ManagementCapabilities;
41
+ /** One-line human descriptions per preset, reused by the walkthrough + status. */
42
+ export declare function presetSummaryLines(preset: ManagementPreset): string;
@@ -0,0 +1,122 @@
1
+ /**
2
+ * Management presets: how much of the user's machine phren wires up.
3
+ *
4
+ * Phren's flagship experience actively manages symlinks, skills, hooks and
5
+ * lifecycle automations. Not everyone wants that. A named preset lets a user
6
+ * dial the footprint down without hunting through scattered env flags:
7
+ *
8
+ * - managed (default): the historical behavior — MCP + hooks + home
9
+ * symlinks (~/.claude/CLAUDE.md, ~/.claude/skills), CLI/session
10
+ * wrappers, repo mirroring (still ownership-gated), lifecycle
11
+ * automations, and SessionStart self-heal of the above.
12
+ * - assisted: MCP + hooks (context injection, capture, store git sync) but
13
+ * phren writes NOTHING outside its own store and agent settings —
14
+ * no CLAUDE.md symlink, no skills symlinks, no ~/.local/bin
15
+ * wrappers, no self-heal. Project ownership defaults to detached.
16
+ * Init prints a self-wiring snippet so users wire their own files.
17
+ * - manual: MCP server registration only. No hooks, no automations, no
18
+ * daily maintenance, no auto commit/push. A pull-based knowledge
19
+ * base the agent must choose to call.
20
+ *
21
+ * Presets are thin bundles over mostly-existing toggles. Individual capability
22
+ * overrides in install-preferences.json win over the preset bundle, so a power
23
+ * user can, e.g., run "assisted" but re-enable selfHeal. Precedence, strongest
24
+ * first:
25
+ * 1. PHREN_FEATURE_* env / ~/.phren/.env flags (runtime, for the automations
26
+ * they already gate — this module does not duplicate them).
27
+ * 2. Explicit per-capability boolean in install-preferences.json.
28
+ * 3. Preset bundle default (this file).
29
+ * 4. Built-in managed defaults (preset absent).
30
+ */
31
+ import { readInstallPreferences } from "./preferences.js";
32
+ export const MANAGEMENT_PRESETS = ["managed", "assisted", "manual"];
33
+ export const DEFAULT_MANAGEMENT_PRESET = "managed";
34
+ const PRESET_CAPABILITIES = {
35
+ managed: {
36
+ linkGlobalClaudeMd: true,
37
+ installSkillLinks: true,
38
+ installWrappers: true,
39
+ selfHeal: true,
40
+ repoMirroring: true,
41
+ lifecycleAutomations: true,
42
+ hooksDefault: true,
43
+ ownershipForcedDetached: false,
44
+ },
45
+ assisted: {
46
+ linkGlobalClaudeMd: false,
47
+ installSkillLinks: false,
48
+ installWrappers: false,
49
+ selfHeal: false,
50
+ repoMirroring: false,
51
+ lifecycleAutomations: true,
52
+ hooksDefault: true,
53
+ ownershipForcedDetached: true,
54
+ },
55
+ manual: {
56
+ linkGlobalClaudeMd: false,
57
+ installSkillLinks: false,
58
+ installWrappers: false,
59
+ selfHeal: false,
60
+ repoMirroring: false,
61
+ lifecycleAutomations: false,
62
+ hooksDefault: false,
63
+ ownershipForcedDetached: true,
64
+ },
65
+ };
66
+ /** Parse a user-supplied preset name; undefined for invalid/empty input. */
67
+ export function parseManagementPreset(value) {
68
+ const normalized = value?.trim().toLowerCase();
69
+ if (!normalized)
70
+ return undefined;
71
+ return MANAGEMENT_PRESETS.includes(normalized)
72
+ ? normalized
73
+ : undefined;
74
+ }
75
+ /** The capability bundle for a preset (no per-user overrides applied). */
76
+ export function presetCapabilities(preset) {
77
+ return { ...PRESET_CAPABILITIES[preset] };
78
+ }
79
+ /** Current preset from install preferences; absent → managed. */
80
+ export function getManagementPreset(phrenPath) {
81
+ const prefs = readInstallPreferences(phrenPath);
82
+ return prefs.managementPreset ?? DEFAULT_MANAGEMENT_PRESET;
83
+ }
84
+ /**
85
+ * Capabilities for a given preset overlaid with any explicit per-capability
86
+ * booleans already present in install-preferences.json. Use this when applying
87
+ * a preset (e.g. during init) that may not yet be persisted, so the caller can
88
+ * pass the intended preset while still honoring existing power-user overrides.
89
+ */
90
+ export function capabilitiesForPreset(phrenPath, preset) {
91
+ const prefs = readInstallPreferences(phrenPath);
92
+ const base = presetCapabilities(preset);
93
+ const overlay = (key, value) => value === undefined ? base[key] : value;
94
+ return {
95
+ linkGlobalClaudeMd: overlay("linkGlobalClaudeMd", prefs.linkGlobalClaudeMd),
96
+ installSkillLinks: overlay("installSkillLinks", prefs.installSkillLinks),
97
+ installWrappers: overlay("installWrappers", prefs.installWrappers),
98
+ selfHeal: overlay("selfHeal", prefs.selfHeal),
99
+ repoMirroring: overlay("repoMirroring", prefs.repoMirroring),
100
+ lifecycleAutomations: overlay("lifecycleAutomations", prefs.lifecycleAutomations),
101
+ hooksDefault: base.hooksDefault,
102
+ ownershipForcedDetached: base.ownershipForcedDetached,
103
+ };
104
+ }
105
+ /**
106
+ * Resolve effective capabilities: the persisted preset bundle overlaid with
107
+ * any explicit per-capability booleans set in install-preferences.json.
108
+ */
109
+ export function resolveManagementCapabilities(phrenPath) {
110
+ return capabilitiesForPreset(phrenPath, getManagementPreset(phrenPath));
111
+ }
112
+ /** One-line human descriptions per preset, reused by the walkthrough + status. */
113
+ export function presetSummaryLines(preset) {
114
+ switch (preset) {
115
+ case "managed":
116
+ return "phren wires everything: MCP, hooks, ~/.claude symlinks, skills, self-heal (recommended)";
117
+ case "assisted":
118
+ return "MCP + hooks only — phren never writes outside its store; you wire CLAUDE.md/skills yourself";
119
+ case "manual":
120
+ return "MCP server only — pull-based knowledge base, no hooks or automations";
121
+ }
122
+ }
@@ -4,6 +4,22 @@ export interface InstallPreferences {
4
4
  hooksEnabled?: boolean;
5
5
  skillsScope?: "global" | "project";
6
6
  projectOwnershipDefault?: "phren-managed" | "detached" | "repo-managed";
7
+ /**
8
+ * Management preset controlling how much of the machine phren wires up.
9
+ * Absent → treated as "managed" (the historical, fully-managed behavior).
10
+ * See init/management-preset.ts for the capability expansion.
11
+ */
12
+ managementPreset?: "managed" | "assisted" | "manual";
13
+ /**
14
+ * Per-capability overrides. When set they win over the preset bundle
15
+ * (power-user escape hatch); when absent the preset default applies.
16
+ */
17
+ linkGlobalClaudeMd?: boolean;
18
+ installSkillLinks?: boolean;
19
+ installWrappers?: boolean;
20
+ selfHeal?: boolean;
21
+ repoMirroring?: boolean;
22
+ lifecycleAutomations?: boolean;
7
23
  proactivity?: "high" | "medium" | "low";
8
24
  proactivityFindings?: "high" | "medium" | "low";
9
25
  proactivityTask?: "high" | "medium" | "low";
@@ -34,3 +50,4 @@ export declare function getMcpEnabledPreference(phrenPath: string): boolean;
34
50
  export declare function setMcpEnabledPreference(phrenPath: string, enabled: boolean): void;
35
51
  export declare function getHooksEnabledPreference(phrenPath: string): boolean;
36
52
  export declare function setHooksEnabledPreference(phrenPath: string, enabled: boolean): void;
53
+ export declare function setManagementPresetPreference(phrenPath: string, preset: "managed" | "assisted" | "manual"): void;
@@ -75,3 +75,6 @@ export function getHooksEnabledPreference(phrenPath) {
75
75
  export function setHooksEnabledPreference(phrenPath, enabled) {
76
76
  writeInstallPreferences(phrenPath, { hooksEnabled: enabled });
77
77
  }
78
+ export function setManagementPresetPreference(phrenPath, preset) {
79
+ writeInstallPreferences(phrenPath, { managementPreset: preset });
80
+ }
@@ -0,0 +1,5 @@
1
+ import { type ManagementPreset } from "./management-preset.js";
2
+ /** Build the self-wiring instructions as lines (testable without stdout). */
3
+ export declare function buildSelfWiringSnippet(phrenPath: string, preset: ManagementPreset): string[];
4
+ /** Print the self-wiring snippet for the given (or current) preset. */
5
+ export declare function printSelfWiringSnippet(phrenPath: string, preset?: ManagementPreset): void;
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Self-wiring snippet printer for the assisted/manual presets.
3
+ *
4
+ * Under presets where phren does not symlink into ~/.claude, users who still
5
+ * want the global instructions and slash-commands wire them up themselves. This
6
+ * prints a copy-pasteable block pointing at the store's canonical files so they
7
+ * are never left guessing where phren keeps things.
8
+ */
9
+ import * as path from "path";
10
+ import { log } from "./shared.js";
11
+ import { getManagementPreset } from "./management-preset.js";
12
+ /** Build the self-wiring instructions as lines (testable without stdout). */
13
+ export function buildSelfWiringSnippet(phrenPath, preset) {
14
+ const globalClaude = path.join(phrenPath, "global", "CLAUDE.md");
15
+ const globalSkills = path.join(phrenPath, "global", "skills");
16
+ const lines = [];
17
+ lines.push("");
18
+ lines.push("─────────────────────────────────────────────────────────────");
19
+ lines.push(`Self-wiring (${preset} preset — phren does not touch ~/.claude)`);
20
+ lines.push("─────────────────────────────────────────────────────────────");
21
+ if (preset === "manual") {
22
+ lines.push("phren runs as an MCP server only. Your agent reaches phren through");
23
+ lines.push("its MCP tools — no global instructions or hooks are installed.");
24
+ lines.push("");
25
+ lines.push("Optional — surface the global guidance to your agent yourself, e.g.");
26
+ lines.push("add a line to your own ~/.claude/CLAUDE.md:");
27
+ lines.push(` @${globalClaude}`);
28
+ return lines;
29
+ }
30
+ // assisted
31
+ lines.push("Hooks + MCP are active, but phren never writes outside its store.");
32
+ lines.push("To load the global instructions in every session, reference them");
33
+ lines.push("from your own ~/.claude/CLAUDE.md (phren won't overwrite your file):");
34
+ lines.push(` @${globalClaude}`);
35
+ lines.push("");
36
+ lines.push(" …or symlink it yourself if you prefer:");
37
+ lines.push(` ln -s ${globalClaude} ~/.claude/CLAUDE.md`);
38
+ lines.push("");
39
+ lines.push("Phren slash-commands live in:");
40
+ lines.push(` ${globalSkills}`);
41
+ lines.push(" Copy or symlink the ones you want into ~/.claude/skills/, e.g.:");
42
+ lines.push(` ln -s ${path.join(globalSkills, "phren-sync")} ~/.claude/skills/phren-sync`);
43
+ lines.push("");
44
+ lines.push("Re-print this anytime with: phren snippet");
45
+ return lines;
46
+ }
47
+ /** Print the self-wiring snippet for the given (or current) preset. */
48
+ export function printSelfWiringSnippet(phrenPath, preset) {
49
+ const resolved = preset ?? getManagementPreset(phrenPath);
50
+ for (const line of buildSelfWiringSnippet(phrenPath, resolved))
51
+ log(line);
52
+ }
@@ -3,6 +3,7 @@
3
3
  */
4
4
  import * as fs from "fs";
5
5
  import { commandVersion } from "./shared.js";
6
+ import { type ManagementCapabilities, type ManagementPreset } from "./management-preset.js";
6
7
  import { type ProjectOwnershipMode } from "../project-config.js";
7
8
  import { type BuiltinTopic } from "../project-topics.js";
8
9
  export interface PostInitCheck {
@@ -41,7 +42,10 @@ interface RepairInstallResult {
41
42
  }
42
43
  export declare function ensureGitignoreEntry(repoRoot: string, entry: string): boolean;
43
44
  export declare function upsertProjectEnvVar(repoRoot: string, key: string, value: string): boolean;
44
- export declare function repairPreexistingInstall(phrenPath: string): RepairInstallResult;
45
+ export declare function repairPreexistingInstall(phrenPath: string, opts?: {
46
+ caps?: ManagementCapabilities;
47
+ preset?: ManagementPreset;
48
+ }): RepairInstallResult;
45
49
  export declare function getVerifyOutcomeNote(phrenPath: string, checks: PostInitCheck[]): string | null;
46
50
  interface HookEntrypointCheckDeps {
47
51
  pathExists?: typeof fs.existsSync;
@@ -63,9 +67,6 @@ export interface InferredInitScaffold {
63
67
  export declare function inferInitScaffoldFromRepo(repoRoot: string, fallbackDomain?: InitProjectDomain): InferredInitScaffold | null;
64
68
  export declare function ensureProjectScaffold(projectDir: string, projectName: string, domain?: InitProjectDomain, inference?: InferredInitScaffold | null): void;
65
69
  export declare function ensureLocalGitRepo(phrenPath: string): LocalGitRepoStatus;
66
- /** Bootstrap a phren project from an existing project directory with CLAUDE.md.
67
- * @param profile - if provided, only this profile YAML is updated (avoids leaking project to unrelated profiles).
68
- */
69
70
  export declare function bootstrapFromExisting(phrenPath: string, projectPath: string, opts?: string | BootstrapProjectOptions): BootstrapProjectResult;
70
71
  export declare function updateMachinesYaml(phrenPath: string, machine?: string, profile?: string): void;
71
72
  /**
@@ -74,6 +75,10 @@ export declare function updateMachinesYaml(phrenPath: string, machine?: string,
74
75
  * A directory qualifies if it:
75
76
  * - Is not the home directory or phren directory
76
77
  * - Has a CLAUDE.md, AGENTS.md, .claude/CLAUDE.md, or .git directory
78
+ *
79
+ * A git worktree resolves to the repository it belongs to. Without this a
80
+ * throwaway agent worktree under `.claude/worktrees/<codename>` looks like its
81
+ * own repo (it has a `.git` entry) and gets offered as a new project.
77
82
  */
78
83
  export declare function detectProjectDir(dir: string, phrenPath: string): string | null;
79
84
  /**