@phren/cli 0.0.56 → 0.0.58

package/dist/governance/policy.d.ts

@@ -0,0 +1,109 @@
+import { type PhrenResult } from "../shared.js";
+import { type ProjectConfigOverrides } from "../project-config.js";
+/** @internal Exported for tests. */
+export declare const MAX_QUEUE_ENTRY_LENGTH = 500;
+export interface RetentionPolicy {
+    schemaVersion?: number;
+    ttlDays: number;
+    retentionDays: number;
+    autoAcceptThreshold: number;
+    minInjectConfidence: number;
+    decay: {
+        d30: number;
+        d60: number;
+        d90: number;
+        d120: number;
+    };
+}
+export interface WorkflowPolicy {
+    schemaVersion?: number;
+    lowConfidenceThreshold: number;
+    riskySections: Array<"Review" | "Stale" | "Conflicts">;
+    taskMode: "off" | "manual" | "suggest" | "auto";
+    findingSensitivity: "minimal" | "conservative" | "balanced" | "aggressive";
+}
+export interface IndexPolicy {
+    schemaVersion?: number;
+    includeGlobs: string[];
+    excludeGlobs: string[];
+    includeHidden: boolean;
+}
+export interface RuntimeHealth {
+    schemaVersion?: number;
+    lastSessionStartAt?: string;
+    lastPromptAt?: string;
+    lastStopAt?: string;
+    lastAutoSave?: {
+        at: string;
+        status: "clean" | "saved-local" | "saved-pushed" | "no-upstream" | "error";
+        detail?: string;
+    };
+    lastGovernance?: {
+        at: string;
+        status: "ok" | "error";
+        detail: string;
+    };
+    lastSync?: {
+        lastPullAt?: string;
+        lastPullStatus?: "ok" | "error";
+        lastPullDetail?: string;
+        lastSuccessfulPullAt?: string;
+        lastPushAt?: string;
+        lastPushStatus?: "saved-local" | "saved-pushed" | "no-upstream" | "error";
+        lastPushDetail?: string;
+        unsyncedCommits?: number;
+    };
+}
+export type SyncStatus = NonNullable<RuntimeHealth["lastSync"]>;
+export interface BuildSyncStatusOpts {
+    now: string;
+    pushStatus: SyncStatus["lastPushStatus"];
+    pushDetail?: string;
+    pullAt?: string;
+    pullStatus?: SyncStatus["lastPullStatus"];
+    pullDetail?: string;
+    successfulPullAt?: string;
+    unsyncedCommits?: number;
+}
+export declare function buildSyncStatus(opts: BuildSyncStatusOpts): SyncStatus;
+export type RetentionPolicyPatch = Partial<Omit<RetentionPolicy, "decay">> & {
+    decay?: Partial<RetentionPolicy["decay"]>;
+};
+export declare const GOVERNANCE_SCHEMA_VERSION = 1;
+type GovernanceSchema = "retention-policy" | "workflow-policy" | "index-policy";
+export declare function validateGovernanceJson(filePath: string, schema: GovernanceSchema): boolean;
+export interface ResolvedConfig {
+    findingSensitivity: WorkflowPolicy["findingSensitivity"];
+    proactivity: {
+        base?: "high" | "medium" | "low";
+        findings?: "high" | "medium" | "low";
+        tasks?: "high" | "medium" | "low";
+    };
+    taskMode: WorkflowPolicy["taskMode"];
+    retentionPolicy: RetentionPolicy;
+    workflowPolicy: WorkflowPolicy;
+}
+export declare const VALID_TASK_MODES: readonly ["off", "manual", "suggest", "auto"];
+export type TaskMode = typeof VALID_TASK_MODES[number];
+export declare const VALID_FINDING_SENSITIVITY: readonly ["minimal", "conservative", "balanced", "aggressive"];
+export type FindingSensitivityLevel = typeof VALID_FINDING_SENSITIVITY[number];
+export declare function getProjectConfigOverrides(phrenPath: string, projectName: string): ProjectConfigOverrides | null;
+export declare function mergeConfig(phrenPath: string, projectName?: string, profile?: string): ResolvedConfig;
+export declare function getRetentionPolicy(phrenPath: string, projectName?: string): RetentionPolicy;
+export declare function updateRetentionPolicy(phrenPath: string, patch: RetentionPolicyPatch): PhrenResult<RetentionPolicy>;
+export declare function getWorkflowPolicy(phrenPath: string, projectName?: string): WorkflowPolicy;
+export declare function updateWorkflowPolicy(phrenPath: string, patch: Partial<WorkflowPolicy>): PhrenResult<WorkflowPolicy>;
+export declare function getIndexPolicy(phrenPath: string): IndexPolicy;
+export declare function updateIndexPolicy(phrenPath: string, patch: Partial<IndexPolicy>): PhrenResult<IndexPolicy>;
+export declare function getRuntimeHealth(phrenPath: string): RuntimeHealth;
+export declare function updateRuntimeHealth(phrenPath: string, patch: Partial<RuntimeHealth>): RuntimeHealth;
+export declare function normalizeQueueEntryText(raw: string, opts?: {
+    truncate?: boolean;
+}): PhrenResult<{
+    text: string;
+    truncated: boolean;
+}>;
+export declare function appendReviewQueue(phrenPath: string, project: string, section: "Review" | "Stale" | "Conflicts", entries: string[]): PhrenResult<number>;
+export declare function pruneDeadMemories(phrenPath: string, project?: string, dryRun?: boolean): PhrenResult<string>;
+export declare function consolidateProjectFindings(phrenPath: string, project: string, dryRun?: boolean): PhrenResult<string>;
+export {};

