pi-vault-mind 0.14.2 → 0.16.3

package/dist/src/modal-config.js

@@ -9,16 +9,20 @@
  * No HTTP is reimplemented here — `ModalEmbeddingClient` owns that.
  */
 import * as fs from "node:fs";
-import * as path from "node:path";
+import { EMBEDDING_FLAT_KEYS } from "./config-keys.js";
 import { ModalEmbeddingClient } from "./modal-client.js";
-/** Env var name for the Modal bearer token (preferred over config). */
-export const MODAL_TOKEN_ENV = "PVM_API_TOKEN";
+import { deriveCollectionNameFromVaultPath, getTokenEnvPath, normalizeCollectionName, } from "./utils.js";
+/** Env var name for the unscoped remote embedding API key (preferred over config). */
+export const MODAL_TOKEN_ENV = "PVM_REMOTE_EMBEDDING_API_KEY";
 /** Env var name for the read-scoped Modal token (search/export). */
 export const MODAL_READ_TOKEN_ENV = "PVM_MODAL_READ_TOKEN";
 /** Env var name for the write-scoped Modal token (embed/reindex). */
 export const MODAL_WRITE_TOKEN_ENV = "PVM_MODAL_WRITE_TOKEN";
-/** Dotenv-style fallback path for the Modal token. */
-export const MODAL_TOKEN_ENV_PATH = path.join(process.env.HOME || process.env.USERPROFILE || "", ".pi", "agent", "vault-mind.env");
+/**
+ * Dotenv fallback path for the Modal token, resolved from the vault cwd:
+ * `<vault>/.vault-mind/vault-mind.env`. Lazy so tests can override cwd.
+ */
+export const modalTokenEnvPath = (cwd = process.cwd()) => getTokenEnvPath(cwd);
 /** Canonical deployed Modal app name. */
 export const MODAL_APP_NAME = "pi-vault-mind-embed";
 /**
@@ -49,58 +53,63 @@ const readDotEnv = (filePath) => {
 /** Derive the Modal service URL from a workspace slug and canonical app name. */
 export const modalUrl = (workspace) => `https://${workspace}--${MODAL_APP_NAME}-embeddingservice-fastapi-app.modal.run`;
 /**
- * Resolve the Modal API token. Resolution order:
- * 1. `PVM_API_TOKEN` env var
- * 2. `~/.pi/agent/vault-mind.env`
- * 3. `vaultMind.embedding.modal.apiToken` in config
+ * Resolve the unscoped remote embedding API token. Resolution order:
+ * 1. `PVM_REMOTE_EMBEDDING_API_KEY` env var
+ * 2. `<vault>/.vault-mind/vault-mind.env`
+ * 3. `vaultMind.embedding.remoteApiKey` in config
+ *
+ * `PVM_API_TOKEN` is intentionally not consulted — it is reserved for the
+ * extension's bridge authentication.
  *
  * Never log the resolved token.
  */
 export const resolveModalToken = (cfg) => {
     if (process.env[MODAL_TOKEN_ENV])
         return process.env[MODAL_TOKEN_ENV];
-    const dotenv = readDotEnv(MODAL_TOKEN_ENV_PATH);
+    const dotenv = readDotEnv(modalTokenEnvPath());
     if (dotenv[MODAL_TOKEN_ENV])
         return dotenv[MODAL_TOKEN_ENV];
-    return cfg.embedding.modal?.apiToken;
+    return cfg.embedding[EMBEDDING_FLAT_KEYS[7]];
 };
 /**
  * Resolve a scoped Modal token for the requested operation.
  * Resolution order:
  * 1. `PVM_MODAL_{READ|WRITE}_TOKEN` env var
- * 2. `~/.pi/agent/vault-mind.env`
- * 3. `vaultMind.embedding.modal.{readToken|writeToken}` in config
- * 4. Fallback to the unscoped `apiToken` (env, dotenv, then config)
+ * 2. `<vault>/.vault-mind/vault-mind.env`
+ * 3. `vaultMind.embedding.remoteReadApiKey` / `remoteWriteApiKey` in config
+ * 4. Fallback to the unscoped `PVM_REMOTE_EMBEDDING_API_KEY` (env, dotenv, then config)
+ *
+ * `PVM_API_TOKEN` is intentionally not consulted — it is reserved for the
+ * extension's bridge authentication.
  *
  * Never log the resolved token.
  */
 export const getModalToken = (cfg, operation) => {
-    const modal = cfg.embedding.modal;
-    const dotenv = readDotEnv(MODAL_TOKEN_ENV_PATH);
+    const dotenv = readDotEnv(modalTokenEnvPath());
     if (operation === "read") {
         return (process.env[MODAL_READ_TOKEN_ENV] ||
             dotenv[MODAL_READ_TOKEN_ENV] ||
-            modal?.readToken ||
+            cfg.embedding[EMBEDDING_FLAT_KEYS[8]] ||
             resolveModalToken(cfg));
     }
     return (process.env[MODAL_WRITE_TOKEN_ENV] ||
         dotenv[MODAL_WRITE_TOKEN_ENV] ||
-        modal?.writeToken ||
+        cfg.embedding[EMBEDDING_FLAT_KEYS[9]] ||
         resolveModalToken(cfg));
 };
