@phren/cli 0.1.39 → 0.1.40

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.
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, 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+)(?:-(.+))?/);
@@ -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`);
@@ -515,10 +555,12 @@ export async function runInit(opts = {}) {
515
555
  persistMachineName(effectiveMachine);
516
556
  updateMachinesYaml(phrenPath, effectiveMachine, opts.profile);
517
557
  ensureGovernanceFiles(phrenPath);
518
- const repaired = repairPreexistingInstall(phrenPath);
558
+ setManagementPresetPreference(phrenPath, managementPreset);
559
+ const repaired = repairPreexistingInstall(phrenPath, { caps: managementCaps, preset: managementPreset });
519
560
  applyOnboardingPreferences(phrenPath, opts);
520
561
  const localGitRepo = ensureLocalGitRepo(phrenPath);
521
562
  log(` Updated machines.yaml with machine "${effectiveMachine}"`);
563
+ log(` Management preset: ${managementPreset} — ${presetSummaryLines(managementPreset)}`);
522
564
  log(` MCP mode: ${mcpLabel}`);
523
565
  log(` Hooks mode: ${hooksLabel}`);
524
566
  log(` Default project ownership: ${ownershipDefault}`);
@@ -532,8 +574,8 @@ export async function runInit(opts = {}) {
532
574
  log(` Recreated missing generated assets: ${repairedAssets.join(", ")}`);
533
575
  }
534
576
  // Configure MCP for all detected AI coding tools and hooks
535
- configureMcpTargets(phrenPath, { mcpEnabled, hooksEnabled }, "Configured");
536
- configureHooksIfEnabled(phrenPath, hooksEnabled, "Configured");
577
+ configureMcpTargets(phrenPath, { mcpEnabled, hooksEnabled, caps: managementCaps }, "Configured");
578
+ configureHooksIfEnabled(phrenPath, hooksEnabled, "Configured", managementCaps);
537
579
  writeInstallPreferences(phrenPath, { mcpEnabled, hooksEnabled, skillsScope, installedVersion: VERSION, syncIntent });
538
580
  // Post-init verification
539
581
  log(`\nVerifying setup...`);
@@ -569,9 +611,15 @@ export async function runInit(opts = {}) {
569
611
  logger.debug("init", `init ollamaInstallHint: ${errorMessage(err)}`);
570
612
  }
571
613
  }
572
- for (const envLabel of writeWalkthroughEnvDefaults(phrenPath, opts)) {
614
+ for (const envLabel of writeWalkthroughEnvDefaults(phrenPath, opts, {
615
+ preset: managementPreset,
616
+ explicit: Boolean(opts.managementPreset),
617
+ })) {
573
618
  log(` ${envLabel}`);
574
619
  }
620
+ if (managementPreset !== "managed") {
621
+ printSelfWiringSnippet(phrenPath, managementPreset);
622
+ }
575
623
  if (opts._walkthroughSemanticSearch) {
576
624
  log(`\nWarming semantic search...`);
577
625
  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;
@@ -14,6 +14,7 @@ import { GOVERNANCE_SCHEMA_VERSION, } from "../shared/governance.js";
14
14
  import { STOP_WORDS, errorMessage } from "../utils.js";
15
15
  import { ROOT, STARTER_DIR, VERSION, resolveEntryScript, commandVersion, versionAtLeast, nearestWritableTarget } from "./shared.js";
16
16
  import { readInstallPreferences } from "./preferences.js";
17
+ import { getManagementPreset, resolveManagementCapabilities, } from "./management-preset.js";
17
18
  import { TASKS_FILENAME } from "../data/tasks.js";
18
19
  import { FINDINGS_FILENAME } from "../data/access.js";
19
20
  import { getProjectOwnershipDefault, parseProjectOwnershipMode, readProjectConfig, writeProjectConfig, } from "../project-config.js";
@@ -202,20 +203,22 @@ function ensureRuntimeAssets(phrenPath) {
202
203
  }
203
204
  return created;
204
205
  }
205
- function ensureDefaultFeatureFlags(phrenPath) {
206
+ function ensureDefaultFeatureFlags(phrenPath, preset) {
206
207
  const created = [];
207
208
  const envPath = path.join(phrenPath, ".env");
208
209
  const header = "# phren feature flags — generated by init\n";
209
210
  let content = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : header;
210
211
  let changed = !fs.existsSync(envPath);
211
212
  const lines = content.split("\n");
213
+ // Manual preset opts out of prompt-time auto-capture by default.
214
+ const autoCaptureDefault = preset === "manual" ? "0" : "1";
212
215
  const hasAutoCaptureFlag = lines.some((line) => line.trimStart().startsWith("PHREN_FEATURE_AUTO_CAPTURE="));
213
216
  if (!hasAutoCaptureFlag) {
214
217
  if (!content.endsWith("\n"))
215
218
  content += "\n";
216
- content += "PHREN_FEATURE_AUTO_CAPTURE=1\n";
219
+ content += `PHREN_FEATURE_AUTO_CAPTURE=${autoCaptureDefault}\n`;
217
220
  changed = true;
218
- created.push(".env:PHREN_FEATURE_AUTO_CAPTURE=1");
221
+ created.push(`.env:PHREN_FEATURE_AUTO_CAPTURE=${autoCaptureDefault}`);
219
222
  }
220
223
  if (changed) {
221
224
  atomicWriteText(envPath, content);
@@ -301,15 +304,24 @@ export function upsertProjectEnvVar(repoRoot, key, value) {
301
304
  atomicWriteText(envPath, content);
302
305
  return true;
303
306
  }
304
- export function repairPreexistingInstall(phrenPath) {
307
+ export function repairPreexistingInstall(phrenPath, opts) {
308
+ // Resolve the effective management capabilities. Callers that are applying a
309
+ // not-yet-persisted preset (e.g. init) pass caps explicitly; the every-session
310
+ // self-heal path resolves from stored preferences.
311
+ const caps = opts?.caps ?? resolveManagementCapabilities(phrenPath);
312
+ const preset = opts?.preset ?? getManagementPreset(phrenPath);
305
313
  const createdGovernanceAssets = ensureGovernanceFiles(phrenPath);
306
314
  const createdGlobalAssets = ensureGlobalStarterAssets(phrenPath);
307
315
  const createdRuntimeAssets = [...createdGovernanceAssets, ...ensureRuntimeAssets(phrenPath)];
308
- const createdFeatureDefaults = ensureDefaultFeatureFlags(phrenPath);
316
+ const createdFeatureDefaults = ensureDefaultFeatureFlags(phrenPath, preset);
309
317
  const profileRepair = pruneLegacySampleProjectsFromProfiles(phrenPath);
310
318
  const preferredHome = resolvePreferredHomeDir(phrenPath);
311
- const createdSkillArtifacts = ensureGeneratedSkillArtifacts(phrenPath, preferredHome);
312
- const repairedGlobalSymlink = repairGlobalClaudeSymlink(phrenPath);
319
+ // Structural surfaces (home skills symlinks + ~/.claude/CLAUDE.md) are only
320
+ // created/self-healed under presets that opt into them.
321
+ const createdSkillArtifacts = caps.installSkillLinks
322
+ ? ensureGeneratedSkillArtifacts(phrenPath, preferredHome)
323
+ : [];
324
+ const repairedGlobalSymlink = caps.linkGlobalClaudeMd ? repairGlobalClaudeSymlink(phrenPath) : false;
313
325
  return {
314
326
  profileFilesUpdated: profileRepair.filesUpdated,
315
327
  removedLegacyProjects: profileRepair.removed,
@@ -0,0 +1,15 @@
1
+ /** Remove the phren-owned ~/.claude/CLAUDE.md and copilot-instructions.md symlinks. */
2
+ export declare function removePhrenHomeSymlinks(): string[];
3
+ /** Remove ~/.local/bin/{copilot,cursor,codex,phren} wrappers that carry the phren marker. */
4
+ export declare function removePhrenWrappers(): string[];
5
+ /** Remove skill symlinks in agent skill dirs that resolve into the phren store, plus manifests. */
6
+ export declare function sweepAgentSkillSymlinks(phrenPath: string): void;
7
+ /** Remove the given exclude entries (and the phren-managed marker) from a repo's .git/info/exclude. */
8
+ export declare function removeGitExcludes(projectDir: string, entries: string[]): void;
9
+ /**
10
+ * Remove per-project repo mirror symlinks (CLAUDE.md, REFERENCE.md, findings,
11
+ * AGENTS.md, CLAUDE-*.md, .github/copilot-instructions.md, .claude/skills/*) that
12
+ * phren created in phren-managed repos, and strip the matching exclude lines.
13
+ * Only removes symlinks that resolve back into the phren store.
14
+ */
15
+ export declare function sweepProjectMirrors(phrenPath: string): void;