package/dist/governance/rbac.d.ts

@@ -0,0 +1,25 @@
+/**
+ * RBAC enforcement for mutating MCP tools.
+ *
+ * Access-control.json lives at `<phrenPath>/.config/access-control.json` (global).
+ * Per-project overrides live in `phren.project.yaml` under the `access` key.
+ *
+ * Schema:
+ *   { admins: string[], contributors: string[], readers: string[] }
+ *
+ * Role hierarchy:
+ *   admins       → all actions
+ *   contributors → add/edit/remove findings, complete/add/remove tasks
+ *   readers      → read-only (search, get)
+ *
+ * When no access-control.json exists, all actors are permitted (open mode).
+ *
+ * The actor is read from the PHREN_ACTOR env var (falls back to open if unset).
+ */
+type RbacAction = "add_finding" | "remove_finding" | "edit_finding" | "complete_task" | "add_task" | "remove_task" | "update_task" | "manage_config";
+/**
+ * Convenience wrapper: returns a permission-denied MCP error string,
+ * or null if the action is allowed.
+ */
+export declare function permissionDeniedError(phrenPath: string, action: RbacAction, project?: string | null): string | null;
+export {};

package/dist/governance/scores.d.ts

@@ -0,0 +1,12 @@
+export interface EntryScore {
+    impressions: number;
+    helpful: number;
+    repromptPenalty: number;
+    regressionPenalty: number;
+    lastUsedAt: string;
+}
+export declare function flushEntryScores(phrenPath: string): void;
+export declare function entryScoreKey(project: string, filename: string, snippet: string): string;
+export declare function recordInjection(phrenPath: string, key: string, sessionId?: string): void;
+export declare function recordFeedback(phrenPath: string, key: string, feedback: "helpful" | "reprompt" | "regression", sessionId?: string): void;
+export declare function getQualityMultiplier(phrenPath: string, key: string): number;

package/dist/hooks.d.ts