-/** Resolve the explicit baseUrl or derive it from workspace. */
+/** Derive the remote URL from the top-level `remoteUrl` or the `workspace` shortcut. */
 export const resolveBaseUrl = (cfg) => {
-    const modal = cfg.embedding.modal;
-    if (modal?.baseUrl)
-        return modal.baseUrl;
-    if (modal?.workspace)
-        return modalUrl(modal.workspace);
+    if (cfg.embedding[EMBEDDING_FLAT_KEYS[0]])
+        return cfg.embedding[EMBEDDING_FLAT_KEYS[0]];
+    if (cfg.embedding[EMBEDDING_FLAT_KEYS[6]])
+        return modalUrl(cfg.embedding[EMBEDDING_FLAT_KEYS[6]]);
     return undefined;
 };
 /** Resolve the configured workspace slug, if any. */
-export const resolveWorkspace = (cfg) => cfg.embedding.modal?.workspace;
+export const resolveWorkspace = (cfg) => cfg.embedding[EMBEDDING_FLAT_KEYS[6]];
 /** True when Modal is usable: a base URL (explicit or derived) and at least one resolvable scoped token are present. */
-export const isModalConfigured = (cfg) => !!cfg.embedding.remoteUrl && (!!getModalToken(cfg, "read") || !!getModalToken(cfg, "write"));
+export const isModalConfigured = (cfg) => !!cfg.embedding[EMBEDDING_FLAT_KEYS[0]] &&
+    (!!getModalToken(cfg, "read") || !!getModalToken(cfg, "write"));
 /**
  * Build a `ModalEmbeddingClient` from config. Returns null when Modal is not
  * configured (no base URL / token) so callers can degrade gracefully.
@@ -124,21 +133,39 @@ export const createModalClient = (cfg) => {
  * hard-coded dimension).
  */
 export const resolveModel = (cfg, collection) => {
-    const override = collection ? cfg.embedding.collectionModels?.[collection] : undefined;
+    const override = collection ? cfg.embedding[EMBEDDING_FLAT_KEYS[12]]?.[collection] : undefined;
     if (override?.model)
         return override.model;
-    return cfg.embedding.modal?.model || "embeddinggemma";
+    return cfg.embedding[EMBEDDING_FLAT_KEYS[2]] || "embeddinggemma";
 };
 /**
  * The configured output dimension for a collection, if known. Per-collection
- * overrides win; otherwise the global Modal config `dim`. Returns undefined
- * when unset — callers resolve the native dim lazily via `/models`.
+ * overrides win; otherwise the top-level `dim` on `EmbeddingConfig`.
+ * Returns undefined when unset — callers resolve the native dim lazily via `/models`.
  */
 export const resolveDim = (cfg, collection) => {
-    const override = collection ? cfg.embedding.collectionModels?.[collection] : undefined;
+    const override = collection ? cfg.embedding[EMBEDDING_FLAT_KEYS[12]]?.[collection] : undefined;
     if (override?.dim != null)
         return override.dim;
-    return cfg.embedding.modal?.dim;
+    return cfg.embedding[EMBEDDING_FLAT_KEYS[4]];
 };
 /** Namespaced local table name mirroring the server's ADR-3 scheme. */
 export const namespacedTableName = (collection, model, dim) => `col_${collection}__${model}__${dim}`;
