@morsa/guidance-bank 0.2.0

package/dist/core/context/detectProjectContext.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import {} from "./types.js";
+const stackOrder = new Map(["nodejs", "typescript", "react", "nextjs", "angular", "ios", "other"].map((stack, index) => [
+    stack,
+    index,
+]));
+const pathExists = async (targetPath) => {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const readJsonFileIfExists = async (filePath) => {
+    if (!(await pathExists(filePath))) {
+        return null;
+    }
+    const content = await fs.readFile(filePath, "utf8");
+    return JSON.parse(content);
+};
+const directoryEntriesIfExists = async (directoryPath) => {
+    try {
+        return await fs.readdir(directoryPath);
+    }
+    catch {
+        return [];
+    }
+};
+const addStack = (stacks, signals, stack, source) => {
+    if (stacks.has(stack)) {
+        return;
+    }
+    stacks.add(stack);
+    signals.push({
+        name: stack,
+        source,
+    });
+};
+export const detectProjectContext = async (cwd) => {
+    const resolvedCwd = path.resolve(cwd);
+    const stacks = new Set();
+    const signals = [];
+    const localGuidance = [];
+    const packageJson = await readJsonFileIfExists(path.join(resolvedCwd, "package.json"));
+    const tsconfigExists = await pathExists(path.join(resolvedCwd, "tsconfig.json"));
+    const angularConfigExists = await pathExists(path.join(resolvedCwd, "angular.json"));
+    const nextConfigExists = (await pathExists(path.join(resolvedCwd, "next.config.js"))) ||
+        (await pathExists(path.join(resolvedCwd, "next.config.mjs"))) ||
+        (await pathExists(path.join(resolvedCwd, "next.config.ts")));
+    const packageSwiftExists = await pathExists(path.join(resolvedCwd, "Package.swift"));
+    const podfileExists = await pathExists(path.join(resolvedCwd, "Podfile"));
+    const rootDirectoryEntries = await directoryEntriesIfExists(resolvedCwd);
+    const xcodeProjectExists = rootDirectoryEntries.some((entry) => entry.endsWith(".xcodeproj"));
+    const xcodeWorkspaceExists = rootDirectoryEntries.some((entry) => entry.endsWith(".xcworkspace"));
+    const dependencies = {
+        ...(packageJson?.dependencies ?? {}),
+        ...(packageJson?.devDependencies ?? {}),
+    };
+    if (packageJson) {
+        addStack(stacks, signals, "nodejs", "package.json");
+    }
+    if (tsconfigExists || "typescript" in dependencies) {
+        addStack(stacks, signals, "typescript", tsconfigExists ? "tsconfig.json" : "package.json");
+    }
+    if (angularConfigExists || "@angular/core" in dependencies) {
+        addStack(stacks, signals, "angular", angularConfigExists ? "angular.json" : "package.json");
+        addStack(stacks, signals, "typescript", angularConfigExists ? "angular.json" : "package.json");
+        addStack(stacks, signals, "nodejs", angularConfigExists ? "angular.json" : "package.json");
+    }
+    if (nextConfigExists || "next" in dependencies) {
+        addStack(stacks, signals, "nextjs", nextConfigExists ? "next.config.*" : "package.json");
+        addStack(stacks, signals, "react", nextConfigExists ? "next.config.*" : "package.json");
+        addStack(stacks, signals, "nodejs", nextConfigExists ? "next.config.*" : "package.json");
+    }
+    if ("react" in dependencies) {
+        addStack(stacks, signals, "react", "package.json");
+        addStack(stacks, signals, "nodejs", "package.json");
+    }
+    if (packageSwiftExists || podfileExists || xcodeProjectExists || xcodeWorkspaceExists) {
+        const iosSource = packageSwiftExists
+            ? "Package.swift"
+            : podfileExists
+                ? "Podfile"
+                : xcodeProjectExists
+                    ? "*.xcodeproj"
+                    : "*.xcworkspace";
+        addStack(stacks, signals, "ios", iosSource);
+    }
+    const localGuidanceCandidates = [
+        { kind: "agents", relativePath: "AGENTS.md" },
+        { kind: "cursor", relativePath: ".cursor" },
+        { kind: "claude", relativePath: ".claude" },
+        { kind: "codex", relativePath: ".codex" },
+    ];
+    for (const candidate of localGuidanceCandidates) {
+        const candidatePath = path.join(resolvedCwd, candidate.relativePath);
+        if (await pathExists(candidatePath)) {
+            localGuidance.push({
+                kind: candidate.kind,
+                path: candidatePath,
+            });
+        }
+    }
+    if (stacks.size === 0) {
+        addStack(stacks, signals, "other", "fallback");
+    }
+    const detectedStacks = [...stacks].sort((left, right) => (stackOrder.get(left) ?? 0) - (stackOrder.get(right) ?? 0));
+    return {
+        projectName: path.basename(resolvedCwd),
+        projectPath: resolvedCwd,
+        detectedStacks,
+        detectedSignals: signals,
+        localGuidance,
+    };
+};

package/dist/core/context/resolveContextService.js

@@ -0,0 +1,138 @@
+import { getProjectBankContinuationIteration, isProjectBankPostponedUntilActive, resolveProjectBankLifecycleStatus, } from "../bank/lifecycle.js";
+import { detectBankUpgrade } from "../upgrade/upgradeService.js";
+import { detectProjectContext } from "./detectProjectContext.js";
+import { findReferenceProjects } from "../projects/findReferenceProjects.js";
+import { getCreateFlowPhase } from "../projects/createFlowPhases.js";
+import { resolveProjectIdentity } from "../projects/identity.js";
+import { assertUniqueResolvedEntryIds, buildResolvedContextCatalog, excludeAlwaysOnRules, loadResolvedContextEntries, mergeResolvedLayerEntries, selectAlwaysOnRules, } from "./contextEntryResolver.js";
+import { buildCreatingContextText, buildDeclinedContextText, buildMissingContextText, buildReadyContextText, buildSharedFallbackContextText, buildSyncRequiredContextText, buildUpgradeRequiredContextText, } from "./contextTextRenderer.js";
+import { ValidationError } from "../../shared/errors.js";
+export const resolveGuidanceBankContext = async ({ repository, projectPath, }) => {
+    const identity = resolveProjectIdentity(projectPath);
+    const bankUpgrade = await detectBankUpgrade(repository.rootPath);
+    if (bankUpgrade.status === "not_initialized") {
+        throw new ValidationError(`AI Guidance Bank is not initialized yet. Run \`gbank init\` first.`);
+    }
+    if (bankUpgrade.status === "upgrade_required") {
+        return {
+            text: buildUpgradeRequiredContextText({
+                bankRoot: bankUpgrade.bankRoot,
+                sourceRoot: bankUpgrade.sourceRoot,
+                storageVersion: bankUpgrade.manifest.storageVersion,
+                expectedStorageVersion: bankUpgrade.expectedStorageVersion,
+            }),
+            requiredAction: "upgrade_bank",
+            bankRoot: bankUpgrade.bankRoot,
+            sourceRoot: bankUpgrade.sourceRoot,
+            storageVersion: bankUpgrade.manifest.storageVersion,
+            expectedStorageVersion: bankUpgrade.expectedStorageVersion,
+        };
+    }
+    const manifest = bankUpgrade.manifest;
+    const detectedProjectContext = await detectProjectContext(identity.projectPath);
+    const projectManifest = await repository.readProjectManifestOptional(identity.projectId);
+    const projectState = await repository.readProjectStateOptional(identity.projectId);
+    const status = resolveProjectBankLifecycleStatus({
+        projectManifest,
+        projectState,
+        expectedStorageVersion: manifest.storageVersion,
+    });
+    if (status === "sync_required") {
+        return {
+            text: buildSyncRequiredContextText({
+                postponedUntil: projectState?.postponedUntil ?? null,
+            }),
+            creationState: projectState?.creationState ?? "ready",
+            requiredAction: "sync_bank",
+        };
+    }
+    if (status === "creation_declined") {
+        return {
+            text: buildDeclinedContextText(),
+            creationState: "declined",
+        };
+    }
+    if (status === "missing") {
+        const referenceProjects = await findReferenceProjects({
+            repository,
+            currentProjectId: identity.projectId,
+            detectedStacks: detectedProjectContext.detectedStacks,
+        });
+        const isCreateReminderPostponed = projectState?.creationState === "postponed" && isProjectBankPostponedUntilActive(projectState);
+        const creationState = isCreateReminderPostponed ? "postponed" : "unknown";
+        const sharedRules = await loadResolvedContextEntries(repository, "shared", "rules", detectedProjectContext.detectedStacks);
+        const sharedSkills = await loadResolvedContextEntries(repository, "shared", "skills", detectedProjectContext.detectedStacks);
+        assertUniqueResolvedEntryIds(sharedRules, "shared", "rules");
+        assertUniqueResolvedEntryIds(sharedSkills, "shared", "skills");
+        const alwaysOnRules = selectAlwaysOnRules(sharedRules);
+        const rulesCatalog = buildResolvedContextCatalog("rules", excludeAlwaysOnRules(sharedRules));
+        const skillsCatalog = buildResolvedContextCatalog("skills", sharedSkills);
+        const text = buildMissingContextText({
+            referenceProjectPaths: referenceProjects.map((project) => project.projectPath),
+            creationState,
+            postponedUntil: isCreateReminderPostponed ? projectState?.postponedUntil ?? null : null,
+            sharedContextText: buildSharedFallbackContextText({
+                projectPath: identity.projectPath,
+                detectedStacks: detectedProjectContext.detectedStacks,
+                alwaysOnRules,
+                rulesCatalog,
+                skillsCatalog,
+            }),
+        });
+        const missingContextBase = {
+            text,
+            creationState: creationState,
+            detectedStacks: [...detectedProjectContext.detectedStacks],
+            rulesCatalog,
+            skillsCatalog,
+            ...(isCreateReminderPostponed ? { postponedUntil: projectState?.postponedUntil ?? null } : {}),
+            ...(!isCreateReminderPostponed ? { recommendedAction: "create_bank" } : {}),
+        };
+        return referenceProjects.length > 0
+            ? {
+                ...missingContextBase,
+                referenceProjects,
+            }
+            : missingContextBase;
+    }
+    if (status === "creation_in_progress") {
+        const nextIteration = getProjectBankContinuationIteration(projectState);
+        const createFlowPhase = getCreateFlowPhase(nextIteration);
+        return {
+            text: buildCreatingContextText({
+                phase: createFlowPhase,
+                nextIteration,
+            }),
+            creationState: "creating",
+            requiredAction: "continue_create_bank",
+            createFlowPhase,
+            nextIteration,
+        };
+    }
+    const sharedRules = await loadResolvedContextEntries(repository, "shared", "rules", detectedProjectContext.detectedStacks);
+    const sharedSkills = await loadResolvedContextEntries(repository, "shared", "skills", detectedProjectContext.detectedStacks);
+    const projectRules = await loadResolvedContextEntries(repository, "project", "rules", detectedProjectContext.detectedStacks, identity.projectId);
+    const projectSkills = await loadResolvedContextEntries(repository, "project", "skills", detectedProjectContext.detectedStacks, identity.projectId);
+    assertUniqueResolvedEntryIds(sharedRules, "shared", "rules");
+    assertUniqueResolvedEntryIds(sharedSkills, "shared", "skills");
+    assertUniqueResolvedEntryIds(projectRules, "project", "rules");
+    assertUniqueResolvedEntryIds(projectSkills, "project", "skills");
+    const mergedRules = mergeResolvedLayerEntries(sharedRules, projectRules);
+    const mergedSkills = mergeResolvedLayerEntries(sharedSkills, projectSkills);
+    const alwaysOnRules = selectAlwaysOnRules(mergedRules);
+    const rulesCatalog = buildResolvedContextCatalog("rules", excludeAlwaysOnRules(mergedRules));
+    const skillsCatalog = buildResolvedContextCatalog("skills", mergedSkills);
+    return {
+        text: buildReadyContextText({
+            projectPath: identity.projectPath,
+            detectedStacks: detectedProjectContext.detectedStacks,
+            alwaysOnRules,
+            rulesCatalog,
+            skillsCatalog,
+        }),
+        creationState: "ready",
+        detectedStacks: detectedProjectContext.detectedStacks,
+        rulesCatalog,
+        skillsCatalog,
+    };
+};

package/dist/core/context/types.js

@@ -0,0 +1 @@
+export const DETECTABLE_STACKS = ["nodejs", "typescript", "react", "nextjs", "angular", "ios", "other"];

package/dist/core/init/initService.js

@@ -0,0 +1,112 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { createManifest, sortProviders, updateManifest } from "../bank/manifest.js";
+import { CURRENT_STORAGE_VERSION } from "../bank/types.js";
+import { getProviderDefinition } from "../providers/providerRegistry.js";
+import { BankRepository } from "../../storage/bankRepository.js";
+import { BANK_DIRECTORY_NAME, LEGACY_BANK_DIRECTORY_NAMES, resolveBankRoot } from "../../shared/paths.js";
+import { createDefaultMcpServerConfig } from "../../mcp/config.js";
+import { ensureMcpLauncher } from "../../mcp/launcher.js";
+import { runCommand } from "../../integrations/commandRunner.js";
+import { ValidationError } from "../../shared/errors.js";
+const assertSelectedProviders = (providerIds) => {
+    const normalizedProviders = sortProviders(providerIds);
+    if (normalizedProviders.length === 0) {
+        throw new ValidationError("At least one provider must be selected during init.");
+    }
+    return normalizedProviders;
+};
+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 migrate 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 class InitService {
+    async run(options) {
+        const selectedProviders = assertSelectedProviders(options.selectedProviders);
+        const bankRoot = resolveBankRoot(options.bankRoot);
+        const commandRunner = options.commandRunner ?? runCommand;
+        const legacyBankRoots = resolveLegacyBankRoots(bankRoot);
+        const repository = new BankRepository(bankRoot);
+        const existingManifestBeforeInit = await repository.readManifestOptional();
+        if (existingManifestBeforeInit === null && legacyBankRoots.length > 0) {
+            const legacyMatches = [];
+            for (const legacyBankRoot of legacyBankRoots) {
+                const legacyRepository = new BankRepository(legacyBankRoot);
+                const legacyManifest = await legacyRepository.readManifestOptional();
+                if (legacyManifest !== null) {
+                    legacyMatches.push(legacyBankRoot);
+                }
+            }
+            if (legacyMatches.length > 1) {
+                throw new ValidationError(`Multiple legacy AI Guidance Bank roots were found: ${legacyMatches.join(", ")}. Resolve them manually before running \`gbank init\`.`);
+            }
+            if (legacyMatches.length === 1) {
+                await moveBankRoot(legacyMatches[0], bankRoot);
+            }
+        }
+        await repository.ensureStructure();
+        await repository.ensureStarterFiles();
+        const existingManifest = await repository.readManifestOptional();
+        const enabledProviders = sortProviders([
+            ...(existingManifest?.enabledProviders ?? []),
+            ...selectedProviders,
+        ]);
+        const manifest = existingManifest
+            ? updateManifest(existingManifest, enabledProviders, new Date(), { storageVersion: CURRENT_STORAGE_VERSION })
+            : createManifest(enabledProviders);
+        const mcpServerConfig = createDefaultMcpServerConfig(bankRoot);
+        await ensureMcpLauncher(bankRoot);
+        await repository.writeManifest(manifest);
+        await repository.writeMcpServerConfig(mcpServerConfig);
+        const integrations = [];
+        for (const providerId of enabledProviders) {
+            const existingDescriptor = await repository.readProviderIntegrationOptional(providerId);
+            const integration = await getProviderDefinition(providerId).install({
+                bankRoot,
+                commandRunner,
+                existingDescriptor,
+                mcpServerConfig,
+                ...(options.cursorConfigRoot ? { cursorConfigRoot: options.cursorConfigRoot } : {}),
+            });
+            integrations.push(integration);
+        }
+        for (const integration of integrations) {
+            await repository.writeProviderIntegration(integration.descriptor.provider, integration.descriptor);
+        }
+        return {
+            bankRoot,
+            alreadyExisted: existingManifest !== null,
+            manifest,
+            mcpServerConfig,
+            integrations,
+        };
+    }
+}

package/dist/core/init/initTypes.js

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

package/dist/core/projects/createBankDeriveGuidance/index.js

@@ -0,0 +1,47 @@
+import { ANGULAR_DERIVE_GUIDANCE } from "./stacks/angular.js";
+import { IOS_DERIVE_GUIDANCE } from "./stacks/ios.js";
+import { NEXTJS_DERIVE_GUIDANCE } from "./stacks/nextjs.js";
+import { NODEJS_DERIVE_GUIDANCE } from "./stacks/nodejs.js";
+import { OTHER_DERIVE_GUIDANCE } from "./stacks/other.js";
+import { REACT_DERIVE_GUIDANCE } from "./stacks/react.js";
+import { GENERAL_DERIVE_GUIDANCE } from "./shared/general.js";
+import { TYPESCRIPT_DERIVE_GUIDANCE } from "./shared/typescript.js";
+const STACK_GUIDANCE_MODULES = [
+    { stack: "typescript", prompt: TYPESCRIPT_DERIVE_GUIDANCE },
+    { stack: "nextjs", prompt: NEXTJS_DERIVE_GUIDANCE },
+    { stack: "react", prompt: REACT_DERIVE_GUIDANCE },
+    { stack: "angular", prompt: ANGULAR_DERIVE_GUIDANCE },
+    { stack: "nodejs", prompt: NODEJS_DERIVE_GUIDANCE },
+    { stack: "ios", prompt: IOS_DERIVE_GUIDANCE },
+    { stack: "other", prompt: OTHER_DERIVE_GUIDANCE },
+];
+const RECOMMENDED_OUTPUT_SHAPE = `## Recommended Output Shape
+
+Aim for a right-sized bank, not a minimal placeholder:
+- 2-6 focused rule files when project evidence supports them
+- 2-5 focused skills when reusable workflows are clearly present
+- for small or low-confidence projects, prefer fewer high-value entries over quota-filling
+- do not stop at a thin summary when the repository clearly supports more
+
+Common high-value starting points when evidence supports them:
+- core/general
+- architecture
+- one stack- or workflow-specific topic
+- adding-feature
+- adding-service
+- code-review
+- task-based-reading or troubleshooting
+
+Before concluding derive/finalize:
+- review the strongest missing rule and skill candidates
+- either create them, merge them into clearer existing entries, or record a skip reason`;
+export const renderCreateDeriveGuidance = (detectedStacks) => {
+    const sections = [GENERAL_DERIVE_GUIDANCE];
+    for (const module of STACK_GUIDANCE_MODULES) {
+        if (detectedStacks.includes(module.stack)) {
+            sections.push(module.prompt);
+        }
+    }
+    sections.push(RECOMMENDED_OUTPUT_SHAPE);
+    return sections.join("\n\n");
+};

package/dist/core/projects/createBankDeriveGuidance/shared/general.js

@@ -0,0 +1,49 @@
+export const GENERAL_DERIVE_GUIDANCE = `## General Analysis Contract
+
+Before generating or updating AI Guidance Bank entries:
+- Explore the codebase thoroughly before writing
+- Prefer project evidence over assumptions
+- Generate project-specific rules, not generic copies
+- Deduplicate candidate rules before writing
+- Keep one clear formulation per rule
+
+## Rule Quality Gate
+
+Create or keep a rule only when at least one is true:
+- The pattern appears repeatedly in the codebase
+- The pattern is encoded in configuration or tooling
+- The pattern is documented and reflected in project structure
+- The pattern is clearly part of the intended architecture
+
+For each candidate rule, decide explicitly:
+- keep: clear evidence and practical value
+- skip: weak evidence or low value
+- [VERIFY: ...]: partial evidence and the decision can affect workflow
+
+Safety constraints:
+- Prefer rules that reinforce established project workflow over idealized rewrites
+- If a rule may disrupt team workflow and evidence is weak, skip it
+- If confidence is low for a high-impact decision, use [VERIFY: ...] or ask the user
+
+## Skills Quality Gate
+
+Generate a skill only when it represents a reusable multi-step workflow with clear project evidence.
+
+Each skill should include:
+- When to use
+- Prerequisites
+- Step-by-step workflow with real project paths
+- Do not / anti-patterns when relevant
+
+If you generate a reading/index-oriented skill:
+- do not output only a static file list
+- include conditional routing logic for common task categories
+- keep routing concise and directly actionable
+
+## Testing Rules Gate
+
+Before generating testing rules:
+- assess how developed testing actually is in this project
+- if testing is minimal, do not force broad coverage rules
+- add testing rules only when they match actual project practice or explicit user intent
+- prefer realistic incremental guidance over idealized requirements`;

package/dist/core/projects/createBankDeriveGuidance/shared/typescript.js

@@ -0,0 +1,18 @@
+export const TYPESCRIPT_DERIVE_GUIDANCE = `## TypeScript Evidence Gate
+
+Apply this only when TypeScript is actually present.
+
+Verify from project evidence:
+- tsconfig strictness profile
+- alias/import strategy and whether boundaries rely on aliases
+- type boundaries between transport, domain, and UI/view models
+- async and error typing patterns
+- runtime validation boundaries for external input
+
+Promote to rules only when repeated:
+- broad any / as any usage without narrowing strategy
+- unsafe assertion chains
+- non-null assertions across async or API boundaries without safety checks
+- inconsistent typing patterns for the same domain entities
+
+Preserve detected strictness and alias strategy. Do not introduce unsafe typing shortcuts as defaults.`;