@@ -0,0 +1,59 @@
+import { type PhrenErrorCode } from "./shared.js";
+export interface HookError {
+    code: PhrenErrorCode;
+    message: string;
+}
+export declare function commandExists(cmd: string): boolean;
+export declare function detectInstalledTools(): Set<string>;
+/** Shell-escape a value by wrapping in single quotes with proper escaping of embedded single quotes. */
+export declare function shellEscape(s: string): string;
+export interface LifecycleCommands {
+    sessionStart: string;
+    userPromptSubmit: string;
+    stop: string;
+    hookTool: string;
+}
+export declare function buildLifecycleCommands(phrenPath: string): LifecycleCommands;
+export declare function buildSharedLifecycleCommands(): LifecycleCommands;
+/**
+ * Install a lightweight `phren` CLI wrapper at ~/.local/bin/phren so the bare
+ * `phren` command works without a global npm install. The wrapper simply execs
+ * `node <entry_script> "$@"`.
+ */
+export declare function installPhrenCliWrapper(phrenPath: string): boolean;
+export interface HookToolPreferences {
+    claude?: boolean;
+    copilot?: boolean;
+    cursor?: boolean;
+    codex?: boolean;
+}
+export declare function clearHookPrefsCache(): void;
+export declare function isToolHookEnabled(phrenPath: string, tool: string): boolean;
+export type CustomHookEvent = "pre-save" | "post-save" | "post-search" | "pre-finding" | "post-finding" | "pre-index" | "post-index" | "post-session-end" | "post-consolidate";
+export interface CommandHookEntry {
+    event: CustomHookEvent;
+    command: string;
+    timeout?: number;
+}
+export interface WebhookHookEntry {
+    event: CustomHookEvent;
+    webhook: string;
+    secret?: string;
+    timeout?: number;
+}
+export type CustomHookEntry = CommandHookEntry | WebhookHookEntry;
+export declare const HOOK_EVENT_VALUES: readonly ["pre-save", "post-save", "post-search", "pre-finding", "post-finding", "pre-index", "post-index", "post-session-end", "post-consolidate"];
+/** Return the target (URL or shell command) for display or matching. */
+export declare function getHookTarget(h: CustomHookEntry): string;
+export declare function validateCustomHookCommand(command: string): string | null;
+export declare function validateCustomWebhookUrl(webhook: string): string | null;
+export declare function readCustomHooks(phrenPath: string): CustomHookEntry[];
+export declare function runCustomHooks(phrenPath: string, event: CustomHookEvent, env?: Record<string, string>): {
+    ran: number;
+    errors: HookError[];
+};
+export interface HookConfigOptions {
+    tools?: Set<string>;
+    allTools?: boolean;
+}
+export declare function configureAllHooks(phrenPath: string, options?: HookConfigOptions): string[];

package/dist/index-query.d.ts

@@ -0,0 +1,33 @@
+export type SqlValue = string | number | null | Uint8Array;
+export type DbRow = SqlValue[];
+export interface SqlJsDatabase {
+    run(sql: string, params?: SqlValue[]): void;
+    exec(sql: string, params?: SqlValue[]): {
+        columns: string[];
+        values: DbRow[];
+    }[];
+    export(): Uint8Array;
+    close(): void;
+}
+export interface DocRow {
+    project: string;
+    filename: string;
+    type: string;
+    content: string;
+    path: string;
+}
+export declare function buildSourceDocKey(project: string, docPath: string, phrenPath: string, fallbackFilename?: string): string;
+export declare function decodeStringRow(row: DbRow, width: number, context: string): string[];
+export declare function decodeFiniteNumber(value: SqlValue | undefined, context: string): number;
+export declare function getDocSourceKey(doc: Pick<DocRow, "project" | "filename" | "path">, phrenPath: string): string;
+/** Normalize a memory ID to canonical format: `mem:project/path/to/file.md`. */
+export declare function normalizeMemoryId(rawId: string): string;
+export declare function rowToDoc(row: DbRow): DocRow;
+export declare function rowToDocWithRowid(row: DbRow): {
+    rowid: number;
+    doc: DocRow;
+};
+export declare function queryRows(db: SqlJsDatabase, sql: string, params: (string | number)[]): DbRow[] | null;
+export declare function queryDocRows(db: SqlJsDatabase, sql: string, params: (string | number)[]): DocRow[] | null;
+export declare function queryDocBySourceKey(db: SqlJsDatabase, phrenPath: string, sourceKey: string): DocRow | null;
+export declare function extractSnippet(content: string, query: string, lines?: number): string;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/init/config.d.ts