+/**
+ * Resolve the server-side (Modal) collection table prefix for cross-vault
+ * isolation on a shared Modal deployment. Unset or `"auto"` derives it from
+ * the vault slug. The result is normalized (no `__`, no leading/trailing `_`)
+ * so it is safe for the server's `col_(.+)__(.+)__(\d+)$` parse.
+ *
+ * Applies ONLY to remote table names — local LanceDB tables stay unprefixed.
+ */
+export const resolveCollectionPrefix = (cfg, vaultPath) => {
+    const raw = cfg.vaults?.default?.collectionPrefix;
+    const base = raw && raw !== "auto" ? raw : deriveCollectionNameFromVaultPath(vaultPath);
+    return normalizeCollectionName(base) || undefined;
+};
+/**
+ * Prepend the collection prefix to a collection name for server-side table
+ * identity. When `prefix` is undefined, returns the collection name unchanged.
+ */
+export const serverCollectionName = (prefix, collection) => prefix ? `${prefix}_${collection}` : collection;

package/dist/src/model-router.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Model-router config scaffolding — shared source of truth for the tuned
+ * default primary/fallback model sequence and the initial `model-router.json`
+ * shape.
+ *
+ * Extracted from the Obsidian plugin (`packages/obsidian/src/main.ts`
+ * `defaultModelRouterChoices`/`scaffoldModelRouterConfig`), which previously
+ * carried the only implementation — a CLI-only setup got no equivalent
+ * scaffold at all. The plugin is expected to switch to calling this (or an
+ * equivalent extension-exposed path) in a future refactor rather than
+ * maintaining its own copy.
+ */
+/** Tuned default primary model + fallback sequence for the `auto` router profile. */
+export declare const defaultModelRouterChoices: () => {
+    primary: string;
+    fallbackSequence: string[];
+};
+/**
+ * Scaffold `model-router.json` at the vault-scoped agent dir
+ * (`resolveVaultMindPaths(cwd).modelRouter`) with tuned defaults, if it
+ * doesn't already exist. No-op (returns `created: false`) when the file is
+ * already present — never overwrites a user's router config.
+ */
+export declare const scaffoldModelRouterConfig: (cwd: string) => {
+    created: boolean;
+    path: string;
+};

package/dist/src/model-router.js

