Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import {
accessSync,
constants,
lstatSync,
mkdirSync,
readdirSync,
readFileSync,
realpathSync,
statSync,
} from 'node:fs';
import { homedir } from 'node:os';
import { basename, dirname, join, resolve } from 'node:path';
import type {
PiBridgeWriteAction,
PiTrustWriteAction,
} from '@inkeep/open-knowledge-core/acp/thread-protocol';
import { atomicWriteFileSync, okUserHomeDir } from '@inkeep/open-knowledge-core/server';
import { buildPiExtensionSource, isOwnPiManagedFileEntry } from '../integrations/pi-extension.ts';
import {
type ConfigFileDeclineReason,
configFileDeclineDetail,
configFileDeclineReason,
} from '../utils/config-file-error.ts';
import { escapeDisplayPath } from '../utils/escape-display-path.ts';
import { isObject } from '../utils/is-object.ts';
import {
EDITOR_TARGETS,
isEntryUpToDate,
type McpInstallOptions,
resolvePiAgentDirPath,
} from './editors.ts';
import { classifyExistingMcpEntry, writeEditorMcpConfig } from './init.ts';
import { existingFileMode } from './jsonc-surgical.ts';
import {
commitPiTrustGrant,
forgetPiTrustGrant,
listPiTrustGrants,
type PiTrustGrantReceipt,
PiTrustReceiptError,
preparePiTrustGrant,
} from './pi-trust-grants.ts';
import { withPiTrustLock, withPiTrustLockSync } from './pi-trust-lock.ts';
import { inspectPiTrustResources } from './pi-trust-resources.ts';
import { resolveRemovalFilePath } from './removal-file-path.ts';
const PI_TRUST_FILENAME = 'trust.json';
export type PiBridgeFileState = 'absent' | 'own-current' | 'own-stale' | 'foreign' | 'unreadable';
export type PiTrustState = 'trusted' | 'untrusted' | 'unreadable';
export type PiBridgeState = {
cwd: string;
bridgePath: string;
trustPath: string;
} & (
| { project: 'unavailable'; error: string }
| {
project: 'ready';
canonicalCwd: string;
bridge: PiBridgeFileState;
trust: PiTrustState;
bridgeLoadable: boolean;
otherExtensions: readonly string[];
}
);
export type { PiBridgeWriteAction, PiTrustWriteAction };
type PiTrustRemoveResult =
| { action: 'removed' | 'not-present'; error?: never; detail?: never }
| { action: 'kept-shared' | 'kept-unowned'; detail: string; error?: never }
| { action: 'kept-unverified' | 'refused-unreadable' | 'failed'; error: string; detail?: never };
export type PiTrustRemoveAction = PiTrustRemoveResult['action'];
export interface EnsurePiBridgeResult {
ok: boolean;
cwd: string;
bridgePath: string;
trustPath: string;
bridge: PiBridgeWriteAction;
trust: PiTrustWriteAction;
error?: string;
}
function resolvePiPaths(
cwd: string,
home?: string,
env?: NodeJS.ProcessEnv,
): {
cwd: string;
bridgePath: string;
trustPath: string;
} {
const normalizedCwd = resolve(cwd);
const agentDir = resolvePiAgentDirPath({
home,
env: env ?? (home === undefined ? process.env : {}),
});
return {
cwd: normalizedCwd,
bridgePath: EDITOR_TARGETS.pi.projectConfigPath(normalizedCwd),
trustPath: join(agentDir, PI_TRUST_FILENAME),
};
}
type PiProjectPath = { path: string; canonical: string };
function resolvePiProjectPath(
path: string,
): { kind: 'ready'; project: PiProjectPath } | { kind: 'refused'; error: string } {
try {
const canonical = realpathSync(path);
if (!statSync(canonical).isDirectory()) {
return {
kind: 'refused',
error: `Pi project path ${escapeDisplayPath(path)} is not a directory; restore the intended project directory, then retry`,
};
}
accessSync(canonical, constants.X_OK);
return { kind: 'ready', project: { path, canonical } };
} catch (error) {
return {
kind: 'refused',
error: `Pi project directory ${escapeDisplayPath(path)} could not be resolved or accessed: ${escapeDisplayPath(error instanceof Error ? error.message : String(error))}; restore the directory or symlink and check its permissions, then retry`,
};
}
}
function recheckPiProjectPath(project: PiProjectPath): string | undefined {
const checked = resolvePiProjectPath(project.path);
if (checked.kind === 'refused') return checked.error;
if (checked.project.canonical !== project.canonical) {
return `Pi project path ${escapeDisplayPath(project.path)} changed while waiting for its trust lock; restore the intended project location, then retry`;
}
return undefined;
}
function classifyPiBridgeFile(
cwd: string,
bridgePath: string,
home: string | undefined,
): { state: PiBridgeFileState; text: string | null } {
const classified = classifyExistingMcpEntry(EDITOR_TARGETS.pi, cwd, home, bridgePath);
if (classified.kind === 'absent') return { state: 'absent', text: null };
if (classified.kind !== 'present') return { state: 'unreadable', text: null };
const entry = classified.entry;
const text =
Array.isArray(entry.args) && typeof entry.args[0] === 'string' ? entry.args[0] : null;
if (isEntryUpToDate(entry)) return { state: 'own-current', text };
if (isOwnPiManagedFileEntry(entry)) return { state: 'own-stale', text };
return { state: 'foreign', text };
}
type PiTrustReadResult =
| {
state: 'trusted' | 'untrusted';
entries: Record<string, unknown>;
trailingNewline: boolean;
}
| { state: 'unreadable'; reason: ReturnType<typeof configFileDeclineReason> | 'invalid-json' };
function readPiTrust(
file: Extract<PiTrustFilePath, { path: string }>,
cwd: string,
): PiTrustReadResult {
let raw: string;
try {
raw = readFileSync(file.path, 'utf-8');
} catch (err) {
const code = (err as NodeJS.ErrnoException).code;
if (file.kind === 'missing' && code === 'ENOENT') {
return { state: 'untrusted', entries: {}, trailingNewline: false };
}
return { state: 'unreadable', reason: configFileDeclineReason(err) };
}
if (raw.trim() === '') return { state: 'untrusted', entries: {}, trailingNewline: false };
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return { state: 'unreadable', reason: 'invalid-json' };
}
if (!isObject(parsed)) return { state: 'unreadable', reason: 'invalid-json' };
return {
state: parsed[cwd] === true ? 'trusted' : 'untrusted',
entries: parsed,
trailingNewline: raw.endsWith('\n'),
};
}
type PiTrustFilePath =
| { kind: 'ready' | 'missing'; path: string }
| { kind: 'refused'; error: string };
type PiTrustRefusalReason =
| ConfigFileDeclineReason
| 'invalid-json'
| 'path-changed'
| 'unavailable-root';
function piTrustRefusalDetail(reason: PiTrustRefusalReason): string {
switch (reason) {
case 'invalid-json':
return 'the file is not a valid JSON object; repair its JSON, then retry';
case 'path-changed':
return 'the path changed while waiting for its lock; retry to check its current state';
case 'unavailable-root':
return 'the filesystem root is unavailable; reconnect the drive or network share, then retry';
default:
return configFileDeclineDetail(reason);
}
}
function refusedTrustPath(
trustPath: string,
reason: PiTrustRefusalReason,
): Extract<PiTrustFilePath, { kind: 'refused' }> {
return {
kind: 'refused',
error: `trust store ${escapeDisplayPath(trustPath)}: ${piTrustRefusalDetail(reason)}`,
};
}
function resolvePiTrustFilePath(trustPath: string): PiTrustFilePath {
const resolved = resolveRemovalFilePath(trustPath);
try {
switch (resolved.kind) {
case 'declined':
return refusedTrustPath(trustPath, resolved.reason);
case 'ready':
return { kind: 'ready', path: realpathSync(resolved.path) };
case 'not-present':
break;
default: {
const exhaustive: never = resolved;
throw new Error(`unhandled trust file resolution: ${exhaustive}`);
}
}
let parent = dirname(trustPath);
const suffix = [basename(trustPath)];
let parentEntry = lstatSync(parent, { throwIfNoEntry: false });
while (!parentEntry) {
const ancestor = dirname(parent);
if (ancestor === parent) return refusedTrustPath(trustPath, 'unavailable-root');
suffix.unshift(basename(parent));
parent = ancestor;
parentEntry = lstatSync(parent, { throwIfNoEntry: false });
}
try {
return { kind: 'missing', path: join(realpathSync(parent), ...suffix) };
} catch (error) {
return refusedTrustPath(
trustPath,
parentEntry.isSymbolicLink() && (error as NodeJS.ErrnoException).code === 'ENOENT'
? 'missing-symlink-target'
: configFileDeclineReason(error),
);
}
} catch (error) {
return refusedTrustPath(trustPath, configFileDeclineReason(error));
}
}
function recheckPiTrustFilePath(
trustPath: string,
previous: Extract<PiTrustFilePath, { path: string }>,
): PiTrustFilePath {
const current = resolvePiTrustFilePath(trustPath);
if (current.kind === 'refused') return current;
if (current.path !== previous.path || (previous.kind === 'ready' && current.kind === 'missing')) {
return refusedTrustPath(trustPath, 'path-changed');
}
return current;
}
export function probePiBridgeState(
cwd: string,
home?: string,
env?: NodeJS.ProcessEnv,
): PiBridgeState {
const paths = resolvePiPaths(cwd, home, env);
const project = resolvePiProjectPath(paths.cwd);
if (project.kind === 'refused') {
return { ...paths, project: 'unavailable', error: project.error };
}
const bridge = classifyPiBridgeFile(paths.cwd, paths.bridgePath, home).state;
const trustFile = resolvePiTrustFilePath(paths.trustPath);
const trust =
trustFile.kind === 'refused'
? 'unreadable'
: trustFile.kind === 'missing'
? 'untrusted'
: readPiTrust(trustFile, project.project.canonical).state;
return {
...paths,
project: 'ready',
canonicalCwd: project.project.canonical,
bridge,
trust,
bridgeLoadable: (bridge === 'own-current' || bridge === 'own-stale') && trust === 'trusted',
otherExtensions: listOtherPiExtensions(paths.bridgePath).displayNames,
};
}
function listOtherPiExtensions(bridgePath: string): {
displayNames: readonly string[];
} {
const dir = dirname(bridgePath);
const own = basename(bridgePath);
try {
return {
displayNames: readdirSync(dir)
.filter((name) => name !== own && name.endsWith('.ts'))
.sort()
.map((name) => escapeDisplayPath(JSON.stringify(name))),
};
} catch {
return { displayNames: [] };
}
}
export async function ensurePiBridge(
cwd: string,
options: McpInstallOptions = { mode: 'published' },
home?: string,
env?: NodeJS.ProcessEnv,
approvedCanonicalCwd?: string,
): Promise<EnsurePiBridgeResult> {
const base = resolvePiPaths(cwd, home, env);
const project = resolvePiProjectPath(base.cwd);
if (project.kind === 'refused') {
return {
...base,
ok: false,
bridge: 'refused-project-path',
trust: 'skipped',
error: project.error,
};
}
if (approvedCanonicalCwd !== undefined && project.project.canonical !== approvedCanonicalCwd) {
return {
...base,
ok: false,
bridge: 'refused-project-path',
trust: 'skipped',
error: `The approved Pi project directory ${escapeDisplayPath(approvedCanonicalCwd)} no longer matches the current directory ${escapeDisplayPath(project.project.canonical)}. Reopen the intended project and approve the Pi integration again; no bridge or trust settings were changed.`,
};
}
const existing = classifyPiBridgeFile(base.cwd, base.bridgePath, home);
if (existing.state === 'foreign') {
return { ...base, ok: false, bridge: 'refused-foreign', trust: 'skipped' };
}
if (existing.state === 'unreadable') {
return { ...base, ok: false, bridge: 'refused-unreadable', trust: 'skipped' };
}
let bridge: PiBridgeWriteAction;
if (existing.state === 'absent') {
bridge = 'written';
} else {
let desired: string | undefined;
try {
desired = buildPiExtensionSource(options);
} catch {
desired = undefined;
}
bridge = desired !== undefined && existing.text === desired ? 'unchanged' : 'refreshed';
}
if (bridge !== 'unchanged') {
const result = writeEditorMcpConfig(
EDITOR_TARGETS.pi,
base.cwd,
options,
home,
base.bridgePath,
);
if (result.action !== 'written' && result.action !== 'overwritten') {
return {
...base,
ok: false,
bridge: 'failed',
trust: 'skipped',
error:
result.error !== undefined
? escapeDisplayPath(result.error)
: `bridge write ${result.action}`,
};
}
}
const trust = await addPiTrustEntry(base.trustPath, project.project, home ?? homedir());
return {
...base,
ok: trust.action === 'already-trusted' || trust.action === 'added',
bridge,
trust: trust.action,
...(trust.error !== undefined ? { error: trust.error } : {}),
};
}
async function addPiTrustEntry(
trustPath: string,
project: PiProjectPath,
home: string,
): Promise<{ action: PiTrustWriteAction; error?: string }> {
const cwd = project.canonical;
const resolved = resolvePiTrustFilePath(trustPath);
if (resolved.kind === 'refused') return { action: 'refused-unreadable', error: resolved.error };
try {
mkdirSync(dirname(resolved.path), { recursive: true });
} catch (err) {
return {
action: 'failed',
error: escapeDisplayPath(err instanceof Error ? err.message : String(err)),
};
}
const captured: { action: PiTrustWriteAction; error?: string } = { action: 'added' };
try {
await withPiTrustLock(trustPath, resolved.path, () => {
const projectError = recheckPiProjectPath(project);
if (projectError) {
captured.action = 'refused-unreadable';
captured.error = projectError;
return;
}
const checked = recheckPiTrustFilePath(trustPath, resolved);
if (checked.kind === 'refused') {
captured.action = 'refused-unreadable';
captured.error = checked.error;
return;
}
const current = readPiTrust(checked, cwd);
if (current.state === 'trusted') {
captured.action = 'already-trusted';
return;
}
if (current.state === 'unreadable') {
captured.action = 'refused-unreadable';
captured.error = refusedTrustPath(trustPath, current.reason).error;
return;
}
const receipt = accessPiTrustReceipts(home, () => {
const previousReceipt = listPiTrustGrants(home, cwd).find(
(grant) => grant.record.canonicalTrustPath === checked.path,
);
if (previousReceipt) forgetPiTrustGrant(home, previousReceipt);
return preparePiTrustGrant(
home,
cwd,
trustPath,
checked.path,
Object.hasOwn(current.entries, cwd)
? { present: true, value: current.entries[cwd] }
: { present: false },
);
});
const next = { ...current.entries, [cwd]: true };
const serialized = JSON.stringify(next, null, 2) + (current.trailingNewline ? '\n' : '');
const mode = existingFileMode(checked.path);
atomicWriteFileSync(checked.path, serialized, mode !== undefined ? { mode } : undefined);
accessPiTrustReceipts(home, () => commitPiTrustGrant(home, receipt));
captured.action = 'added';
});
} catch (err) {
return {
action: 'failed',
error: escapeDisplayPath(err instanceof Error ? err.message : String(err)),
};
}
return captured;
}
function missingPiProjectPathCandidate(path: string): string | undefined {
const suffix: string[] = [];
let inspecting = path;
try {
while (true) {
const entry = lstatSync(inspecting, { throwIfNoEntry: false });
if (entry) {
if (suffix.length === 0) return undefined;
const ancestor = realpathSync(inspecting);
if (!statSync(ancestor).isDirectory()) return undefined;
accessSync(ancestor, constants.X_OK);
return join(ancestor, ...suffix);
}
const parent = dirname(inspecting);
if (parent === inspecting) return undefined;
suffix.unshift(basename(inspecting));
inspecting = parent;
}
} catch {
return undefined;
}
}
type PiTrustRemovalKey = {
cwd: string;
mode: 'recorded' | 'inspect';
receipt?: PiTrustGrantReceipt;
};
type PiTrustRemovalStore = {
trustPath: string;
resolved: Extract<PiTrustFilePath, { path: string }>;
keys: Map<string, PiTrustRemovalKey>;
};
function aggregatePiTrustRemoval(outcomes: readonly PiTrustRemoveResult[]): PiTrustRemoveResult {
const priority = {
'not-present': 0,
removed: 1,
'kept-unowned': 2,
'kept-shared': 3,
'kept-unverified': 4,
'refused-unreadable': 5,
failed: 6,
} satisfies Record<PiTrustRemoveAction, number>;
const outcome = outcomes.reduce<PiTrustRemoveResult>(
(best, item) => (priority[item.action] > priority[best.action] ? item : best),
{ action: 'not-present' },
);
const errors = outcomes.flatMap((item) => item.error ?? []);
const details = outcomes.flatMap((item) => item.detail ?? []);
if (errors.length > 0) {
return {
action: outcome.error !== undefined ? outcome.action : 'failed',
error: [...errors, ...details].join('\n'),
};
}
if (outcome.detail !== undefined) return { ...outcome, detail: details.join('\n') };
return outcome;
}
export function removePiTrustEntry(
cwd: string,
home?: string,
env?: NodeJS.ProcessEnv,
options: { recordedOnly?: boolean } = {},
): PiTrustRemoveResult {
const base = resolvePiPaths(cwd, home, env);
const resolvedHome = home ?? homedir();
const project = resolvePiProjectPath(base.cwd);
const missingCandidate =
project.kind === 'refused' && options.recordedOnly
? missingPiProjectPathCandidate(base.cwd)
: undefined;
const receiptCwd = project.kind === 'ready' ? project.project.canonical : missingCandidate;
let receipts: PiTrustGrantReceipt[];
try {
receipts = accessPiTrustReceipts(resolvedHome, () => {
const literal = listPiTrustGrants(resolvedHome, base.cwd);
if (receiptCwd === undefined || receiptCwd === base.cwd) return literal;
return [...listPiTrustGrants(resolvedHome, receiptCwd), ...literal];
});
} catch (error) {
return {
action: 'failed',
error: escapeDisplayPath(error instanceof Error ? error.message : String(error)),
};
}
if (receipts.length === 0 && options.recordedOnly) {
if (project.kind === 'ready' || missingCandidate !== undefined)
return { action: 'not-present' };
return {
action: 'kept-unverified',
error: `${project.error}. OpenKnowledge could not verify whether this path refers to a project with recorded Pi trust; cleanup was left pending. Retry once the project path can be resolved to check again.`,
};
}
if (project.kind === 'refused') {
if (receipts.length === 0) return { action: 'kept-unverified', error: project.error };
const records = receipts.map(
({ path, record }) =>
`key ${escapeDisplayPath(JSON.stringify(record.cwd))}; configured store ${escapeDisplayPath(JSON.stringify(record.configuredTrustPath))}; recorded destination ${escapeDisplayPath(JSON.stringify(record.canonicalTrustPath))}; ownership record ${escapeDisplayPath(JSON.stringify(path))} (${record.state})`,
);
return {
action: 'kept-unverified',
error: [
`${project.error}. OpenKnowledge kept these Pi trust ownership records; current trust decisions were not checked:`,
...records,
'To review manually, close Pi, verify the intended store against its recorded destination, and inspect only the exact key. A pending record does not prove setup completed or ownership of a current grant. If you choose to undo a current true decision, restore the recorded previous value, or remove that key only when no previous entry was recorded. Preserve other current decisions; parent-folder and global trust settings still apply.',
].join('\n'),
};
}
const resources = inspectPiTrustResources(
project.project.canonical,
resolvedHome,
EDITOR_TARGETS.pi.projectConfigPath(project.project.canonical),
);
if (resources.kind === 'unreadable') {
return { action: 'kept-unverified', error: resources.error };
}
const sharedPaths = resources.kind === 'shared' ? resources.paths : [];
const outcomes: PiTrustRemoveResult[] = [];
const stores = new Map<string, PiTrustRemovalStore>();
const addStore = (trustPath: string, receipt?: PiTrustGrantReceipt): void => {
let store = stores.get(trustPath);
if (!store) {
const resolved = resolvePiTrustFilePath(trustPath);
if (resolved.kind === 'refused') {
outcomes.push({ action: 'refused-unreadable', error: resolved.error });
return;
}
store = { trustPath, resolved, keys: new Map() };
stores.set(trustPath, store);
}
if (!receipt) return;
if (store.resolved.path !== receipt.record.canonicalTrustPath) {
outcomes.push({
action: 'refused-unreadable',
error: `Pi trust store ${escapeDisplayPath(trustPath)} no longer points to its recorded destination ${escapeDisplayPath(receipt.record.canonicalTrustPath)}; restore the intended file location or symlink, then retry`,
});
return;
}
store.keys.set(receipt.record.cwd, { cwd: receipt.record.cwd, mode: 'recorded', receipt });
};
for (const receipt of receipts) addStore(receipt.record.configuredTrustPath, receipt);
addStore(base.trustPath);
for (const store of stores.values()) {
for (const key of [project.project.canonical, base.cwd]) {
if (!store.keys.has(key)) {
store.keys.set(key, {
cwd: key,
mode: 'inspect',
receipt: receipts.find(
(receipt) =>
receipt.record.cwd === key &&
receipt.record.canonicalTrustPath === store.resolved.path,
),
});
}
}
outcomes.push(removePiTrustStore(store, resolvedHome, sharedPaths, project.project));
}
return aggregatePiTrustRemoval(outcomes);
}
function accessPiTrustReceipts<T>(home: string, operation: () => T): T {
try {
return operation();
} catch (error) {
if (error instanceof PiTrustReceiptError) throw error;
throw new Error(
`Could not access OpenKnowledge's Pi trust ownership records at ${escapeDisplayPath(join(okUserHomeDir(home), 'pi-trust'))}: ${escapeDisplayPath(error instanceof Error ? error.message : String(error))}. Check the records and their permissions, then retry.`,
{ cause: error },
);
}
}
function removePiTrustStore(
store: PiTrustRemovalStore,
home: string,
sharedPaths: string[],
project: PiProjectPath,
): PiTrustRemoveResult {
const { trustPath, resolved } = store;
const keys = [...store.keys.values()];
if (!keys.some((key) => key.mode === 'recorded') && resolved.kind === 'missing')
return { action: 'not-present' };
if (resolved.kind === 'missing') {
try {
lstatSync(dirname(resolved.path));
} catch (error) {
return {
action: 'failed',
error: `The recorded Pi trust directory ${escapeDisplayPath(dirname(resolved.path))} is unavailable: ${escapeDisplayPath(error instanceof Error ? error.message : String(error))}. Restore access to its parent directory or mounted drive, then retry; the ownership record was kept.`,
};
}
}
const outcomes: PiTrustRemoveResult[] = [];
const captured: { result: PiTrustRemoveResult } = { result: { action: 'not-present' } };
try {
withPiTrustLockSync(trustPath, resolved.path, () => {
const projectError = recheckPiProjectPath(project);
if (projectError) {
captured.result = { action: 'kept-unverified', error: projectError };
return;
}
const checked = recheckPiTrustFilePath(trustPath, resolved);
if (checked.kind === 'refused') {
captured.result = { action: 'refused-unreadable', error: checked.error };
return;
}
const current = readPiTrust(checked, project.canonical);
if (current.state === 'unreadable') {
captured.result = {
action: 'refused-unreadable',
error: refusedTrustPath(trustPath, current.reason).error,
};
return;
}
const currentKeys = keys.map((key) => ({
cwd: key.cwd,
mode: key.mode,
expectedConfiguredPath: key.receipt?.record.configuredTrustPath,
receipt: accessPiTrustReceipts(home, () =>
listPiTrustGrants(home, key.cwd).find(
(grant) => grant.record.canonicalTrustPath === checked.path,
),
),
}));
if (
currentKeys.some(
(key) =>
key.receipt && key.receipt.record.configuredTrustPath !== key.expectedConfiguredPath,
)
) {
captured.result = {
action: 'failed',
error:
'The Pi trust ownership record changed during cleanup; retry to read its current location.',
};
return;
}
for (const key of currentKeys) {
try {
removePiTrustKey(
key,
home,
trustPath,
checked.path,
current,
sharedPaths,
project,
captured,
);
} catch (error) {
const detail = escapeDisplayPath(error instanceof Error ? error.message : String(error));
const retry =
error instanceof PiTrustReceiptError ? '' : '; retry to check its current state.';
outcomes.push({
action: 'failed',
error: `Pi trust entry ${escapeDisplayPath(JSON.stringify(key.cwd))} in ${escapeDisplayPath(trustPath)} could not be reconciled: ${detail}${retry}`,
});
}
outcomes.push(captured.result);
captured.result = { action: 'not-present' };
}
});
} catch (error) {
outcomes.push({
action: 'failed',
error: escapeDisplayPath(error instanceof Error ? error.message : String(error)),
});
}
return aggregatePiTrustRemoval([...outcomes, captured.result]);
}
function removePiTrustKey(
key: PiTrustRemovalKey,
home: string,
trustPath: string,
canonicalTrustPath: string,
current: Extract<PiTrustReadResult, { entries: unknown }>,
sharedPaths: string[],
project: PiProjectPath,
captured: { result: PiTrustRemoveResult },
): void {
const { cwd, receipt } = key;
if (current.entries[cwd] !== true) {
if (receipt && key.mode === 'recorded')
accessPiTrustReceipts(home, () => forgetPiTrustGrant(home, receipt));
captured.result = { action: 'not-present' };
return;
}
const manualAction = `To remove this grant manually, close Pi and remove only the ${escapeDisplayPath(JSON.stringify(cwd))} entry from ${escapeDisplayPath(trustPath)}; parent-folder and global trust settings still apply.`;
if (sharedPaths.length > 0 && cwd === project.canonical) {
const shown = sharedPaths
.slice(0, 3)
.map((path) => escapeDisplayPath(JSON.stringify(path)))
.join(', ');
const remaining = sharedPaths.length > 3 ? ` (+${sharedPaths.length - 3} more)` : '';
const detail = `kept Pi's folder trust because other resources still need it: ${shown}${remaining}. ${manualAction} Removing this grant may stop Pi from loading those resources, including any not listed here.`;
captured.result = { action: 'kept-shared', detail };
if (receipt && key.mode === 'recorded')
accessPiTrustReceipts(home, () => forgetPiTrustGrant(home, receipt));
const ownership = !receipt
? 'OpenKnowledge has no ownership record for this grant and will not revoke it on later cleanup runs.'
: key.mode === 'recorded'
? 'OpenKnowledge has relinquished this grant and will not revoke it on later cleanup runs.'
: 'OpenKnowledge kept the existing ownership record; cleanup of its recorded location remains incomplete.';
captured.result = { action: 'kept-shared', detail: `${detail} ${ownership}` };
return;
}
if (key.mode === 'inspect' || !receipt || receipt.record.state === 'pending') {
const reason = !receipt
? 'no OpenKnowledge ownership record exists; this includes every grant made before ownership recording was introduced.'
: receipt.record.state === 'pending'
? 'its ownership record is pending after an interrupted setup; completion cannot be verified. Re-running setup or cleanup does not reconcile this record while the folder remains trusted.'
: `OpenKnowledge must reconcile its recorded location at ${escapeDisplayPath(receipt.record.configuredTrustPath)} before removing it.`;
const subject =
cwd === project.canonical
? `kept Pi's folder trust because ${reason}`
: `kept a Pi trust entry under a non-canonical project path because ${reason} Pi uses the real project directory instead of this key.`;
captured.result = { action: 'kept-unowned', detail: `${subject} ${manualAction}` };
return;
}
const next = { ...current.entries };
if (receipt.record.previous.present) next[cwd] = receipt.record.previous.value;
else delete next[cwd];
const serialized = JSON.stringify(next, null, 2) + (current.trailingNewline ? '\n' : '');
const mode = existingFileMode(canonicalTrustPath);
atomicWriteFileSync(canonicalTrustPath, serialized, mode !== undefined ? { mode } : undefined);
current.entries = next;
accessPiTrustReceipts(home, () => forgetPiTrustGrant(home, receipt));
captured.result = { action: 'removed' };
}