@@ -0,0 +1,43 @@
+export type McpConfigStatus = "installed" | "already_configured" | "disabled" | "already_disabled";
+export type McpRootKey = "mcpServers" | "servers";
+export type ToolStatus = McpConfigStatus | "no_settings" | "no_vscode" | "no_cursor" | "no_copilot" | "no_codex";
+export interface HookEntry {
+    matcher?: string;
+    hooks?: Array<{
+        type?: string;
+        command?: string;
+        timeout?: number;
+    }>;
+}
+export type HookEventName = "UserPromptSubmit" | "Stop" | "SessionStart" | "PostToolUse";
+export type HookMap = Partial<Record<HookEventName, HookEntry[]>> & Record<string, unknown>;
+type JsonObject = Record<string, unknown> & {
+    hooks?: HookMap;
+    mcpServers?: Record<string, unknown>;
+    servers?: Record<string, unknown>;
+};
+export declare function patchJsonFile(filePath: string, patch: (data: JsonObject) => void): void;
+export declare function removeTomlMcpServer(filePath: string): boolean;
+export declare function removeMcpServerAtPath(filePath: string): boolean;
+export declare function isPhrenCommand(command: string): boolean;
+export declare function configureClaude(phrenPath: string, opts?: {
+    mcpEnabled?: boolean;
+    hooksEnabled?: boolean;
+}): McpConfigStatus;
+/** Reset the VS Code path probe cache (for testing). */
+export declare function resetVSCodeProbeCache(): void;
+export declare function configureVSCode(phrenPath: string, opts?: {
+    mcpEnabled?: boolean;
+    scope?: "user" | "workspace";
+}): McpConfigStatus | "no_vscode";
+export declare function configureCursorMcp(phrenPath: string, opts?: {
+    mcpEnabled?: boolean;
+}): ToolStatus;
+export declare function configureCopilotMcp(phrenPath: string, opts?: {
+    mcpEnabled?: boolean;
+}): ToolStatus;
+export declare function configureCodexMcp(phrenPath: string, opts?: {
+    mcpEnabled?: boolean;
+}): ToolStatus;
+export declare function logMcpTargetStatus(tool: string, status: string, phase?: "Configured" | "Updated"): void;
+export {};

package/dist/init/init-configure.d.ts

@@ -0,0 +1,21 @@
+import { repairPreexistingInstall } from "./setup.js";
+import type { InitOptions } from "./init.js";
+/**
+ * Configure MCP for all detected AI coding tools (Claude, VS Code, Cursor, Copilot, Codex).
+ * @param verb - label used in log messages, e.g. "Updated" or "Configured"
+ */
+export declare function configureMcpTargets(phrenPath: string, opts: {
+    mcpEnabled: boolean;
+    hooksEnabled: boolean;
+}, verb?: "Configured" | "Updated"): string;
+/**
+ * Configure hooks if enabled, or log a disabled message.
+ * @param verb - label used in log messages, e.g. "Updated" or "Configured"
+ */
+export declare function configureHooksIfEnabled(phrenPath: string, hooksEnabled: boolean, verb: string): void;
+export declare function applyOnboardingPreferences(phrenPath: string, opts: InitOptions): void;
+export declare function writeWalkthroughEnvDefaults(phrenPath: string, opts: InitOptions): string[];
+export declare function collectRepairedAssetLabels(repaired: ReturnType<typeof repairPreexistingInstall>): string[];
+export declare function applyProjectStorageBindings(repoRoot: string, phrenPath: string): string[];
+export declare function warmSemanticSearch(phrenPath: string, profile?: string): Promise<string>;
+export declare function runProjectLocalInit(opts?: InitOptions): Promise<void>;

package/dist/init/init-hooks-mode.d.ts

@@ -0,0 +1 @@
+export declare function runHooksMode(modeArg?: string): Promise<void>;

package/dist/init/init-mcp-mode.d.ts

@@ -0,0 +1 @@
+export declare function runMcpMode(modeArg?: string): Promise<void>;

package/dist/init/init-uninstall.d.ts

@@ -0,0 +1,3 @@
+export declare function runUninstall(opts?: {
+    yes?: boolean;
+}): Promise<void>;

package/dist/init/init-walkthrough.d.ts