@@ -0,0 +1,67 @@
+/**
+ * Model-router config scaffolding — shared source of truth for the tuned
+ * default primary/fallback model sequence and the initial `model-router.json`
+ * shape.
+ *
+ * Extracted from the Obsidian plugin (`packages/obsidian/src/main.ts`
+ * `defaultModelRouterChoices`/`scaffoldModelRouterConfig`), which previously
+ * carried the only implementation — a CLI-only setup got no equivalent
+ * scaffold at all. The plugin is expected to switch to calling this (or an
+ * equivalent extension-exposed path) in a future refactor rather than
+ * maintaining its own copy.
+ */
+import * as fs from "node:fs";
+import { ensureDir, resolveVaultMindPaths } from "./utils.js";
+/** Tuned default primary model + fallback sequence for the `auto` router profile. */
+export const defaultModelRouterChoices = () => {
+    const isMacOS = process.platform === "darwin";
+    return {
+        primary: "ollama/gemma4:31b-cloud",
+        fallbackSequence: isMacOS
+            ? ["ollama/gemma4:e4b", "ollama/gemma4:12b-mlx", "ollama/gemma3:4b", "ollama/*"]
+            : ["ollama/gemma4:e4b", "ollama/gemma4:12b", "ollama/gemma3:4b", "ollama/*"],
+    };
+};
+/**
+ * Scaffold `model-router.json` at the vault-scoped agent dir
+ * (`resolveVaultMindPaths(cwd).modelRouter`) with tuned defaults, if it
+ * doesn't already exist. No-op (returns `created: false`) when the file is
+ * already present — never overwrites a user's router config.
+ */
+export const scaffoldModelRouterConfig = (cwd) => {
+    const { modelRouter: configPath } = resolveVaultMindPaths(cwd);
+    if (fs.existsSync(configPath))
+        return { created: false, path: configPath };
+    const { primary: mediumModel, fallbackSequence } = defaultModelRouterChoices();
+    const config = {
+        defaultProfile: "auto",
+        features: {
+            rateLimitFallback: true,
+            ollamaSync: false,
+            scopeShim: true,
+            perTurnRouting: false,
+            intentClassifier: false,
+            costBudgeting: false,
+            phaseMemory: false,
+            contextCompression: false,
+        },
+        rateLimitFallback: {
+            enabled: true,
+            shortDelayThreshold: 30,
+            autoFallback: true,
+            autoRestore: true,
+            restoreCheckInterval: 300,
+            fallbackSequence,
+        },
+        profiles: {
+            auto: {
+                high: { model: "ollama/gemma4:31b-cloud", thinking: "medium" },
+                medium: { model: mediumModel, thinking: "low" },
+                low: { model: "ollama/gemma4:e4b", thinking: "off" },
+            },
+        },
+    };
+    ensureDir(configPath);
+    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+    return { created: true, path: configPath };
+};

package/dist/src/models.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Server-side reader for pi's `models.json` provider/model catalog.
+ *
+ * Mirrors the plugin's `packages/obsidian/src/chat/pi-config-reader.ts`
+ * (`readPiModelsConfig`) so the `GET /vault-mind/models` endpoint returns the
+ * same flattened `ProviderInfo[]` shape the plugin already consumes — letting
+ * it replace synchronous disk reads with a `VaultMindClient.getModels()` call.
+ *
+ * Reads two locations and merges (project overrides agent-dir):
+ *   1. Agent-dir:  `resolveVaultMindPaths(vault).modelsJson`
+ *                  (= `<vault>/.vault-mind/.pi/agent/models.json`)
+ *   2. Project:    `<vault>/.pi/models.json`
+ *
+ * Uses plain `JSON.parse` (consistent with the `/vm doctor` reader in
+ * commands.ts) — pi writes machine-generated strict JSON. A parse failure
+ * degrades gracefully to `{ providers: [], error }`.
+ */
+/** A single model entry, flattened for UI/transport. */
+export interface ModelInfo {
+    id: string;
+    name: string;
+    reasoning?: boolean;
+    contextWindow?: number;
+}
+/** A provider entry with its models and the env var it expects for auth. */
+export interface ProviderInfo {
+    name: string;
+    /** Env var name the provider expects. Only exact $NAME or ${NAME} references are accepted; all others yield "". */
+    envVarName: string;
+    baseUrl?: string;
+    api?: string;
+    models: ModelInfo[];
+}
+/**
+ * Read + merge pi's `models.json` for a vault and flatten to `ProviderInfo[]`.
+ * Returns `{ providers, error? }`; `error` is set only when a config file
+ * exists but cannot be parsed (matching the plugin's contract).
+ */
+export declare const readModelProviders: (vaultPath: string) => {
+    providers: ProviderInfo[];
+    error?: string;
+};

package/dist/src/models.js

