@mappamind_/store 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mappamind contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { stateRoot, workspaceIdFor, workspaceDir, baselinePath, factsHashFor, workspaceIdentity } from "./paths.js";
+export { writeBaseline, readBaseline, isStale, loadBaselineStatus } from "./store.js";
+export type { BaselineStatus } from "./store.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { stateRoot, workspaceIdFor, workspaceDir, baselinePath, factsHashFor, workspaceIdentity } from "./paths.js";
+export { writeBaseline, readBaseline, isStale, loadBaselineStatus } from "./store.js";

package/dist/paths.d.ts

@@ -0,0 +1,10 @@
+import type { RepoFiles, WorkspaceModel } from "@mappamind_/baseline";
+export declare function stateRoot(env?: NodeJS.ProcessEnv): string;
+export declare function workspaceIdFor(repoRoots: readonly string[]): string;
+export declare function workspaceDir(workspaceId: string, env?: NodeJS.ProcessEnv): string;
+export declare function baselinePath(workspaceId: string, env?: NodeJS.ProcessEnv): string;
+export declare function factsHashFor(repos: readonly RepoFiles[]): string;
+export declare function workspaceIdentity(repos: readonly RepoFiles[], _model?: WorkspaceModel): {
+    readonly workspaceId: string;
+    readonly factsHash: string;
+};

package/dist/paths.js

@@ -0,0 +1,61 @@
+// Identity and location for the workspace store (D12).
+//
+// The low-level store only knows a state root + workspace id. Product entrypoints
+// set MAPPAMIND_STATE_DIR to <workspace>/.mappamind/state by default, so the
+// durable baseline/cache/snapshot live beside the repo/workspace the user ran on.
+// The XDG fallback remains for direct package use and custom installs.
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function shortHash(input) {
+    return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+// The root that holds all workspaces. Order of precedence: explicit env override,
+// XDG_STATE_HOME, then the XDG default.
+export function stateRoot(env = process.env) {
+    if (env["MAPPAMIND_STATE_DIR"]) {
+        return env["MAPPAMIND_STATE_DIR"];
+    }
+    const xdg = env["XDG_STATE_HOME"];
+    return xdg ? join(xdg, "mappamind") : join(homedir(), ".local", "state", "mappamind");
+}
+// Stable id for a workspace = hash of its repo roots, order-independent (sorted), so
+// the same set of repos always maps to the same store regardless of listing order.
+export function workspaceIdFor(repoRoots) {
+    const canonical = [...repoRoots].sort().join("\n");
+    return `ws_${shortHash(canonical)}`;
+}
+export function workspaceDir(workspaceId, env = process.env) {
+    return join(stateRoot(env), "workspaces", workspaceId);
+}
+export function baselinePath(workspaceId, env = process.env) {
+    return join(workspaceDir(workspaceId, env), "baseline.json");
+}
+// The structural fingerprint the baseline was derived from. If the code's structure
+// changes, this changes, and the stored baseline is known to be stale (D12). We hash
+// a canonical projection of the facts — not formatting, not order — so only real
+// structural change moves it.
+export function factsHashFor(repos) {
+    const canonicalRepos = [...repos]
+        .sort((a, b) => a.repo.localeCompare(b.repo))
+        .map((repo) => ({
+        repo: repo.repo,
+        files: [...repo.files]
+            .sort((a, b) => a.path.localeCompare(b.path))
+            .map((file) => ({
+            path: file.path,
+            symbols: file.symbols.map((symbol) => `${symbol.kind}:${symbol.name}`).sort(),
+            exports: file.exports.map((exported) => exported.name).sort(),
+            imports: file.imports.map((imported) => imported.module).sort(),
+            calls: file.calls.map((call) => `${call.callee}(${call.args.join(",")})`).sort()
+        }))
+    }));
+    return shortHash(JSON.stringify(canonicalRepos));
+}
+// Convenience: the id + fingerprint for a workspace, ready to stamp a baseline.
+export function workspaceIdentity(repos, _model) {
+    return {
+        workspaceId: workspaceIdFor(repos.map((repo) => repo.repo)),
+        factsHash: factsHashFor(repos)
+    };
+}

package/dist/store.d.ts

@@ -0,0 +1,10 @@
+import type { Baseline, RepoFiles } from "@mappamind_/baseline";
+export declare function writeBaseline(workspaceId: string, baseline: Baseline, env?: NodeJS.ProcessEnv): Promise<string>;
+export declare function readBaseline(workspaceId: string, env?: NodeJS.ProcessEnv): Promise<Baseline | null>;
+export declare function isStale(baseline: Baseline, currentFactsHash: string): boolean;
+export type BaselineStatus = {
+    readonly baseline: Baseline | null;
+    readonly stale: boolean;
+    readonly currentFactsHash: string;
+};
+export declare function loadBaselineStatus(workspaceId: string, repos: readonly RepoFiles[], env?: NodeJS.ProcessEnv): Promise<BaselineStatus>;

package/dist/store.js

@@ -0,0 +1,40 @@
+// Read/write the persisted baseline, and detect staleness (D12).
+//
+// Writes are atomic (temp file + rename) so a crash mid-write never leaves a
+// half-baseline on disk. Reads tolerate a missing or unreadable file by returning
+// null — an absent baseline is a normal first-run state, not an error. Staleness is
+// a pure comparison of the stored fingerprint against the current one.
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { baselinePath, factsHashFor } from "./paths.js";
+export async function writeBaseline(workspaceId, baseline, env = process.env) {
+    const target = baselinePath(workspaceId, env);
+    await mkdir(dirname(target), { recursive: true });
+    const tmp = join(dirname(target), `baseline.json.tmp-${process.pid}`);
+    await writeFile(tmp, `${JSON.stringify(baseline, null, 2)}\n`, "utf8");
+    await rename(tmp, target);
+    return target;
+}
+export async function readBaseline(workspaceId, env = process.env) {
+    try {
+        const text = await readFile(baselinePath(workspaceId, env), "utf8");
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+// The baseline is stale if the code it was derived from has structurally changed.
+export function isStale(baseline, currentFactsHash) {
+    return baseline.derivedFrom.factsHash !== currentFactsHash;
+}
+// Load the stored baseline and tell the caller whether it still matches the code.
+export async function loadBaselineStatus(workspaceId, repos, env = process.env) {
+    const currentFactsHash = factsHashFor(repos);
+    const baseline = await readBaseline(workspaceId, env);
+    return {
+        baseline,
+        stale: baseline !== null && isStale(baseline, currentFactsHash),
+        currentFactsHash
+    };
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mappamind_/store",
+  "version": "0.1.0-rc.1",
+  "description": "Structured JSON/JSONL persistence for Mappamind.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mappamind/mappamind.git",
+    "directory": "packages/store"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --test dist/**/*.test.js"
+  },
+  "dependencies": {
+    "@mappamind_/baseline": "0.1.0-rc.1",
+    "@mappamind_/extractors": "0.1.0-rc.1"
+  }
+}