@@ -0,0 +1,61 @@
+import type { ProjectOwnershipMode } from "../project-config.js";
+import type { ProactivityLevel } from "../proactivity.js";
+import { type InitProjectDomain, type InferredInitScaffold } from "./setup.js";
+import type { McpMode } from "./shared.js";
+type WorkflowRiskSection = "Review" | "Stale" | "Conflicts";
+type StorageLocationChoice = "global" | "project" | "custom";
+export type WalkthroughChoice<T extends string> = {
+    value: T;
+    name: string;
+    description?: string;
+};
+export type WalkthroughPromptUi = {
+    input(message: string, initialValue?: string): Promise<string>;
+    confirm(message: string, defaultValue?: boolean): Promise<boolean>;
+    select<T extends string>(message: string, choices: WalkthroughChoice<T>[], defaultValue?: T): Promise<T>;
+};
+export type WalkthroughStyle = {
+    header: (text: string) => string;
+    success: (text: string) => string;
+    warning: (text: string) => string;
+};
+export declare function withFallbackColors(style?: {
+    header?: (text: string) => string;
+    success?: (text: string) => string;
+    warning?: (text: string) => string;
+}): WalkthroughStyle;
+export declare function createWalkthroughStyle(): Promise<WalkthroughStyle>;
+export declare function createWalkthroughPrompts(): Promise<WalkthroughPromptUi>;
+export interface WalkthroughResult {
+    storageChoice: StorageLocationChoice;
+    storagePath: string;
+    storageRepoRoot?: string;
+    machine: string;
+    profile: string;
+    mcp: McpMode;
+    hooks: McpMode;
+    projectOwnershipDefault: ProjectOwnershipMode;
+    findingsProactivity: ProactivityLevel;
+    taskProactivity: ProactivityLevel;
+    lowConfidenceThreshold: number;
+    riskySections: WorkflowRiskSection[];
+    taskMode: "off" | "manual" | "suggest" | "auto";
+    bootstrapCurrentProject: boolean;
+    bootstrapOwnership?: ProjectOwnershipMode;
+    ollamaEnabled: boolean;
+    autoCaptureEnabled: boolean;
+    semanticDedupEnabled: boolean;
+    semanticConflictEnabled: boolean;
+    findingSensitivity: "minimal" | "conservative" | "balanced" | "aggressive";
+    githubUsername?: string;
+    githubRepo?: string;
+    cloneUrl?: string;
+    domain: InitProjectDomain;
+    inferredScaffold?: InferredInitScaffold;
+}
+export interface WalkthroughOptions {
+    /** When true, skip the express prompt and use recommended defaults immediately */
+    express?: boolean;
+}
+export declare function runWalkthrough(phrenPath: string, options?: WalkthroughOptions): Promise<WalkthroughResult>;
+export {};

package/dist/init/init.d.ts

