@morsa/guidance-bank 0.2.0

package/dist/shared/errors.js

@@ -0,0 +1,18 @@
+export class GuidanceBankCliError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GuidanceBankCliError";
+    }
+}
+export class ValidationError extends GuidanceBankCliError {
+    constructor(message) {
+        super(message);
+        this.name = "ValidationError";
+    }
+}
+export class UserInputError extends GuidanceBankCliError {
+    constructor(message) {
+        super(message);
+        this.name = "UserInputError";
+    }
+}

package/dist/shared/paths.js

@@ -0,0 +1,11 @@
+import os from "node:os";
+import path from "node:path";
+export const BANK_DIRECTORY_NAME = ".guidance-bank";
+export const LEGACY_BANK_DIRECTORY_NAMES = [".guidancebank", ".memory-bank"];
+export const resolveDefaultBankRoot = () => path.join(os.homedir(), BANK_DIRECTORY_NAME);
+export const resolveBankRoot = (overridePath) => {
+    if (!overridePath) {
+        return resolveDefaultBankRoot();
+    }
+    return path.resolve(overridePath);
+};

package/dist/storage/atomicWrite.js

@@ -0,0 +1,15 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export const atomicWriteFile = async (filePath, content) => {
+    const directoryPath = path.dirname(filePath);
+    const temporaryFilePath = path.join(directoryPath, `.${path.basename(filePath)}.${process.pid}.${Date.now().toString(36)}.tmp`);
+    const handle = await fs.open(temporaryFilePath, "wx", 0o600);
+    try {
+        await handle.writeFile(content, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.rename(temporaryFilePath, filePath);
+};

package/dist/storage/auditLogger.js

@@ -0,0 +1,20 @@
+import { randomUUID } from "node:crypto";
+import { resolveBankPaths } from "../core/bank/layout.js";
+import { appendManagedTextFile } from "./safeFs.js";
+export class AuditLogger {
+    options;
+    paths;
+    constructor(options) {
+        this.options = options;
+        this.paths = resolveBankPaths(options.bankRoot);
+    }
+    async writeEvent(event) {
+        await appendManagedTextFile(this.options.bankRoot, this.paths.auditEventsFile, `${JSON.stringify({
+            schemaVersion: 1,
+            eventId: randomUUID(),
+            timestamp: new Date().toISOString(),
+            provider: this.options.provider,
+            ...event,
+        })}\n`);
+    }
+}

package/dist/storage/auditStore.js

@@ -0,0 +1,22 @@
+import { readFile } from "node:fs/promises";
+import { resolveBankPaths } from "../core/bank/layout.js";
+import { managedPathExists } from "./safeFs.js";
+export class AuditStore {
+    rootPath;
+    paths;
+    constructor(rootPath, paths) {
+        this.rootPath = rootPath;
+        this.paths = paths;
+    }
+    async readEventsOptional() {
+        if (!(await managedPathExists(this.rootPath, this.paths.auditEventsFile))) {
+            return [];
+        }
+        const content = await readFile(this.paths.auditEventsFile, "utf8");
+        return content
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map((line) => JSON.parse(line));
+    }
+}

package/dist/storage/bankRepository.js

@@ -0,0 +1,168 @@
+import path from "node:path";
+import { createStarterFiles, resolveBankPaths } from "../core/bank/layout.js";
+import { ensureManagedDirectory, writeManagedTextFileIfMissing, } from "./safeFs.js";
+import { EntryStore } from "./entryStore.js";
+import { ManifestStore } from "./manifestStore.js";
+import { ProjectBankStore } from "./projectBankStore.js";
+import { ProviderIntegrationStore } from "./providerIntegrationStore.js";
+import { AuditStore } from "./auditStore.js";
+export class BankRepository {
+    rootPath;
+    paths;
+    manifestStore;
+    projectBanks;
+    entries;
+    providerIntegrations;
+    auditStore;
+    constructor(rootPath) {
+        this.rootPath = rootPath;
+        this.paths = resolveBankPaths(rootPath);
+        this.manifestStore = new ManifestStore(rootPath, this.paths);
+        this.projectBanks = new ProjectBankStore(rootPath, this.paths);
+        this.entries = new EntryStore(rootPath, this.paths);
+        this.providerIntegrations = new ProviderIntegrationStore(rootPath, this.paths);
+        this.auditStore = new AuditStore(rootPath, this.paths);
+    }
+    // TODO: Multi-agent concurrency is still last-write-wins at the entry level.
+    // Separate `gbank mcp serve` processes can update the same rule or skill concurrently.
+    // Atomic writes protect file integrity, but they do not detect semantic conflicts.
+    // Add revision stamps or optimistic locking before relying on shared concurrent edits.
+    async ensureStructure() {
+        await ensureManagedDirectory(this.rootPath, this.paths.root);
+        await ensureManagedDirectory(this.rootPath, this.paths.sharedDirectory);
+        await ensureManagedDirectory(this.rootPath, this.paths.sharedRulesDirectory);
+        await ensureManagedDirectory(this.rootPath, this.paths.sharedSkillsDirectory);
+        await ensureManagedDirectory(this.rootPath, this.paths.projectsDirectory);
+        await ensureManagedDirectory(this.rootPath, this.paths.mcpDirectory);
+        await ensureManagedDirectory(this.rootPath, this.paths.integrationsDirectory);
+        await ensureManagedDirectory(this.rootPath, path.join(this.paths.sharedRulesDirectory, "core"));
+        await ensureManagedDirectory(this.rootPath, path.join(this.paths.sharedRulesDirectory, "stacks"));
+        await ensureManagedDirectory(this.rootPath, path.join(this.paths.sharedRulesDirectory, "providers"));
+        await ensureManagedDirectory(this.rootPath, path.join(this.paths.sharedRulesDirectory, "topics"));
+    }
+    async ensureStarterFiles() {
+        for (const starterFile of createStarterFiles(this.paths)) {
+            await writeManagedTextFileIfMissing(this.rootPath, starterFile.filePath, starterFile.content);
+        }
+    }
+    async ensureProjectStructure(projectId) {
+        await this.projectBanks.ensureProjectStructure(projectId);
+    }
+    async hasManifest() {
+        return this.manifestStore.hasManifest();
+    }
+    async readManifest() {
+        return this.manifestStore.readManifest();
+    }
+    async readManifestOptional() {
+        return this.manifestStore.readManifestOptional();
+    }
+    async writeManifest(manifest) {
+        await this.manifestStore.writeManifest(manifest);
+    }
+    async writeMcpServerConfig(config) {
+        await this.manifestStore.writeMcpServerConfig(config);
+    }
+    async writeProviderIntegration(providerId, descriptor) {
+        await this.providerIntegrations.writeProviderIntegration(providerId, descriptor);
+    }
+    async readProviderIntegrationOptional(providerId) {
+        return this.providerIntegrations.readProviderIntegrationOptional(providerId);
+    }
+    async writeProjectManifest(projectId, manifest) {
+        await this.projectBanks.writeProjectManifest(projectId, manifest);
+    }
+    async readProjectManifestOptional(projectId) {
+        return this.projectBanks.readProjectManifestOptional(projectId);
+    }
+    async listProjectManifests() {
+        return this.projectBanks.listProjectManifests();
+    }
+    async writeProjectState(projectId, state) {
+        await this.projectBanks.writeProjectState(projectId, state);
+    }
+    async readProjectStateOptional(projectId) {
+        return this.projectBanks.readProjectStateOptional(projectId);
+    }
+    async deleteProjectBank(projectId) {
+        const deleted = await this.projectBanks.deleteProjectBank(projectId);
+        if (deleted) {
+            await this.touchManifest();
+        }
+        return deleted;
+    }
+    async readAuditEventsOptional() {
+        return this.auditStore.readEventsOptional();
+    }
+    async listEntries(kind, groupPath) {
+        return this.listLayerEntries("shared", kind, undefined, groupPath);
+    }
+    async listLayerEntries(layer, kind, projectId, groupPath) {
+        return this.entries.listLayerEntries(layer, kind, projectId, groupPath);
+    }
+    async readEntry(kind, entryPath) {
+        return this.readLayerEntry("shared", kind, entryPath);
+    }
+    async readLayerEntry(layer, kind, entryPath, projectId) {
+        return this.entries.readLayerEntry(layer, kind, entryPath, projectId);
+    }
+    async readLayerEntryOptional(layer, kind, entryPath, projectId) {
+        return this.entries.readLayerEntryOptional(layer, kind, entryPath, projectId);
+    }
+    async touchManifest() {
+        const manifest = await this.readManifestOptional();
+        if (manifest === null) {
+            return;
+        }
+        await this.writeManifest({
+            ...manifest,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    async touchProjectManifest(projectId) {
+        const manifest = await this.readProjectManifestOptional(projectId);
+        if (manifest === null) {
+            return;
+        }
+        await this.writeProjectManifest(projectId, {
+            ...manifest,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    async upsertRule(layer, entryPath, content, projectId) {
+        const result = await this.entries.upsertRule(layer, entryPath, content, projectId);
+        await this.touchManifest();
+        if (layer === "project" && projectId) {
+            await this.touchProjectManifest(projectId);
+        }
+        return result;
+    }
+    async upsertSkill(layer, skillPath, content, projectId) {
+        const result = await this.entries.upsertSkill(layer, skillPath, content, projectId);
+        await this.touchManifest();
+        if (layer === "project" && projectId) {
+            await this.touchProjectManifest(projectId);
+        }
+        return result;
+    }
+    async deleteRule(layer, entryPath, projectId) {
+        const result = await this.entries.deleteRule(layer, entryPath, projectId);
+        if (result.status === "deleted") {
+            await this.touchManifest();
+            if (layer === "project" && projectId) {
+                await this.touchProjectManifest(projectId);
+            }
+        }
+        return result;
+    }
+    async deleteSkill(layer, skillPath, projectId) {
+        const result = await this.entries.deleteSkill(layer, skillPath, projectId);
+        if (result.status === "deleted") {
+            await this.touchManifest();
+            if (layer === "project" && projectId) {
+                await this.touchProjectManifest(projectId);
+            }
+        }
+        return result;
+    }
+}

package/dist/storage/entryStore.js

@@ -0,0 +1,142 @@
+import path from "node:path";
+import { parseCanonicalRuleDocument, parseCanonicalSkillDocument } from "../core/bank/canonicalEntry.js";
+import { resolveBankPaths } from "../core/bank/layout.js";
+import { ValidationError } from "../shared/errors.js";
+import { deleteManagedDirectory, deleteManagedFile, listManagedFilesRecursively, managedPathExists, readManagedTextFile, writeManagedTextFile, } from "./safeFs.js";
+export class EntryStore {
+    rootPath;
+    paths;
+    constructor(rootPath, paths) {
+        this.rootPath = rootPath;
+        this.paths = paths;
+    }
+    resolveEntryBasePath(kind, layer, projectId) {
+        if (layer === "shared") {
+            return kind === "rules" ? this.paths.sharedRulesDirectory : this.paths.sharedSkillsDirectory;
+        }
+        if (!projectId) {
+            throw new ValidationError("Project id is required for project-layer entries.");
+        }
+        return kind === "rules" ? this.paths.projectRulesDirectory(projectId) : this.paths.projectSkillsDirectory(projectId);
+    }
+    resolvePathWithinEntryBase(basePath, relativePath) {
+        const resolvedPath = path.resolve(basePath, relativePath);
+        const normalizedRelativePath = path.relative(basePath, resolvedPath);
+        if (normalizedRelativePath.startsWith("..") || path.isAbsolute(normalizedRelativePath)) {
+            throw new ValidationError(`Entry path escapes ${path.basename(basePath)}: ${relativePath}`);
+        }
+        return resolvedPath;
+    }
+    buildReadableEntryCandidates(kind, layer, entryPath) {
+        const normalizedPath = entryPath.replaceAll("\\", "/").trim();
+        if (kind !== "skills") {
+            return [normalizedPath];
+        }
+        const scopePrefix = `${layer}/`;
+        const alternatePath = normalizedPath.startsWith(scopePrefix)
+            ? normalizedPath.slice(scopePrefix.length)
+            : `${scopePrefix}${normalizedPath}`;
+        return [...new Set([normalizedPath, alternatePath])];
+    }
+    validateRuleEntryPath(entryPath) {
+        const normalizedPath = entryPath.replaceAll("\\", "/").trim();
+        if (!normalizedPath.endsWith(".md")) {
+            throw new ValidationError("Rule path must end with .md.");
+        }
+        if (path.posix.basename(normalizedPath).toLowerCase() === "skill.md") {
+            throw new ValidationError("Rule path cannot target SKILL.md.");
+        }
+    }
+    normalizeSkillPath(skillPath) {
+        const trimmedPath = skillPath.replaceAll("\\", "/").trim().replace(/\/+$/u, "");
+        const lowerCasePath = trimmedPath.toLowerCase();
+        if (trimmedPath.length === 0) {
+            throw new ValidationError("Skill path must not be empty.");
+        }
+        if (lowerCasePath === "skill.md") {
+            throw new ValidationError("Skill path must reference a skill folder, not SKILL.md directly.");
+        }
+        if (lowerCasePath.endsWith("/skill.md")) {
+            return trimmedPath.slice(0, -"/SKILL.md".length);
+        }
+        return trimmedPath;
+    }
+    async listLayerEntries(layer, kind, projectId, groupPath) {
+        const basePath = this.resolveEntryBasePath(kind, layer, projectId);
+        const resolvedBasePath = groupPath ? this.resolvePathWithinEntryBase(basePath, groupPath) : basePath;
+        const filePaths = await listManagedFilesRecursively(this.rootPath, resolvedBasePath);
+        return filePaths.map((filePath) => ({
+            path: path.relative(basePath, filePath),
+        }));
+    }
+    async readLayerEntry(layer, kind, entryPath, projectId) {
+        const basePath = this.resolveEntryBasePath(kind, layer, projectId);
+        const candidatePaths = this.buildReadableEntryCandidates(kind, layer, entryPath);
+        for (const candidatePath of candidatePaths) {
+            const resolvedEntryPath = this.resolvePathWithinEntryBase(basePath, candidatePath);
+            if (await managedPathExists(this.rootPath, resolvedEntryPath)) {
+                return readManagedTextFile(this.rootPath, resolvedEntryPath);
+            }
+        }
+        throw new ValidationError(`Entry not found: ${kind}/${entryPath}`);
+    }
+    async readLayerEntryOptional(layer, kind, entryPath, projectId) {
+        const basePath = this.resolveEntryBasePath(kind, layer, projectId);
+        const candidatePaths = this.buildReadableEntryCandidates(kind, layer, entryPath);
+        for (const candidatePath of candidatePaths) {
+            const resolvedEntryPath = this.resolvePathWithinEntryBase(basePath, candidatePath);
+            if (await managedPathExists(this.rootPath, resolvedEntryPath)) {
+                return readManagedTextFile(this.rootPath, resolvedEntryPath);
+            }
+        }
+        return null;
+    }
+    async upsertRule(layer, entryPath, content, projectId) {
+        this.validateRuleEntryPath(entryPath);
+        parseCanonicalRuleDocument(content);
+        const basePath = this.resolveEntryBasePath("rules", layer, projectId);
+        const resolvedEntryPath = this.resolvePathWithinEntryBase(basePath, entryPath);
+        const existed = await managedPathExists(this.rootPath, resolvedEntryPath);
+        await writeManagedTextFile(this.rootPath, resolvedEntryPath, content);
+        return {
+            status: existed ? "updated" : "created",
+            path: path.relative(basePath, resolvedEntryPath),
+            absolutePath: resolvedEntryPath,
+        };
+    }
+    async upsertSkill(layer, skillPath, content, projectId) {
+        const normalizedSkillPath = this.normalizeSkillPath(skillPath);
+        parseCanonicalSkillDocument(content);
+        const basePath = this.resolveEntryBasePath("skills", layer, projectId);
+        const resolvedSkillDirectory = this.resolvePathWithinEntryBase(basePath, normalizedSkillPath);
+        const resolvedEntryPath = path.join(resolvedSkillDirectory, "SKILL.md");
+        const existed = await managedPathExists(this.rootPath, resolvedEntryPath);
+        await writeManagedTextFile(this.rootPath, resolvedEntryPath, content);
+        return {
+            status: existed ? "updated" : "created",
+            path: path.relative(basePath, resolvedSkillDirectory),
+            filePath: path.relative(basePath, resolvedEntryPath),
+            absolutePath: resolvedEntryPath,
+        };
+    }
+    async deleteRule(layer, entryPath, projectId) {
+        this.validateRuleEntryPath(entryPath);
+        const basePath = this.resolveEntryBasePath("rules", layer, projectId);
+        const resolvedEntryPath = this.resolvePathWithinEntryBase(basePath, entryPath);
+        const deleted = await deleteManagedFile(this.rootPath, resolvedEntryPath);
+        return {
+            status: deleted ? "deleted" : "not_found",
+            path: path.relative(basePath, resolvedEntryPath),
+        };
+    }
+    async deleteSkill(layer, skillPath, projectId) {
+        const normalizedSkillPath = this.normalizeSkillPath(skillPath);
+        const basePath = this.resolveEntryBasePath("skills", layer, projectId);
+        const resolvedSkillDirectory = this.resolvePathWithinEntryBase(basePath, normalizedSkillPath);
+        const deleted = await deleteManagedDirectory(this.rootPath, resolvedSkillDirectory);
+        return {
+            status: deleted ? "deleted" : "not_found",
+            path: path.relative(basePath, resolvedSkillDirectory),
+        };
+    }
+}

package/dist/storage/manifestStore.js

@@ -0,0 +1,30 @@
+import { parseManifest } from "../core/bank/manifest.js";
+import { resolveBankPaths } from "../core/bank/layout.js";
+import { managedPathExists, readManagedJsonFile, writeManagedJsonFile } from "./safeFs.js";
+export class ManifestStore {
+    rootPath;
+    paths;
+    constructor(rootPath, paths) {
+        this.rootPath = rootPath;
+        this.paths = paths;
+    }
+    async hasManifest() {
+        return managedPathExists(this.rootPath, this.paths.manifestFile);
+    }
+    async readManifest() {
+        const manifest = await readManagedJsonFile(this.rootPath, this.paths.manifestFile);
+        return parseManifest(manifest);
+    }
+    async readManifestOptional() {
+        if (!(await this.hasManifest())) {
+            return null;
+        }
+        return this.readManifest();
+    }
+    async writeManifest(manifest) {
+        await writeManagedJsonFile(this.rootPath, this.paths.manifestFile, manifest);
+    }
+    async writeMcpServerConfig(config) {
+        await writeManagedJsonFile(this.rootPath, this.paths.mcpServerConfigFile, config);
+    }
+}

package/dist/storage/projectBankStore.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { parseProjectBankManifest, parseProjectBankState } from "../core/bank/project.js";
+import { resolveBankPaths } from "../core/bank/layout.js";
+import { deleteManagedDirectory, ensureManagedDirectory, listManagedChildDirectories, managedPathExists, readManagedJsonFile, writeManagedJsonFile, } from "./safeFs.js";
+export class ProjectBankStore {
+    rootPath;
+    paths;
+    constructor(rootPath, paths) {
+        this.rootPath = rootPath;
+        this.paths = paths;
+    }
+    async ensureProjectStructure(projectId) {
+        await ensureManagedDirectory(this.rootPath, this.paths.projectDirectory(projectId));
+        await ensureManagedDirectory(this.rootPath, this.paths.projectRulesDirectory(projectId));
+        await ensureManagedDirectory(this.rootPath, this.paths.projectSkillsDirectory(projectId));
+        await ensureManagedDirectory(this.rootPath, path.join(this.paths.projectRulesDirectory(projectId), "core"));
+        await ensureManagedDirectory(this.rootPath, path.join(this.paths.projectRulesDirectory(projectId), "stacks"));
+        await ensureManagedDirectory(this.rootPath, path.join(this.paths.projectRulesDirectory(projectId), "topics"));
+    }
+    async writeProjectManifest(projectId, manifest) {
+        await this.ensureProjectStructure(projectId);
+        await writeManagedJsonFile(this.rootPath, this.paths.projectManifestFile(projectId), manifest);
+    }
+    async readProjectManifestOptional(projectId) {
+        const manifestFilePath = this.paths.projectManifestFile(projectId);
+        if (!(await managedPathExists(this.rootPath, manifestFilePath))) {
+            return null;
+        }
+        const manifest = await readManagedJsonFile(this.rootPath, manifestFilePath);
+        return parseProjectBankManifest(manifest);
+    }
+    async listProjectManifests() {
+        const projectDirectoryPaths = await listManagedChildDirectories(this.rootPath, this.paths.projectsDirectory);
+        const manifests = await Promise.all(projectDirectoryPaths.map(async (projectDirectoryPath) => {
+            const projectId = path.basename(projectDirectoryPath);
+            return this.readProjectManifestOptional(projectId);
+        }));
+        return manifests.filter((manifest) => manifest !== null);
+    }
+    async writeProjectState(projectId, state) {
+        await this.ensureProjectStructure(projectId);
+        await writeManagedJsonFile(this.rootPath, this.paths.projectStateFile(projectId), state);
+    }
+    async readProjectStateOptional(projectId) {
+        const stateFilePath = this.paths.projectStateFile(projectId);
+        if (!(await managedPathExists(this.rootPath, stateFilePath))) {
+            return null;
+        }
+        const state = await readManagedJsonFile(this.rootPath, stateFilePath);
+        return parseProjectBankState(state);
+    }
+    async deleteProjectBank(projectId) {
+        return deleteManagedDirectory(this.rootPath, this.paths.projectDirectory(projectId));
+    }
+}

package/dist/storage/providerIntegrationStore.js

@@ -0,0 +1,22 @@
+import { parseProviderIntegrationDescriptor } from "../core/bank/integration.js";
+import { resolveBankPaths } from "../core/bank/layout.js";
+import { managedPathExists, readManagedJsonFile, writeManagedJsonFile } from "./safeFs.js";
+export class ProviderIntegrationStore {
+    rootPath;
+    paths;
+    constructor(rootPath, paths) {
+        this.rootPath = rootPath;
+        this.paths = paths;
+    }
+    async writeProviderIntegration(providerId, descriptor) {
+        await writeManagedJsonFile(this.rootPath, this.paths.integrationFile(providerId), descriptor);
+    }
+    async readProviderIntegrationOptional(providerId) {
+        const integrationFilePath = this.paths.integrationFile(providerId);
+        if (!(await managedPathExists(this.rootPath, integrationFilePath))) {
+            return null;
+        }
+        const descriptor = await readManagedJsonFile(this.rootPath, integrationFilePath);
+        return parseProviderIntegrationDescriptor(descriptor);
+    }
+}