@mnemonik/shared 7.140.1 → 7.140.3

package/src/instructions.ts

@@ -156,7 +156,7 @@
 
 // Dynamic response orchestration remains authoritative. This universal floor stays
 // self-scoping when project context was already loaded through another channel.
-const INSTRUCTIONS_CONTENT = `Mnemonik provides persistent project memory: decisions, rationale, tasks, and policies across sessions. If no block begins "PROJECT_CONTEXT schemaVersion=", session_bootstrap({ cwd }) loads project context when cwd is the real absolute path of the project root; a placeholder or relative path fails. With that block, context is loaded and no session_bootstrap call is needed. Code and docs show current artifacts, git shows changes, and memory carries the why; memory_search recalls rationale or intent, then Grep or Read verifies current source.
+const INSTRUCTIONS_CONTENT = `Mnemonik provides persistent project memory: decisions, rationale, tasks, and policies across sessions. If no block begins "PROJECT_CONTEXT schemaVersion=", session_bootstrap({}) loads project context; installed hooks supply the project. With that block, context is loaded and no session_bootstrap call is needed. Code and docs show current artifacts, git shows changes, and memory carries the why; memory_search recalls rationale or intent, then Grep or Read verifies current source.
 
 What I learn about you belongs in Companion; what I learn about this project belongs here.
 

package/src/projectIdentityFile.ts

@@ -86,9 +86,35 @@ export function parseIdentityFile(text: string): Exclude<IdentityFileResult, { k
   };
 }
 