@@ -0,0 +1,78 @@
+/**
+ * Server-side reader for pi's `models.json` provider/model catalog.
+ *
+ * Mirrors the plugin's `packages/obsidian/src/chat/pi-config-reader.ts`
+ * (`readPiModelsConfig`) so the `GET /vault-mind/models` endpoint returns the
+ * same flattened `ProviderInfo[]` shape the plugin already consumes — letting
+ * it replace synchronous disk reads with a `VaultMindClient.getModels()` call.
+ *
+ * Reads two locations and merges (project overrides agent-dir):
+ *   1. Agent-dir:  `resolveVaultMindPaths(vault).modelsJson`
+ *                  (= `<vault>/.vault-mind/.pi/agent/models.json`)
+ *   2. Project:    `<vault>/.pi/models.json`
+ *
+ * Uses plain `JSON.parse` (consistent with the `/vm doctor` reader in
+ * commands.ts) — pi writes machine-generated strict JSON. A parse failure
+ * degrades gracefully to `{ providers: [], error }`.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveVaultMindPaths } from "./utils.js";
+/**
+ * Read + merge pi's `models.json` for a vault and flatten to `ProviderInfo[]`.
+ * Returns `{ providers, error? }`; `error` is set only when a config file
+ * exists but cannot be parsed (matching the plugin's contract).
+ */
+export const readModelProviders = (vaultPath) => {
+    const merged = {};
+    let error;
+    let configExists = false;
+    const agentModelsPath = resolveVaultMindPaths(vaultPath).modelsJson;
+    const projectModelsPath = path.join(vaultPath, ".pi", "models.json");
+    for (const [label, file] of [
+        ["agent-dir", agentModelsPath],
+        ["project", projectModelsPath],
+    ]) {
+        try {
+            if (!fs.existsSync(file))
+                continue;
+            configExists = true;
+            const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+            if (parsed.providers) {
+                // Project-level overrides agent-dir for same provider names.
+                Object.assign(merged, parsed.providers);
+            }
+        }
+        catch (err) {
+            error = `Failed to read ${label} models.json: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    if (configExists && Object.keys(merged).length === 0 && error) {
+        return { providers: [], error };
+    }
+    const providers = Object.entries(merged).map(([name, config]) => {
+        // Only exact shell-style references ($VAR_NAME or ${VAR_NAME}) are converted to raw
+        // env var names; all other apiKey values yield an empty string to prevent literal leakage.
+        let envVarName = "";
+        if (typeof config.apiKey === "string") {
+            const match = config.apiKey.match(/^\$([A-Za-z_][A-Za-z0-9_]*)$/) ||
+                config.apiKey.match(/^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/);
+            if (match)
+                envVarName = match[1];
+        }
+        return {
+            name,
+            envVarName,
+            baseUrl: config.baseUrl,
+            api: config.api,
+            models: (config.models ?? []).map((m) => ({
+                id: m.id,
+                name: m.name || m.id,
+                reasoning: m.reasoning,
+                contextWindow: m.contextWindow,
+            })),
+        };
+    });
+    providers.sort((a, b) => a.name.localeCompare(b.name));
+    return { providers, error };
+};

package/dist/src/personalize.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { getStatus } from "./lance.js";
-import { expandHome, loadConfig } from "./utils.js";
+import { expandHome, loadConfig, resolveAgentDir } from "./utils.js";
 /** Resolve the vault path: configured default vault wins, otherwise ctx.cwd. */
 export const resolveVaultPath = (ctx) => {
     const cfg = loadConfig(ctx.cwd);
@@ -11,7 +11,7 @@ export const resolveVaultPath = (ctx) => {
 };
 /** Load current agent configuration files if they exist. */
 export const loadCurrentConfig = (vaultPath) => {
-    const systemMdPath = path.join(vaultPath, ".pi", "agent", "system.md");
+    const systemMdPath = path.join(resolveAgentDir(vaultPath), "system.md");
     const agentsMdPath = path.join(vaultPath, "AGENTS.md");
     return {
         systemMd: fs.existsSync(systemMdPath) ? fs.readFileSync(systemMdPath, "utf-8") : null,
@@ -305,6 +305,20 @@ const resolveCurrentContent = (filePath, currentConfig) => {
     }
     return null;
 };
+/**
+ * Resolve a suggestion's relative path to its on-disk location. The framework
+ * `system.md` lives in the resolved agent dir (which may be outside the vault),
+ * while everything else (AGENTS.md, etc.) is vault-relative.
+ */
+const resolveSuggestionPath = (filePath, vaultPath) => {
+    if (path.isAbsolute(filePath))
+        return filePath;
+    const normalized = filePath.replace(/\\/g, "/");
+    if (normalized === ".pi/agent/system.md" || normalized.endsWith("/.pi/agent/system.md")) {
+        return path.join(resolveAgentDir(vaultPath), "system.md");
+    }
+    return path.join(vaultPath, filePath);
+};
 /** Present each suggestion diff to the user and write approved files. */
 export const presentAndApplyDiff = async (suggestions, ctx, currentConfig) => {
     const approved = [];
@@ -321,7 +335,7 @@ export const presentAndApplyDiff = async (suggestions, ctx, currentConfig) => {
         const message = [suggestions.commentary, diff].filter(Boolean).join("\n\n");
         const ok = await ctx.ui.confirm(title, message);
         if (ok) {
-            const fullPath = path.isAbsolute(file.path) ? file.path : path.join(vaultPath, file.path);
+            const fullPath = resolveSuggestionPath(file.path, vaultPath);
             const dir = path.dirname(fullPath);
             if (!fs.existsSync(dir))
                 fs.mkdirSync(dir, { recursive: true });

package/dist/src/scaffold.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Vault config scaffolding — the single, UI-agnostic implementation of
+ * "create/merge-safe-update the config + collection files + injector
+ * artifacts + vault-root .gitignore." Shared by every entry point that needs
+ * to scaffold a vault: the `/vm setup` CLI command (`commands.ts`), the HTTP
+ * `/vm/setup` API route (`server.ts`), and any future consumer (e.g. an
+ * Obsidian plugin refactor) — none of them should carry their own copy of
+ * the collections/injectors template.
+ */
+/**
+ * Vault-root `.gitignore` entries that keep pi-vault-mind compatible with
+ * `obsidian-git` (and, transitively, Obsidian Sync setups that also back up via
+ * git). The `.vault-mind/` directory holds local state (token, index, framework
+ * dir) that must never be committed, EXCEPT the hand-tuned config file, which is
+ * re-included via a `!` negation. The LanceDB index is a large, per-device,
+ * rebuildable binary; Obsidian's workspace UI state churns constantly. See
+ * docs/OBSIDIAN_SETUP.md §6.
+ */
+export declare const GITIGNORE_ENTRIES: string[];
+/**
+ * Decide what to do with the vault `.gitignore`, given its current contents
+ * (`null` if absent). Pure — does no I/O — so it is unit-testable. Creates the
+ * file when missing, appends only the entries that aren't already present
+ * (line-exact match, trimmed), and skips when everything is covered.
+ *
+ * A bare `.vault-mind/` directory exclude would block the per-file config
+ * negation (git cannot re-include a file inside an ignored directory), so when
+ * one is present it is rewritten to `.vault-mind/*` and the whole file returned.
+ */
+export declare const planGitignore: (existing: string | null) => {
+    action: "create" | "append" | "rewrite" | "skip";
+    content: string;
+};
+export interface ScaffoldResult {
+    created: string[];
+    updated: string[];
+    skipped: string[];
+    /** The resolved default-collection file name (vault-derived unless overridden). */
+    collectionName: string;
+}
+/**
+ * Scaffold (or merge-safe-update) `.vault-mind/vault-mind.config.json`,
+ * the default collection files, injector artifacts, and vault-root
+ * `.gitignore` for `vaultPath`. UI-agnostic — returns what happened instead
+ * of notifying; callers (a CLI command, an HTTP handler, anything else)
+ * render the result however fits their surface.
+ */
+export declare const scaffoldVaultConfig: (vaultPath: string, collectionOverride?: string) => ScaffoldResult;