@@ -0,0 +1,84 @@
+import { type InstallMode } from "../shared.js";
+export type { McpConfigStatus, McpRootKey, ToolStatus, HookEntry, HookMap } from "./config.js";
+export { configureClaude, configureVSCode, configureCursorMcp, configureCopilotMcp, configureCodexMcp, logMcpTargetStatus, resetVSCodeProbeCache, patchJsonFile, } from "./config.js";
+export type { InstallPreferences } from "./preferences.js";
+export { getMcpEnabledPreference, setMcpEnabledPreference, getHooksEnabledPreference, setHooksEnabledPreference, } from "./preferences.js";
+export { PROJECT_OWNERSHIP_MODES, type ProjectOwnershipMode, parseProjectOwnershipMode, getProjectOwnershipDefault, } from "../project-config.js";
+export { PROACTIVITY_LEVELS, type ProactivityLevel, getProactivityLevel, getProactivityLevelForFindings, getProactivityLevelForTask, } from "../proactivity.js";
+export type { PostInitCheck, InitProjectDomain, InferredInitScaffold } from "./setup.js";
+export { ensureGovernanceFiles, repairPreexistingInstall, runPostInitVerify, getVerifyOutcomeNote, listTemplates, detectProjectDir, isProjectTracked, ensureLocalGitRepo, resolvePreferredHomeDir, inferInitScaffoldFromRepo, } from "./setup.js";
+export { configureMcpTargets, warmSemanticSearch, runProjectLocalInit } from "./init-configure.js";
+export { runMcpMode } from "./init-mcp-mode.js";
+export { runHooksMode } from "./init-hooks-mode.js";
+export { runUninstall } from "./init-uninstall.js";
+import { type InitProjectDomain, type InferredInitScaffold } from "./setup.js";
+import { type McpMode } from "./shared.js";
+import { type ProjectOwnershipMode } from "../project-config.js";
+import { type ProactivityLevel } from "../proactivity.js";
+export { type McpMode, parseMcpMode } from "./shared.js";
+type StorageLocationChoice = "global" | "project" | "custom";
+type SkillsScope = "global" | "project";
+/**
+ * Compare two semver strings. Returns true when `current` is strictly newer
+ * than `previous`. Pre-release versions (e.g. 1.2.3-rc.1) sort before the
+ * corresponding release (1.2.3). Among pre-release tags, comparison is
+ * lexicographic.
+ */
+export declare function isVersionNewer(current: string, previous?: string): boolean;
+export interface InitOptions {
+    mode?: InstallMode;
+    machine?: string;
+    profile?: string;
+    mcp?: McpMode;
+    hooks?: McpMode;
+    projectOwnershipDefault?: ProjectOwnershipMode;
+    findingsProactivity?: ProactivityLevel;
+    taskProactivity?: ProactivityLevel;
+    lowConfidenceThreshold?: number;
+    riskySections?: ("Review" | "Stale" | "Conflicts")[];
+    taskMode?: "off" | "manual" | "suggest" | "auto";
+    findingSensitivity?: "minimal" | "conservative" | "balanced" | "aggressive";
+    skillsScope?: SkillsScope;
+    applyStarterUpdate?: boolean;
+    dryRun?: boolean;
+    yes?: boolean;
+    /** Skip walkthrough entirely with recommended defaults (express mode) */
+    express?: boolean;
+    template?: "python-project" | "monorepo" | "library" | "frontend" | string;
+    /** Set by walkthrough to pass project name to init logic */
+    _walkthroughProject?: string;
+    /** Set by walkthrough for personalized GitHub next-steps output */
+    _walkthroughGithub?: {
+        username?: string;
+        repo: string;
+    };
+    /** Set by walkthrough to seed project docs/topics by domain */
+    _walkthroughDomain?: InitProjectDomain;
+    /** Set by walkthrough to seed adaptive project scaffold from current repo content */
+    _walkthroughInferredScaffold?: InferredInitScaffold;
+    /** Set by walkthrough when user enables auto-capture; triggers writing ~/.phren/.env */
+    _walkthroughAutoCapture?: boolean;
+    /** Set by walkthrough when user opts into local semantic search */
+    _walkthroughSemanticSearch?: boolean;
+    /** Set by walkthrough when user enables LLM semantic dedup */
+    _walkthroughSemanticDedup?: boolean;
+    /** Set by walkthrough when user enables LLM conflict detection */
+    _walkthroughSemanticConflict?: boolean;
+    /** Set by walkthrough when user provides a git clone URL for existing phren */
+    _walkthroughCloneUrl?: string;
+    /** Set by walkthrough when the user wants the current repo enrolled immediately */
+    _walkthroughBootstrapCurrentProject?: boolean;
+    /** Set by walkthrough for the ownership mode selected for the current repo */
+    _walkthroughBootstrapOwnership?: ProjectOwnershipMode;
+    /** Set by walkthrough to select where phren data is stored */
+    _walkthroughStorageChoice?: StorageLocationChoice;
+    /** Set by walkthrough to pass resolved storage path to init logic */
+    _walkthroughStoragePath?: string;
+    /** Set by walkthrough when project-local storage is chosen */
+    _walkthroughStorageRepoRoot?: string;
+}
+export declare function getPendingBootstrapTarget(phrenPath: string, _opts: InitOptions): {
+    path: string;
+    mode: "explicit" | "detected";
+} | null;
+export declare function runInit(opts?: InitOptions): Promise<void>;

package/dist/init/preferences.d.ts

