@morsa/guidance-bank 0.2.0

package/dist/core/projects/findReferenceProjects.js

@@ -0,0 +1,42 @@
+import { detectProjectContext } from "../context/detectProjectContext.js";
+import { DETECTABLE_STACKS } from "../context/types.js";
+const intersectStacks = (left, right) => left.filter((stack) => right.includes(stack));
+const detectableStackSet = new Set(DETECTABLE_STACKS);
+export const findReferenceProjects = async ({ repository, currentProjectId, detectedStacks, }) => {
+    const manifests = await repository.listProjectManifests();
+    const candidates = await Promise.all(manifests
+        .filter((manifest) => manifest.projectId !== currentProjectId)
+        .map(async (manifest) => {
+        const manifestStacks = manifest.detectedStacks.length > 0
+            ? manifest.detectedStacks
+            : (await detectProjectContext(manifest.projectPath).catch(() => null))?.detectedStacks ?? [];
+        const normalizedStacks = manifestStacks.filter((stack) => detectableStackSet.has(stack));
+        const sharedStacks = intersectStacks(detectedStacks, normalizedStacks);
+        return {
+            projectId: manifest.projectId,
+            projectName: manifest.projectName,
+            projectPath: manifest.projectPath,
+            projectBankPath: repository.paths.projectDirectory(manifest.projectId),
+            detectedStacks: normalizedStacks,
+            sharedStacks,
+            updatedAt: manifest.updatedAt,
+        };
+    }));
+    return candidates
+        .filter((candidate) => candidate.sharedStacks.length > 0)
+        .sort((left, right) => {
+        if (right.sharedStacks.length !== left.sharedStacks.length) {
+            return right.sharedStacks.length - left.sharedStacks.length;
+        }
+        return right.updatedAt.localeCompare(left.updatedAt);
+    })
+        .slice(0, 5)
+        .map((candidate) => ({
+        projectId: candidate.projectId,
+        projectName: candidate.projectName,
+        projectPath: candidate.projectPath,
+        projectBankPath: candidate.projectBankPath,
+        detectedStacks: candidate.detectedStacks,
+        sharedStacks: candidate.sharedStacks,
+    }));
+};

package/dist/core/projects/guidanceStrategies.js

@@ -0,0 +1,29 @@
+export const GUIDANCE_SOURCE_STRATEGIES = ["ignore", "copy", "move", "keep_source_fill_gaps"];
+export const SOURCE_REVIEW_DECISIONS = ["ok", "not_ok"];
+export const formatGuidanceSourceStrategy = (strategy) => {
+    switch (strategy) {
+        case "ignore":
+            return "ignore";
+        case "copy":
+            return "copy";
+        case "move":
+            return "move";
+        case "keep_source_fill_gaps":
+            return "keep source, fill gaps in bank";
+    }
+};
+export const buildDefaultSourceStrategies = (sources, decision) => {
+    return sources.map((source) => ({
+        sourceRef: source.relativePath,
+        strategy: source.entryType === "directory"
+            ? "ignore"
+            : decision === "ok"
+                ? "move"
+                : "copy",
+        note: source.entryType === "directory"
+            ? "Handled as a container while file-level guidance is migrated."
+            : decision === "ok"
+                ? "Confirmed by the default canonicalization flow with legacy cleanup allowed."
+                : "Confirmed by the default canonicalization flow while keeping legacy guidance in place.",
+    }));
+};

package/dist/core/projects/identity.js

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+const normalizeProjectPath = (projectPath) => {
+    const resolvedPath = path.resolve(projectPath);
+    return resolvedPath.endsWith(path.sep) ? resolvedPath.slice(0, -1) : resolvedPath;
+};
+export const resolveProjectIdentity = (projectPath) => {
+    const normalizedProjectPath = normalizeProjectPath(projectPath);
+    const projectName = path.basename(normalizedProjectPath);
+    const hash = createHash("sha256").update(normalizedProjectPath).digest("hex").slice(0, 12);
+    return {
+        projectId: `${projectName}-${hash}`,
+        projectName,
+        projectPath: normalizedProjectPath,
+    };
+};

package/dist/core/projects/providerProjectGuidance.js