+/**
+ * A `.mnemonik.json` that holds configuration but no identity: a JSON object
+ * with no `projectId` that names schema 1 or no schema. Invalid identities,
+ * and any file naming another schema (which may carry its identity under other
+ * keys), are not.
+ */
+export function isConfigurationOnly(text: string): boolean {
+  try {
+    const value: unknown = JSON.parse(text);
+    return (
+      !!value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      !('projectId' in value) &&
+      (!('schemaVersion' in value) || value.schemaVersion === 1)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read a folder's identity file. With `configurationOnlyAbsent` (and with
+ * `selectedRoot`, folders ticked during install), a configuration-only file is
+ * no identity: the folder is not a project of its own.
+ */
 export async function readIdentityFile(
   dir: string,
-  options: { selectedRoot?: boolean } = {}
+  options: { selectedRoot?: boolean; configurationOnlyAbsent?: boolean } = {}
 ): Promise<IdentityFileResult> {
   const path = join(dir, '.mnemonik.json');
   try {
@@ -96,25 +122,13 @@ export async function readIdentityFile(
     if (stat.isSymbolicLink()) return { kind: 'malformed', detail: 'symlink' };
     if (!stat.isFile()) return { kind: 'malformed', detail: 'identity path is not a regular file' };
     const text = await readFile(path, 'utf8');
-    if (options.selectedRoot) {
-      // A ticked folder with configuration but no identity is a new project.
-      // Keep invalid identities, non-regular files and any file that names a
-      // schema other than 1 on the strict refusal path: a later schema may carry
-      // its identity under other keys, and setup must not replace it.
-      try {
-        const value: unknown = JSON.parse(text);
-        if (
-          value &&
-          typeof value === 'object' &&
-          !Array.isArray(value) &&
-          !('projectId' in value) &&
-          (!('schemaVersion' in value) || value.schemaVersion === 1)
-        )
-          return { kind: 'absent' };
-      } catch {
-        /* The strict parser supplies the diagnostic. */
-      }
-    }
+    // A ticked folder with configuration but no identity is a new project, and
+    // a configuration-only file met walking up is not a project boundary. Keep
+    // invalid identities, non-regular files and any file that names a schema
+    // other than 1 on the strict refusal path: a later schema may carry its
+    // identity under other keys, and setup must not replace it.
+    if ((options.selectedRoot || options.configurationOnlyAbsent) && isConfigurationOnly(text))
+      return { kind: 'absent' };
     return parseIdentityFile(text);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { kind: 'absent' };

package/src/protectedPaths.ts

@@ -7,6 +7,23 @@ function pathsFor(platform: Platform): PlatformPath {
   return platform === 'win32' ? win32 : posix;
 }
 
+/**
+ * Mnemonik's local state folder: the same answer as `stateDirectory` in
+ * @mnemonik/local-setup, which depends on this package and so cannot be
+ * imported here.
+ */
+export function mnemonikStateDirectory(
+  platform: Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+  home: string = homedir()
+): string {
+  if (env.MNEMONIK_STATE_DIR) return env.MNEMONIK_STATE_DIR;
+  if (platform === 'win32')
+    return win32.join(env.LOCALAPPDATA || win32.join(home, 'AppData', 'Local'), 'Mnemonik');
+  if (platform === 'darwin') return posix.join(home, 'Library', 'Application Support', 'Mnemonik');
+  return posix.join(env.XDG_STATE_HOME || posix.join(home, '.local', 'state'), 'mnemonik');
+}
+
 /** Local state and credential locations that Mnemonik must never scan. */
 export function protectedLocalPaths(
   platform: Platform = process.platform,
@@ -16,13 +33,7 @@ export function protectedLocalPaths(
   const path = pathsFor(platform);
   const localAppData = env.LOCALAPPDATA || win32.join(home, 'AppData', 'Local');
   const appData = env.APPDATA || win32.join(home, 'AppData', 'Roaming');
-  const state =
-    env.MNEMONIK_STATE_DIR ||
-    (platform === 'win32'
-      ? win32.join(localAppData, 'Mnemonik')
-      : platform === 'darwin'
-        ? posix.join(home, 'Library', 'Application Support', 'Mnemonik')
-        : posix.join(env.XDG_STATE_HOME || posix.join(home, '.local', 'state'), 'mnemonik'));
+  const state = mnemonikStateDirectory(platform, env, home);
   const common = [
     state,
     path.join(home, '.mnemonik'),

package/src/repositoryRoot.ts

@@ -1,4 +1,4 @@
-import { lstat, readFile } from 'node:fs/promises';
+import { lstat, readFile, realpath } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -33,12 +33,6 @@ export type ProjectIdentityResolution =
   | (ResolvedBase & { kind: 'absent' })
   | (ResolvedBase & { kind: 'unknown_version'; version: unknown; path: string })
   | (ResolvedBase & { kind: 'malformed'; detail: string; path: string })
-  | (ResolvedBase & { kind: 'nested'; parentIdentity?: ProjectIdentityFile })
-  | (ResolvedBase & {
-      kind: 'conflict';
-      rootIdentity: ProjectIdentityFile;
-      nestedIdentity: ProjectIdentityFile;
-    })
   | { kind: 'git_unavailable'; detail: string };
 
 const GIT_TIMEOUT_MS = 2_000;
@@ -102,7 +96,7 @@ async function confirmedBoundaryAt(path: string): Promise<RepositoryBoundary | u
 async function boundariesBetween(cwd: string, root: string): Promise<RepositoryBoundary[]> {
   const boundaries: RepositoryBoundary[] = [];
   let directory = cwd;
-  while (directory !== root) {
+  while (!samePath(directory, root)) {
     const boundary = await confirmedBoundaryAt(directory);
     if (boundary) boundaries.push(boundary);
     const parent = dirname(directory);
@@ -123,37 +117,45 @@ async function containingRepository(root: string): Promise<RepositoryBoundary |
   }
 }
 
-async function canonicalBoundaryRoot(boundary: RepositoryBoundary): Promise<string> {
-  if (boundary.kind === 'directory') return boundary.path;
-  const pointer = /^gitdir:\s*(.+)\s*$/im.exec(
-    await readFile(join(boundary.path, '.git'), 'utf8')
-  )?.[1];
-  if (!pointer) return boundary.path;
-  const gitDir = resolve(boundary.path, pointer);
-  try {
-    const commonDir = resolve(gitDir, (await readFile(join(gitDir, 'commondir'), 'utf8')).trim());
-    return dirname(commonDir);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return boundary.path;
-    throw error;
-  }
+/**
+ * A path as the file system knows it, symlinks resolved, so it compares equal
+ * with the real paths of git's answers. A path that does not exist stays as given.
+ */
+async function canonicalPath(path: string): Promise<string> {
+  const absolute = resolve(path);
+  return realpath(absolute).catch(() => absolute);
+}
+
+/** Path equality; Windows paths compare without regard to case. */
+function samePath(left: string, right: string): boolean {
+  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
 }
 
 export async function resolveRepositoryRoot(cwd: string): Promise<RepositoryRootResult> {
-  const absoluteCwd = resolve(cwd);
+  const absoluteCwd = await canonicalPath(cwd);
   try {
     const { stdout } = await runGit(absoluteCwd, [
       'rev-parse',
       '--show-toplevel',
+      '--git-dir',
       '--git-common-dir',
     ]);
-    const [rootLine, commonLine, ...extra] = stdout.trim().split(/\r?\n/);
-    if (!rootLine || !commonLine || extra.length) {
+    const [rootLine, gitDirLine, commonLine, ...extra] = stdout.trim().split(/\r?\n/);
+    if (!rootLine || !gitDirLine || !commonLine || extra.length) {
       return { kind: 'git_unavailable', detail: 'git rev-parse returned an unexpected response' };
     }
-    const root = resolve(rootLine);
-    const commonDir = resolve(root, commonLine);
-    const isLinkedWorktree = commonDir !== join(root, '.git');
+    // git prints --git-dir and --git-common-dir relative to the directory it
+    // ran in (`../.git` from a subfolder) or absolute; every git version
+    // agrees on that. Real paths make them comparable with each other and
+    // with real paths from the file system.
+    const fromGit = (line: string) => canonicalPath(resolve(absoluteCwd, line));
+    const root = await fromGit(rootLine);
+    const gitDir = await fromGit(gitDirLine);
+    const commonDir = await fromGit(commonLine);
+    // Only a linked worktree keeps its own git directory apart from the common
+    // one. A submodule (`.git/modules/<name>`) and a `--separate-git-dir`
+    // checkout keep both in one place, wherever that is.
+    const isLinkedWorktree = !samePath(gitDir, commonDir);
     const nested = await boundariesBetween(absoluteCwd, root);
     if (!isLinkedWorktree && (await containingRepository(root))) {
       const boundary = await boundaryAt(root);
@@ -175,16 +177,56 @@ export async function resolveRepositoryRoot(cwd: string): Promise<RepositoryRoot
   }
 }
 
-async function readPlainIdentity(start: string): Promise<{
-  root: string;
-  result: Awaited<ReturnType<typeof readIdentityFile>>;
-}> {
-  const home = resolve(homedir());
+/**
+ * The common git directory when `dir` is the top of a linked worktree: its
+ * `.git` is a file pointing at a git directory that has a `commondir`. A
+ * submodule's `.git` file points at `.git/modules/<name>`, which has none.
+ * Read from the files git writes, so it holds without a git command.
+ */
+async function linkedWorktreeCommonDir(dir: string): Promise<string | undefined> {
+  try {
+    if (!(await lstat(join(dir, '.git'))).isFile()) return undefined;
+    const pointer = /^gitdir:\s*(.+?)\s*$/im.exec(await readFile(join(dir, '.git'), 'utf8'))?.[1];
+    if (!pointer) return undefined;
+    const gitDir = resolve(dir, pointer);
+    const common = (await readFile(join(gitDir, 'commondir'), 'utf8')).trim();
+    return common ? await canonicalPath(resolve(gitDir, common)) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The project folder of a linked worktree's main checkout: the first entry of
+ * `git worktree list --porcelain`. When that entry is a bare repository
+ * (`proj/.bare` with worktrees beside it), the project folder is the folder
+ * holding it, never the git directory itself. Without git, the folder holding
+ * the common git directory, which is the same answer for both layouts.
+ */
+async function mainCheckout(worktreeTop: string, commonDir: string): Promise<string> {
+  try {
+    const { stdout } = await runGit(worktreeTop, ['worktree', 'list', '--porcelain']);
+    const first = stdout.split(/\r?\n\r?\n/)[0] ?? '';
+    const path = /^worktree (.+)$/m.exec(first)?.[1];
+    if (path) {
+      const main = await canonicalPath(resolve(worktreeTop, path));
+      return /^bare$/m.test(first) ? dirname(main) : main;
+    }
+  } catch {
+    /* fall through */
+  }
+  return dirname(commonDir);
+}
+
+type FoundIdentity = { root: string; result: Awaited<ReturnType<typeof readIdentityFile>> };
+
+async function readPlainIdentity(start: string): Promise<FoundIdentity> {
+  const home = await canonicalPath(homedir());
   let directory = start;
   while (true) {
-    const result = await readIdentityFile(directory);
+    const result = await readIdentityFile(directory, { configurationOnlyAbsent: true });
     if (result.kind !== 'absent') return { root: directory, result };
-    if (directory === home) break;
+    if (samePath(directory, home)) break;
     const parent = dirname(directory);
     if (parent === directory) break;
     directory = parent;
@@ -192,6 +234,105 @@ async function readPlainIdentity(start: string): Promise<{
   return { root: start, result: { kind: 'absent' } };
 }
 
+/**
+ * Walk up from `start` to the nearest identity file, stopping at the home
+ * folder (whose own file still counts). A configuration-only file (no
+ * `projectId`) is not an identity and the walk passes it. Reaching the top of a linked worktree
+ * first ends the walk there: the worktree belongs to its main checkout, and
+ * the copy of the identity file at its top does not count.
+ */
+async function nearestIdentity(
+  start: string
+): Promise<FoundIdentity | { worktreeTop: string; commonDir: string } | undefined> {
+  const home = await canonicalPath(homedir());
+  let directory = start;
+  while (true) {
+    const commonDir = await linkedWorktreeCommonDir(directory);
+    if (commonDir) return { worktreeTop: directory, commonDir };
+    const result = await readIdentityFile(directory, { configurationOnlyAbsent: true });
+    if (result.kind !== 'absent') return { root: directory, result };
+    if (samePath(directory, home)) return undefined;
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+/**
+ * The project a working folder belongs to: the nearest `.mnemonik.json` above
+ * it. Git repositories are not project boundaries; a clone, submodule,
+ * subsystem or subproject inside a project belongs to that project unless it
+ * has its own identity file. Git has one part in identity: a linked worktree
+ * (and anything inside it without an identity file of its own below the
+ * worktree's top, nested clones and submodules included) belongs to the
+ * project of its main checkout; the worktree's own top-level copy of the
+ * identity file does not count.
+ */
+export async function resolveNearestProjectIdentity(
+  cwd: string
+): Promise<ProjectIdentityResolution> {
+  const start = await canonicalPath(cwd);
+  const resolved = await resolveRepositoryRoot(start);
+  const repository: ResolvedRepository =
+    resolved.kind === 'git_unavailable' ? { kind: 'plain', root: start } : resolved;
+  const nested = repository.kind === 'git' ? repository.nested : [];
+
+  let found = await nearestIdentity(start);
+  if (found && 'worktreeTop' in found) {
+    found = await readPlainIdentity(await mainCheckout(found.worktreeTop, found.commonDir));
+  }
+  if (found) {
+    return shapedIdentity(found, await projectFolderRepository(found.root, repository), nested);
+  }
+  return { ...withBase(repository, repository.root, nested), kind: 'absent' };
+}
+
+/**
+ * The identity of exactly the folder named, for commands that create or link
+ * a project there on purpose, even inside another project. The top of a
+ * linked worktree stands for its main checkout.
+ */
+async function resolveNamedProjectIdentity(
+  cwd: string,
+  options: { selectedRoot?: boolean }
+): Promise<ProjectIdentityResolution> {
+  const start = await canonicalPath(cwd);
+  const resolved = await resolveRepositoryRoot(start);
+  const repository: ResolvedRepository =
+    resolved.kind === 'git_unavailable' ? { kind: 'plain', root: start } : resolved;
+  const commonDir = await linkedWorktreeCommonDir(start);
+  const root = commonDir ? await mainCheckout(start, commonDir) : start;
+  return shapedIdentity(
+    { root, result: await readIdentityFile(root, options) },
+    await projectFolderRepository(root, repository),
+    repository.kind === 'git' ? repository.nested : []
+  );
+}
+
+function shapedIdentity(
+  found: FoundIdentity,
+  repository: ResolvedRepository,
+  nested: RepositoryBoundary[]
+): ProjectIdentityResolution {
+  const base = withBase(repository, found.root, nested);
+  if (found.result.kind === 'ok') return { ...base, ...found.result };
+  if (found.result.kind === 'unknown_version')
+    return { ...base, ...found.result, path: found.root };
+  if (found.result.kind === 'malformed') return { ...base, ...found.result, path: found.root };
+  return { ...base, kind: 'absent' };
+}
+
+/** The project folder counts as a git repository only when it is the repository's top. */
+async function projectFolderRepository(
+  projectRoot: string,
+  known: ResolvedRepository
+): Promise<ResolvedRepository> {
+  if (known.kind === 'git' && samePath(known.root, projectRoot)) return known;
+  const repository = await resolveRepositoryRoot(projectRoot);
+  if (repository.kind === 'git' && samePath(repository.root, projectRoot)) return repository;
+  return { kind: 'plain', root: projectRoot };
+}
+
 function withBase(
   repository: ResolvedRepository,
   root: string,
@@ -200,55 +341,20 @@ function withBase(
   return { root, repository, nested };
 }
 
+/**
+ * Which project a folder is in. By default this is the rule every reader
+ * shares with the hooks (resolveNearestProjectIdentity). `namedRoot` and
+ * `selectedRoot` read exactly the folder given instead, for commands that make
+ * that folder a project on purpose; `selectedRoot` (folders ticked during
+ * install) also treats a configuration-only file as no identity, as the
+ * nearest-file walk always does.
+ */
 export async function resolveProjectIdentity(
   cwd: string,
-  options: { allowNestedInherit?: boolean; selectedRoot?: boolean } = {}
+  options: { selectedRoot?: boolean; namedRoot?: boolean } = {}
 ): Promise<ProjectIdentityResolution> {
-  const resolved = await resolveRepositoryRoot(cwd);
-  // Git is optional. When the git command cannot answer, the folder is still a folder.
-  const repository: ResolvedRepository =
-    resolved.kind === 'git_unavailable' ? { kind: 'plain', root: resolve(cwd) } : resolved;
-
-  if (repository.kind === 'plain') {
-    const { root, result } = options.selectedRoot
-      ? { root: repository.root, result: await readIdentityFile(repository.root, options) }
-      : await readPlainIdentity(repository.root);
-    const base = withBase(repository, root, []);
-    if (result.kind === 'ok') return { ...base, ...result };
-    if (result.kind === 'unknown_version') return { ...base, ...result, path: root };
-    if (result.kind === 'malformed') return { ...base, ...result, path: root };
-    return { ...base, kind: 'absent' };
-  }
-
-  const ownRoot = repository.isLinkedWorktree ? dirname(repository.commonDir) : repository.root;
-  const outer = repository.isLinkedWorktree
-    ? undefined
-    : await containingRepository(repository.root);
-  const own = await readIdentityFile(ownRoot, options);
-  if (!outer || options.selectedRoot || own.kind === 'ok') {
-    const base = withBase(repository, ownRoot, repository.nested);
-    if (own.kind === 'ok') return { ...base, ...own };
-    if (own.kind === 'unknown_version') return { ...base, ...own, path: ownRoot };
-    if (own.kind === 'malformed') return { ...base, ...own, path: ownRoot };
-    return { ...base, kind: 'absent' };
+  if (options.selectedRoot || options.namedRoot) {
+    return resolveNamedProjectIdentity(cwd, { selectedRoot: options.selectedRoot });
   }
-
-  const nested = repository.nested;
-  const parentRoot = await canonicalBoundaryRoot(outer);
-  const parent = await readIdentityFile(parentRoot);
-  const base = withBase(repository, parentRoot, nested);
-
-  if (own.kind === 'unknown_version') return { ...base, ...own, path: ownRoot };
-  if (own.kind === 'malformed') return { ...base, ...own, path: ownRoot };
-  if (parent.kind === 'unknown_version') return { ...base, ...parent, path: parentRoot };
-  if (parent.kind === 'malformed') return { ...base, ...parent, path: parentRoot };
-  if (!options.allowNestedInherit) {
-    return {
-      ...base,
-      kind: 'nested',
-      ...(parent.kind === 'ok' ? { parentIdentity: parent.identity } : {}),
-    };
-  }
-  if (parent.kind === 'ok') return { ...base, kind: 'ok', identity: parent.identity };
-  return { ...base, kind: 'absent' };
+  return resolveNearestProjectIdentity(cwd);
 }

package/src/runtimeReader.ts

@@ -21,7 +21,12 @@ export type Reason =
   | 'unsigned'
   | 'permission'
   | 'acl_unavailable'
-  | 'lock_held';
+  | 'lock_held'
+  // The registry answered without the package (404, 429 or 5xx): a fresh release
+  // still reaching its CDN, a busy registry, or a pin it does not have.
+  | 'registry_unavailable'
+  // The registry could not be reached at all: offline, DNS, refused, timed out.
+  | 'registry_unreachable';
 export class RuntimeError extends Error {
   constructor(public readonly reason: Reason) {
     super(reason);

package/test-fixtures/identity/runner.d.mts

@@ -2,7 +2,7 @@ export interface IdentityFixtureAdapter {
   parse(text: string): unknown;
   read(dir: string): Promise<unknown>;
   resolveRoot(cwd: string): Promise<unknown>;
-  resolve(cwd: string, options?: { allowNestedInherit?: boolean }): Promise<unknown>;
+  resolve(cwd: string, options?: { namedRoot?: boolean }): Promise<unknown>;
   find?(cwd: string): Promise<unknown>;
 }