@@ -0,0 +1,28 @@
+import type { CustomHookEntry } from "../hooks.js";
+export interface InstallPreferences {
+    mcpEnabled?: boolean;
+    hooksEnabled?: boolean;
+    skillsScope?: "global" | "project";
+    projectOwnershipDefault?: "phren-managed" | "detached" | "repo-managed";
+    proactivity?: "high" | "medium" | "low";
+    proactivityFindings?: "high" | "medium" | "low";
+    proactivityTask?: "high" | "medium" | "low";
+    hookTools?: Record<string, boolean>;
+    disabledSkills?: Record<string, boolean>;
+    installedVersion?: string;
+    updatedAt?: string;
+    customHooks?: CustomHookEntry[];
+    /** Whether the user intended cross-machine sync ("sync") or local-only ("local"). */
+    syncIntent?: "sync" | "local";
+}
+export declare function governanceInstallPreferencesFile(phrenPath: string): string;
+export declare function readInstallPreferences(phrenPath: string): InstallPreferences;
+export declare function readGovernanceInstallPreferences(phrenPath: string): InstallPreferences;
+export declare function writeInstallPreferences(phrenPath: string, patch: Partial<InstallPreferences>): void;
+export declare function writeGovernanceInstallPreferences(phrenPath: string, patch: Partial<InstallPreferences>): void;
+/** Atomically read-modify-write install preferences using a patcher function. */
+export declare function updateInstallPreferences(phrenPath: string, patcher: (current: InstallPreferences) => Partial<InstallPreferences>): void;
+export declare function getMcpEnabledPreference(phrenPath: string): boolean;
+export declare function setMcpEnabledPreference(phrenPath: string, enabled: boolean): void;
+export declare function getHooksEnabledPreference(phrenPath: string): boolean;
+export declare function setHooksEnabledPreference(phrenPath: string, enabled: boolean): void;

package/dist/init/setup.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Governance files, root file migration, verification, starter templates, bootstrap.
+ */
+import * as fs from "fs";
+import { commandVersion } from "./shared.js";
+import { type ProjectOwnershipMode } from "../project-config.js";
+import { type BuiltinTopic } from "../project-topics.js";
+export interface PostInitCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+    fix?: string;
+}
+interface BootstrapProjectOptions {
+    profile?: string;
+    ownership?: ProjectOwnershipMode;
+}
+interface BootstrapProjectResult {
+    project: string;
+    ownership: ProjectOwnershipMode;
+    claudePath: string | null;
+}
+interface LocalGitRepoStatus {
+    ok: boolean;
+    initialized: boolean;
+    detail: string;
+}
+export type InitProjectDomain = "software" | "music" | "game" | "research" | "writing" | "creative" | "other";
+export declare function resolvePreferredHomeDir(phrenPath: string): string;
+interface RepairInstallResult {
+    profileFilesUpdated: number;
+    removedLegacyProjects: number;
+    createdContextFile: boolean;
+    createdRootMemory: boolean;
+    createdGlobalAssets: string[];
+    createdRuntimeAssets: string[];
+    createdFeatureDefaults: string[];
+    createdSkillArtifacts: string[];
+    repairedGlobalSymlink: boolean;
+}
+export declare function ensureGitignoreEntry(repoRoot: string, entry: string): boolean;
+export declare function upsertProjectEnvVar(repoRoot: string, key: string, value: string): boolean;
+export declare function repairPreexistingInstall(phrenPath: string): RepairInstallResult;
+export declare function getVerifyOutcomeNote(phrenPath: string, checks: PostInitCheck[]): string | null;
+interface HookEntrypointCheckDeps {
+    pathExists?: typeof fs.existsSync;
+    versionReader?: typeof commandVersion;
+}
+export declare function getHookEntrypointCheck(deps?: HookEntrypointCheckDeps): PostInitCheck;
+export declare function applyStarterTemplateUpdates(phrenPath: string): string[];
+export declare function ensureGovernanceFiles(phrenPath: string): string[];
+export declare function listTemplates(): string[];
+export declare function applyTemplate(projectDir: string, templateName: string, projectName: string): boolean;
+export interface InferredInitScaffold {
+    domain: InitProjectDomain;
+    topics: BuiltinTopic[];
+    referenceHints: string[];
+    commandHints: string[];
+    confidence: number;
+    reason: string;
+}
+export declare function inferInitScaffoldFromRepo(repoRoot: string, fallbackDomain?: InitProjectDomain): InferredInitScaffold | null;
+export declare function ensureProjectScaffold(projectDir: string, projectName: string, domain?: InitProjectDomain, inference?: InferredInitScaffold | null): void;
+export declare function ensureLocalGitRepo(phrenPath: string): LocalGitRepoStatus;
+/** Bootstrap a phren project from an existing project directory with CLAUDE.md.
+ * @param profile - if provided, only this profile YAML is updated (avoids leaking project to unrelated profiles).
+ */
+export declare function bootstrapFromExisting(phrenPath: string, projectPath: string, opts?: string | BootstrapProjectOptions): BootstrapProjectResult;
+export declare function updateMachinesYaml(phrenPath: string, machine?: string, profile?: string): void;
+/**
+ * Detect if a directory looks like a project that should be bootstrapped.
+ * Returns the path if it qualifies, null otherwise.
+ * A directory qualifies if it:
+ * - Is not the home directory or phren directory
+ * - Has a CLAUDE.md, AGENTS.md, .claude/CLAUDE.md, or .git directory
+ */
+export declare function detectProjectDir(dir: string, phrenPath: string): string | null;
+/**
+ * Check if a project name is already tracked in any profile.
+ */
+export declare function isProjectTracked(phrenPath: string, projectName: string, profile?: string): boolean;
+export declare function runPostInitVerify(phrenPath: string): {
+    ok: boolean;
+    checks: PostInitCheck[];
+};
+export {};