@@ -0,0 +1,82 @@
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+const pathExists = async (targetPath) => {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const getHomePath = () => process.env.HOME ?? os.homedir();
+const listFilesRecursively = async (directoryPath) => {
+    const directoryEntries = await fs.readdir(directoryPath, { withFileTypes: true });
+    const filePaths = [];
+    for (const directoryEntry of directoryEntries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const entryPath = path.join(directoryPath, directoryEntry.name);
+        if (directoryEntry.isDirectory()) {
+            filePaths.push(...(await listFilesRecursively(entryPath)));
+            continue;
+        }
+        if (directoryEntry.isFile()) {
+            filePaths.push(entryPath);
+        }
+    }
+    return filePaths;
+};
+const toHomeRelativePath = (targetPath) => {
+    const homePath = getHomePath();
+    const relativeToHome = path.relative(homePath, targetPath);
+    return relativeToHome.startsWith("..") || path.isAbsolute(relativeToHome) ? targetPath : `~/${relativeToHome}`;
+};
+const encodeProjectPathForCursor = (projectPath) => path
+    .resolve(projectPath)
+    .split(path.sep)
+    .filter(Boolean)
+    .join("-")
+    .replaceAll(" ", "-");
+const encodeProjectPathForClaude = (projectPath) => `-${encodeProjectPathForCursor(projectPath)}`;
+const getCandidateRoots = (projectPath) => {
+    const projectName = path.basename(path.resolve(projectPath));
+    const homePath = getHomePath();
+    return [
+        {
+            provider: "codex",
+            rootPath: path.join(homePath, ".codex", "skills", "projects", projectName),
+        },
+        {
+            provider: "cursor",
+            rootPath: path.join(homePath, ".cursor", "projects", encodeProjectPathForCursor(projectPath), "rules"),
+        },
+        {
+            provider: "claude",
+            rootPath: path.join(homePath, ".claude", "projects", encodeProjectPathForClaude(projectPath), "skills"),
+        },
+    ];
+};
+export const discoverProviderProjectGuidance = async (projectPath) => {
+    const discoveredSources = [];
+    for (const candidate of getCandidateRoots(projectPath)) {
+        if (!(await pathExists(candidate.rootPath))) {
+            continue;
+        }
+        discoveredSources.push({
+            provider: candidate.provider,
+            entryType: "directory",
+            path: candidate.rootPath,
+            relativePath: toHomeRelativePath(candidate.rootPath),
+        });
+        const nestedFilePaths = await listFilesRecursively(candidate.rootPath);
+        for (const nestedFilePath of nestedFilePaths) {
+            discoveredSources.push({
+                provider: candidate.provider,
+                entryType: "file",
+                path: nestedFilePath,
+                relativePath: toHomeRelativePath(nestedFilePath),
+            });
+        }
+    }
+    return discoveredSources.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+};

package/dist/core/providers/providerRegistry.js

@@ -0,0 +1,51 @@
+import { access } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { installClaudeCodeIntegration } from "../../integrations/claudeCode/install.js";
+import { installCodexIntegration } from "../../integrations/codex/install.js";
+import { installCursorIntegration } from "../../integrations/cursor/install.js";
+import { PROVIDER_IDS } from "../bank/types.js";
+const pathExists = async (targetPath) => {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const isCursorEnvironmentAvailable = async () => (await pathExists(path.join(os.homedir(), ".cursor"))) ||
+    (await pathExists(path.join(os.homedir(), "Library", "Application Support", "Cursor")));
+export const PROVIDER_DEFINITIONS = [
+    {
+        id: "codex",
+        displayName: "Codex",
+        cliCommand: "codex",
+        unavailableMessage: "Codex CLI was not found on PATH.",
+        install: installCodexIntegration,
+    },
+    {
+        id: "cursor",
+        displayName: "Cursor",
+        cliCommand: "cursor",
+        unavailableMessage: "Cursor local configuration directories were not found.",
+        isAvailable: isCursorEnvironmentAvailable,
+        install: installCursorIntegration,
+    },
+    {
+        id: "claude-code",
+        displayName: "Claude Code",
+        cliCommand: "claude",
+        unavailableMessage: "Claude Code CLI was not found on PATH.",
+        install: installClaudeCodeIntegration,
+    },
+];
+const providerMap = new Map(PROVIDER_DEFINITIONS.map((definition) => [definition.id, definition]));
+export const getProviderDefinition = (providerId) => {
+    const definition = providerMap.get(providerId);
+    if (!definition) {
+        throw new Error(`Unsupported provider: ${providerId}`);
+    }
+    return definition;
+};
+export const isProviderId = (value) => PROVIDER_IDS.includes(value);

package/dist/core/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/stats/statsService.js

@@ -0,0 +1,117 @@
+import path from "node:path";
+import { BankRepository } from "../../storage/bankRepository.js";
+import { resolveBankRoot } from "../../shared/paths.js";
+const incrementCount = (bucket, key) => {
+    bucket[key] = (bucket[key] ?? 0) + 1;
+};
+const isDocumentationEntry = (entryPath) => {
+    const normalizedEntryPath = entryPath.replaceAll("\\", "/").toLowerCase();
+    return normalizedEntryPath.endsWith("/readme.md") || normalizedEntryPath === "readme.md";
+};
+const summarizeEvents = (events, limit) => [...events]
+    .sort((left, right) => right.timestamp.localeCompare(left.timestamp))
+    .slice(0, limit)
+    .map((event) => ({
+    timestamp: event.timestamp,
+    provider: event.provider,
+    tool: event.tool,
+    action: event.action,
+    projectId: event.projectId,
+    projectPath: event.projectPath,
+    sessionRef: event.sessionRef,
+}));
+const summarizeEventsByKey = (events, selector) => {
+    const counts = {};
+    for (const event of events) {
+        incrementCount(counts, selector(event));
+    }
+    return counts;
+};
+const countEntries = async (repository, scope, projectId) => {
+    const rules = await repository.listLayerEntries(scope, "rules", projectId);
+    const skills = await repository.listLayerEntries(scope, "skills", projectId);
+    return {
+        rules: rules.filter((entry) => !isDocumentationEntry(entry.path)).length,
+        skills: skills.filter((entry) => !isDocumentationEntry(entry.path)).length,
+    };
+};
+const resolveProjectFilter = (manifests, projectPath) => {
+    if (!projectPath) {
+        return null;
+    }
+    const resolvedProjectPath = path.resolve(projectPath);
+    return manifests.find((manifest) => path.resolve(manifest.projectPath) === resolvedProjectPath) ?? null;
+};
+export class StatsService {
+    repository;
+    constructor(bankRoot) {
+        this.repository = new BankRepository(resolveBankRoot(bankRoot));
+    }
+    async collect(options) {
+        const latestEventsLimit = options?.latestEventsLimit ?? 10;
+        const manifest = await this.repository.readManifestOptional();
+        if (manifest === null) {
+            throw new Error(`AI Guidance Bank is not initialized at ${this.repository.rootPath}. Run \`gbank init\` first.`);
+        }
+        const projectManifests = await this.repository.listProjectManifests();
+        const auditEvents = await this.repository.readAuditEventsOptional();
+        const sharedEntries = await countEntries(this.repository, "shared");
+        const projectCountsByState = {};
+        for (const projectManifest of projectManifests) {
+            const state = await this.repository.readProjectStateOptional(projectManifest.projectId);
+            incrementCount(projectCountsByState, state?.creationState ?? "unknown");
+        }
+        const matchedProject = resolveProjectFilter(projectManifests, options?.projectPath);
+        let projectStats;
+        if (options?.projectPath) {
+            if (matchedProject === null) {
+                throw new Error(`No project bank found for ${path.resolve(options.projectPath)}.`);
+            }
+            const projectState = await this.repository.readProjectStateOptional(matchedProject.projectId);
+            const projectEntries = await countEntries(this.repository, "project", matchedProject.projectId);
+            const projectEvents = auditEvents.filter((event) => event.projectId === matchedProject.projectId);
+            projectStats = {
+                projectId: matchedProject.projectId,
+                projectName: matchedProject.projectName,
+                projectPath: matchedProject.projectPath,
+                detectedStacks: matchedProject.detectedStacks,
+                creationState: projectState?.creationState ?? "unknown",
+                updatedAt: projectState?.updatedAt ?? matchedProject.updatedAt,
+                entries: projectEntries,
+                audit: {
+                    totalEvents: projectEvents.length,
+                    latestEvents: summarizeEvents(projectEvents, latestEventsLimit),
+                    byTool: summarizeEventsByKey(projectEvents, (event) => event.tool),
+                    byProvider: summarizeEventsByKey(projectEvents, (event) => event.provider ?? "unknown"),
+                },
+            };
+        }
+        return {
+            bankRoot: this.repository.rootPath,
+            manifest: {
+                bankId: manifest.bankId,
+                storageVersion: manifest.storageVersion,
+                createdAt: manifest.createdAt,
+                updatedAt: manifest.updatedAt,
+                enabledProviders: manifest.enabledProviders,
+                defaultMcpTransport: manifest.defaultMcpTransport,
+            },
+            sharedEntries,
+            projects: {
+                total: projectManifests.length,
+                byCreationState: projectCountsByState,
+            },
+            audit: {
+                totalEvents: auditEvents.length,
+                byTool: summarizeEventsByKey(auditEvents, (event) => event.tool),
+                byProvider: summarizeEventsByKey(auditEvents, (event) => event.provider ?? "unknown"),
+                latestEvents: summarizeEvents(auditEvents, latestEventsLimit),
+            },
+            ...(projectStats
+                ? {
+                    project: projectStats,
+                }
+                : {}),
+        };
+    }
+}

package/dist/core/sync/syncService.js

@@ -0,0 +1,145 @@
+import { parseCanonicalRuleDocument, parseCanonicalSkillDocument } from "../bank/canonicalEntry.js";
+import { createProjectBankState, markProjectBankSynced, postponeProjectBankSync, updateProjectBankManifest, } from "../bank/project.js";
+import { detectProjectContext } from "../context/detectProjectContext.js";
+import { resolveProjectIdentity } from "../projects/identity.js";
+import { BankRepository } from "../../storage/bankRepository.js";
+import { ValidationError } from "../../shared/errors.js";
+import { resolveBankRoot } from "../../shared/paths.js";
+const isDocumentationFile = (entryPath) => {
+    const normalizedEntryPath = entryPath.replaceAll("\\", "/").toLowerCase();
+    return normalizedEntryPath.endsWith("/readme.md") || normalizedEntryPath === "readme.md";
+};
+const validateLayer = async (repository, layer, kind, projectId) => {
+    const entries = await repository.listLayerEntries(layer, kind, projectId);
+    let validatedCount = 0;
+    for (const entry of entries) {
+        if (isDocumentationFile(entry.path)) {
+            continue;
+        }
+        const content = await repository.readLayerEntry(layer, kind, entry.path, projectId);
+        try {
+            if (kind === "rules") {
+                parseCanonicalRuleDocument(content);
+            }
+            else {
+                parseCanonicalSkillDocument(content);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown canonical entry parsing error.";
+            throw new ValidationError(`Invalid canonical ${kind.slice(0, -1)} at ${layer}/${entry.path}: ${message}`);
+        }
+        validatedCount += 1;
+    }
+    return validatedCount;
+};
+export class SyncService {
+    async run(options) {
+        const bankRoot = resolveBankRoot(options.bankRoot);
+        const repository = new BankRepository(bankRoot);
+        const manifest = await repository.readManifestOptional();
+        if (manifest === null) {
+            throw new ValidationError("AI Guidance Bank is not initialized yet. Run gbank init first.");
+        }
+        const identity = resolveProjectIdentity(options.projectPath);
+        const projectContext = await detectProjectContext(identity.projectPath);
+        const projectManifest = await repository.readProjectManifestOptional(identity.projectId);
+        const projectState = await repository.readProjectStateOptional(identity.projectId);
+        const sharedRules = await validateLayer(repository, "shared", "rules");
+        const sharedSkills = await validateLayer(repository, "shared", "skills");
+        const projectRules = projectManifest !== null ? await validateLayer(repository, "project", "rules", identity.projectId) : 0;
+        const projectSkills = projectManifest !== null ? await validateLayer(repository, "project", "skills", identity.projectId) : 0;
+        let projectManifestUpdated = false;
+        if (projectManifest !== null) {
+            const nextDetectedStacks = [...projectContext.detectedStacks];
+            const currentDetectedStacks = [...projectManifest.detectedStacks];
+            const stacksChanged = nextDetectedStacks.length !== currentDetectedStacks.length ||
+                nextDetectedStacks.some((stack, index) => stack !== currentDetectedStacks[index]);
+            if (stacksChanged) {
+                await repository.writeProjectManifest(identity.projectId, updateProjectBankManifest(projectManifest, projectContext.detectedStacks));
+                projectManifestUpdated = true;
+            }
+        }
+        if (projectManifest !== null) {
+            const nextProjectState = markProjectBankSynced(projectState ?? createProjectBankState("ready"), manifest.storageVersion);
+            await repository.writeProjectState(identity.projectId, nextProjectState);
+            return {
+                action: "run",
+                bankRoot,
+                projectPath: identity.projectPath,
+                detectedStacks: projectContext.detectedStacks,
+                projectState: nextProjectState.creationState,
+                postponedUntil: nextProjectState.postponedUntil,
+                projectManifestUpdated,
+                validatedEntries: {
+                    shared: {
+                        rules: sharedRules,
+                        skills: sharedSkills,
+                    },
+                    project: {
+                        rules: projectRules,
+                        skills: projectSkills,
+                    },
+                },
+                externalGuidanceSources: projectContext.localGuidance,
+            };
+        }
+        return {
+            action: "run",
+            bankRoot,
+            projectPath: identity.projectPath,
+            detectedStacks: projectContext.detectedStacks,
+            projectState: projectState?.creationState ?? "unknown",
+            postponedUntil: projectState?.postponedUntil ?? null,
+            projectManifestUpdated,
+            validatedEntries: {
+                shared: {
+                    rules: sharedRules,
+                    skills: sharedSkills,
+                },
+                project: {
+                    rules: projectRules,
+                    skills: projectSkills,
+                },
+            },
+            externalGuidanceSources: projectContext.localGuidance,
+        };
+    }
+    async postpone(options) {
+        const bankRoot = resolveBankRoot(options.bankRoot);
+        const repository = new BankRepository(bankRoot);
+        const manifest = await repository.readManifestOptional();
+        if (manifest === null) {
+            throw new ValidationError("AI Guidance Bank is not initialized yet. Run gbank init first.");
+        }
+        const identity = resolveProjectIdentity(options.projectPath);
+        const projectContext = await detectProjectContext(identity.projectPath);
+        const projectManifest = await repository.readProjectManifestOptional(identity.projectId);
+        if (projectManifest === null) {
+            throw new ValidationError("Project AI Guidance Bank does not exist yet. Call create_bank before postponing sync.");
+        }
+        const projectState = await repository.readProjectStateOptional(identity.projectId);
+        const nextProjectState = postponeProjectBankSync(projectState ?? createProjectBankState("ready"), 1);
+        await repository.writeProjectState(identity.projectId, nextProjectState);
+        return {
+            action: "postpone",
+            bankRoot,
+            projectPath: identity.projectPath,
+            detectedStacks: projectContext.detectedStacks,
+            projectState: nextProjectState.creationState,
+            postponedUntil: nextProjectState.postponedUntil,
+            projectManifestUpdated: false,
+            validatedEntries: {
+                shared: {
+                    rules: 0,
+                    skills: 0,
+                },
+                project: {
+                    rules: 0,
+                    skills: 0,
+                },
+            },
+            externalGuidanceSources: projectContext.localGuidance,
+        };
+    }
+}

package/dist/core/sync/syncTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/core/upgrade/upgradeService.js

@@ -0,0 +1,134 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { InitService } from "../init/initService.js";
+import { BankRepository } from "../../storage/bankRepository.js";
+import { ValidationError } from "../../shared/errors.js";
+import { BANK_DIRECTORY_NAME, LEGACY_BANK_DIRECTORY_NAMES, resolveBankRoot } from "../../shared/paths.js";
+import { CURRENT_STORAGE_VERSION } from "../bank/types.js";
+import { isCurrentStorageVersion, updateManifest } from "../bank/manifest.js";
+const resolveLegacyBankRoots = (bankRoot) => {
+    const resolvedBankRoot = path.resolve(bankRoot);
+    if (path.basename(resolvedBankRoot) !== BANK_DIRECTORY_NAME) {
+        return [];
+    }
+    return LEGACY_BANK_DIRECTORY_NAMES.map((directoryName) => path.join(path.dirname(resolvedBankRoot), directoryName));
+};
+const moveBankRoot = async (sourceRoot, targetRoot) => {
+    if (sourceRoot === targetRoot) {
+        return;
+    }
+    try {
+        await fs.access(targetRoot);
+        throw new ValidationError(`Cannot upgrade AI Guidance Bank into an existing path: ${targetRoot}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    await fs.mkdir(path.dirname(targetRoot), { recursive: true });
+    try {
+        await fs.rename(sourceRoot, targetRoot);
+    }
+    catch (error) {
+        if (error.code !== "EXDEV") {
+            throw error;
+        }
+        await fs.cp(sourceRoot, targetRoot, { recursive: true });
+        await fs.rm(sourceRoot, { recursive: true, force: true });
+    }
+};
+export const detectBankUpgrade = async (bankRoot) => {
+    const resolvedBankRoot = resolveBankRoot(bankRoot);
+    const repository = new BankRepository(resolvedBankRoot);
+    const manifest = await repository.readManifestOptional();
+    if (manifest !== null) {
+        if (isCurrentStorageVersion(manifest.storageVersion)) {
+            return {
+                status: "up_to_date",
+                bankRoot: resolvedBankRoot,
+                manifest,
+                expectedStorageVersion: CURRENT_STORAGE_VERSION,
+            };
+        }
+        return {
+            status: "upgrade_required",
+            bankRoot: resolvedBankRoot,
+            sourceRoot: resolvedBankRoot,
+            manifest,
+            expectedStorageVersion: CURRENT_STORAGE_VERSION,
+            reason: "storage_version",
+        };
+    }
+    const legacyMatches = [];
+    for (const legacyBankRoot of resolveLegacyBankRoots(resolvedBankRoot)) {
+        const legacyRepository = new BankRepository(legacyBankRoot);
+        const legacyManifest = await legacyRepository.readManifestOptional();
+        if (legacyManifest !== null) {
+            legacyMatches.push({ legacyBankRoot, manifest: legacyManifest });
+        }
+    }
+    if (legacyMatches.length > 1) {
+        throw new ValidationError(`Multiple legacy AI Guidance Bank roots were found: ${legacyMatches.map(({ legacyBankRoot }) => legacyBankRoot).join(", ")}. Resolve them manually before upgrading.`);
+    }
+    if (legacyMatches.length === 1) {
+        const legacyMatch = legacyMatches[0];
+        return {
+            status: "upgrade_required",
+            bankRoot: resolvedBankRoot,
+            sourceRoot: legacyMatch.legacyBankRoot,
+            manifest: legacyMatch.manifest,
+            expectedStorageVersion: CURRENT_STORAGE_VERSION,
+            reason: "legacy_root",
+        };
+    }
+    return {
+        status: "not_initialized",
+        bankRoot: resolvedBankRoot,
+        expectedStorageVersion: CURRENT_STORAGE_VERSION,
+    };
+};
+export class UpgradeService {
+    async run(options) {
+        const detection = await detectBankUpgrade(options?.bankRoot);
+        if (detection.status === "not_initialized") {
+            throw new ValidationError(`AI Guidance Bank is not initialized yet. Run \`gbank init\` first.`);
+        }
+        if (detection.status === "up_to_date") {
+            return {
+                status: "already_current",
+                bankRoot: detection.bankRoot,
+                sourceRoot: detection.bankRoot,
+                migratedBankRoot: false,
+                previousStorageVersion: detection.manifest.storageVersion,
+                storageVersion: detection.manifest.storageVersion,
+                enabledProviders: detection.manifest.enabledProviders,
+            };
+        }
+        if (detection.reason === "legacy_root") {
+            await moveBankRoot(detection.sourceRoot, detection.bankRoot);
+        }
+        const repository = new BankRepository(detection.bankRoot);
+        const manifestBeforeUpgrade = await repository.readManifest();
+        const initService = new InitService();
+        await initService.run({
+            bankRoot: detection.bankRoot,
+            selectedProviders: manifestBeforeUpgrade.enabledProviders,
+            ...(options?.cursorConfigRoot ? { cursorConfigRoot: options.cursorConfigRoot } : {}),
+            ...(options?.commandRunner ? { commandRunner: options.commandRunner } : {}),
+        });
+        await repository.writeManifest(updateManifest(manifestBeforeUpgrade, manifestBeforeUpgrade.enabledProviders, new Date(), {
+            storageVersion: CURRENT_STORAGE_VERSION,
+        }));
+        const upgradedManifest = await repository.readManifest();
+        return {
+            status: "upgraded",
+            bankRoot: detection.bankRoot,
+            sourceRoot: detection.sourceRoot,
+            migratedBankRoot: detection.sourceRoot !== detection.bankRoot,
+            previousStorageVersion: detection.manifest.storageVersion,
+            storageVersion: upgradedManifest.storageVersion,
+            enabledProviders: upgradedManifest.enabledProviders,
+        };
+    }
+}