package/dist/init/shared.d.ts

@@ -0,0 +1,13 @@
+import { VERSION } from "../package-metadata.js";
+export declare const ROOT: string;
+export { VERSION };
+export declare const STARTER_DIR: string;
+export declare const DEFAULT_PHREN_PATH: string;
+export declare function resolveEntryScript(): string;
+export declare function log(msg: string): void;
+export declare function commandVersion(cmd: string, args?: string[]): string | null;
+export declare function versionAtLeast(raw: string | null, major: number, minor?: number): boolean;
+export declare function nearestWritableTarget(filePath: string): boolean;
+export type McpMode = "on" | "off";
+export declare function parseMcpMode(raw?: string): McpMode | undefined;
+export declare function confirmPrompt(message: string): Promise<boolean>;

package/dist/init-bootstrap.d.ts

@@ -0,0 +1,5 @@
+import { type ProjectOwnershipMode } from "./project-config.js";
+/**
+ * Bootstrap a project from an existing directory into phren.
+ */
+export declare function bootstrapProject(phrenPath: string, projectPath: string, profile: string | undefined, ownership: ProjectOwnershipMode, label: string): void;

package/dist/init-detect.d.ts

@@ -0,0 +1,8 @@
+import type { InitOptions } from "./init-types.js";
+export declare function normalizedBootstrapProjectName(projectPath: string): string;
+export declare function getPendingBootstrapTarget(phrenPath: string, _opts: InitOptions): {
+    path: string;
+    mode: "explicit" | "detected";
+} | null;
+export declare function hasInstallMarkers(phrenPath: string): boolean;
+export declare function resolveInitPhrenPath(opts: InitOptions): string;

package/dist/init-env.d.ts

@@ -0,0 +1,6 @@
+import type { InitOptions } from "./init-types.js";
+import { repairPreexistingInstall } from "./init/setup.js";
+export declare function applyOnboardingPreferences(phrenPath: string, opts: InitOptions): void;
+export declare function writeWalkthroughEnvDefaults(phrenPath: string, opts: InitOptions): string[];
+export declare function collectRepairedAssetLabels(repaired: ReturnType<typeof repairPreexistingInstall>): string[];
+export declare function applyProjectStorageBindings(repoRoot: string, phrenPath: string): string[];

package/dist/init-fresh.d.ts

@@ -0,0 +1,10 @@
+import type { InitOptions, SkillsScope } from "./init-types.js";
+export declare function runFreshInstall(phrenPath: string, opts: InitOptions, params: {
+    mcpEnabled: boolean;
+    hooksEnabled: boolean;
+    skillsScope: SkillsScope;
+    ownershipDefault: string;
+    syncIntent: "sync" | "local";
+    shouldBootstrapCurrentProject: boolean;
+    bootstrapOwnership: string;
+}): Promise<void>;

package/dist/init-hooks.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Configure hooks if enabled, or log a disabled message.
+ * @param verb - label used in log messages, e.g. "Updated" or "Configured"
+ */
+export declare function configureHooksIfEnabled(phrenPath: string, hooksEnabled: boolean, verb: string): void;

package/dist/init-mcp.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Configure MCP for all detected AI coding tools (Claude, VS Code, Cursor, Copilot, Codex).
+ * @param verb - label used in log messages, e.g. "Updated" or "Configured"
+ */
+export declare function configureMcpTargets(phrenPath: string, opts: {
+    mcpEnabled: boolean;
+    hooksEnabled: boolean;
+}, verb?: "Configured" | "Updated"): string;