@jim80net/memex-core 0.3.1 → 0.5.0

package/README.md

@@ -174,6 +174,36 @@ boost: 0.05
 
 Consumers typically extend `MemexCoreConfig` with platform-specific fields (hooks config, sync config, sleep schedule, etc.) and handle file loading themselves.
 
+## Sync
+
+The `sync` module provides Git-based cross-device sync via `syncPull` and `syncCommitAndPush`. Both accept a `SyncConfig` object.
+
+### Case-insensitive project IDs (default)
+
+Project IDs are lowercased by default across all three resolution paths
+(manual mappings, git remote URLs, and encoded `_local/` path fallbacks).
+A clone of `git@github.com:Jim80Net/Repo.git` and `git@github.com:jim80net/repo.git`
+now map to the same canonical id: `github.com/jim80net/repo`.
+
+To preserve the original case, set `caseSensitive: true` in your sync config:
+
+```typescript
+const syncConfig: SyncConfig = {
+  enabled: true,
+  repo: "git@github.com:me/memex-sync.git",
+  autoPull: true,
+  autoCommitPush: true,
+  projectMappings: {},
+  caseSensitive: true, // preserve case as-is
+};
+```
+
+On first sync after upgrading from a version that wrote mixed-case directories,
+`syncPull` will run a one-shot migration that renames legacy paths to lowercase
+and writes a `.memex-sync/version.json` marker so the scan only runs once. The
+migration is safe across devices (only runs against post-pull state), idempotent,
+and handles case-insensitive filesystems (macOS APFS, Windows NTFS) correctly.
+
 ## Development
 
 ```bash

package/dist/cache.js

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-const CACHE_VERSION = 2;
+const CACHE_VERSION = 3;
 export async function loadCache(cachePath, embeddingModel) {
     const empty = { version: CACHE_VERSION, embeddingModel, skills: {} };
     try {

package/dist/git-helpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Run a git command inside a directory. 30s timeout.
+ */
+export declare function git(args: string[], cwd: string): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function isGitRepo(dir: string): Promise<boolean>;
+export declare function hasRemote(dir: string): Promise<boolean>;
+export declare function hasCommits(dir: string): Promise<boolean>;
+export declare function getDefaultBranch(dir: string): Promise<string>;
+//# sourceMappingURL=git-helpers.d.ts.map

package/dist/git-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-helpers.d.ts","sourceRoot":"","sources":["../src/git-helpers.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,wBAAsB,GAAG,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAE7C;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO7D;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO7D;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9D;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBnE"}

package/dist/git-helpers.js

@@ -0,0 +1,58 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Run a git command inside a directory. 30s timeout.
+ */
+export async function git(args, cwd) {
+    return execFileAsync("git", args, { cwd, timeout: 30_000 });
+}
+export async function isGitRepo(dir) {
+    try {
+        await git(["rev-parse", "--git-dir"], dir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function hasRemote(dir) {
+    try {
+        const { stdout } = await git(["remote"], dir);
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export async function hasCommits(dir) {
+    try {
+        await git(["rev-parse", "HEAD"], dir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function getDefaultBranch(dir) {
+    try {
+        const { stdout } = await git(["symbolic-ref", "refs/remotes/origin/HEAD"], dir);
+        const ref = stdout.trim();
+        const branch = ref.replace(/^refs\/remotes\/origin\//, "");
+        if (branch)
+            return branch;
+    }
+    catch {
+        try {
+            const { stdout } = await git(["ls-remote", "--symref", "origin", "HEAD"], dir);
+            const match = stdout.match(/ref:\s+refs\/heads\/(\S+)/);
+            if (match)
+                return match[1];
+        }
+        catch {
+            // Fall through to default
+        }
+    }
+    return "main";
+}
+//# sourceMappingURL=git-helpers.js.map

package/dist/git-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-helpers.js","sourceRoot":"","sources":["../src/git-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,IAAc,EACd,GAAW;IAEX,OAAO,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW;IACzC,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC;QAC9C,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW;IAC1C,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAW;IAChD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,cAAc,EAAE,0BAA0B,CAAC,EAAE,GAAG,CAAC,CAAC;QAChF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC;QAC3D,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;YAC/E,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;YACxD,IAAI,KAAK;gBAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,0BAA0B;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -3,12 +3,16 @@ export * from "./config.js";
 export * from "./embeddings.js";
 export * from "./file-lock.js";
 export * from "./path-encoder.js";
+export type { HarnessKind, PortableLocationWarn, ResolvedPortableLocation, ScanRoot, ScanRootContext, ScanRootRegistry, ScanRootSpec, } from "./portable-location.js";
+export { buildScanRoots, decodeFragment, decodePortableLocation, decodePortableLocationResolved, encodeFragment, encodePortableLocation, escapePortableText, HANDLE_PREFIX, resolvePortableLocation, resolvePortableLocationResolved, splitPortableHandle, stableUnclassifiedKey, unescapePortableText, } from "./portable-location.js";
 export * from "./project-mapping.js";
 export * from "./project-registry.js";
 export * from "./session.js";
-export type { ScanDirs } from "./skill-index.js";
+export type { ScanDirs, SkillIndexOptions } from "./skill-index.js";
 export { parseFrontmatter, parseMemoryFile, SkillIndex } from "./skill-index.js";
 export { autoResolveMarkdownConflict, getSyncScanDirs, initSyncRepo, syncCommitAndPush, syncPull, } from "./sync.js";
+export type { MigrationResult } from "./sync-migration.js";
+export { migrateProjectIdsToLowercase, readSyncRepoVersion, runSyncMigrations, writeSyncRepoVersion, } from "./sync-migration.js";
 export * from "./telemetry.js";
 export * from "./traces.js";
 export * from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,QAAQ,GACT,MAAM,WAAW,CAAC;AACnB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,YAAY,EACV,WAAW,EACX,oBAAoB,EACpB,wBAAwB,EACxB,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,YAAY,GACb,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,8BAA8B,EAC9B,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAClB,aAAa,EACb,uBAAuB,EACvB,+BAA+B,EAC/B,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,QAAQ,GACT,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACL,4BAA4B,EAC5B,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -3,11 +3,13 @@ export * from "./config.js";
 export * from "./embeddings.js";
 export * from "./file-lock.js";
 export * from "./path-encoder.js";
+export { buildScanRoots, decodeFragment, decodePortableLocation, decodePortableLocationResolved, encodeFragment, encodePortableLocation, escapePortableText, HANDLE_PREFIX, resolvePortableLocation, resolvePortableLocationResolved, splitPortableHandle, stableUnclassifiedKey, unescapePortableText, } from "./portable-location.js";
 export * from "./project-mapping.js";
 export * from "./project-registry.js";
 export * from "./session.js";
 export { parseFrontmatter, parseMemoryFile, SkillIndex } from "./skill-index.js";
 export { autoResolveMarkdownConflict, getSyncScanDirs, initSyncRepo, syncCommitAndPush, syncPull, } from "./sync.js";
+export { migrateProjectIdsToLowercase, readSyncRepoVersion, runSyncMigrations, writeSyncRepoVersion, } from "./sync-migration.js";
 export * from "./telemetry.js";
 export * from "./traces.js";
 export * from "./types.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAE7B,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,QAAQ,GACT,MAAM,WAAW,CAAC;AACnB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAUlC,OAAO,EACL,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,8BAA8B,EAC9B,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAClB,aAAa,EACb,uBAAuB,EACvB,+BAA+B,EAC/B,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAE7B,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,QAAQ,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,4BAA4B,EAC5B,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/portable-location.d.ts

@@ -0,0 +1,84 @@
+import type { ScanDirs } from "./skill-index.js";
+/** A scan root with a stable, host-free label for portable handles. */
+export type ScanRoot = {
+    key: string;
+    rootPath: string;
+};
+export type ScanRootRegistry = ScanRoot[];
+export type ScanRootSpec = ScanDirs;
+export type HarnessKind = "grok" | "claude" | "codex" | "hermes";
+export type ScanRootContext = {
+    cwd: string;
+    syncRepoDir?: string;
+    syncEnabled?: boolean;
+    globalSkillsDirs: string[];
+    globalRulesDirs: string[];
+    projectSkillsDir: string;
+    projectRulesDir: string;
+    harness: HarnessKind;
+};
+export declare const HANDLE_PREFIX = "memex://";
+export type PortableLocationWarn = (message: string) => void;
+/** Filesystem path + optional memory section name (fragment decoded once). */
+export type ResolvedPortableLocation = {
+    filePath: string;
+    sectionName?: string;
+};
+/**
+ * Portable handles are opaque location tokens — not general URIs.
+ * Form: memex://{rootKey}/{posix-rel}[#{fragment}]
+ */
+/** Injective escape for rel segments and fragments (% first, then #). */
+export declare function escapePortableText(text: string): string;
+/** Reverse of escapePortableText (# last on decode, then %). */
+export declare function unescapePortableText(text: string): string;
+/** @alias escapePortableText */
+export declare const encodeFragment: typeof escapePortableText;
+/** @alias unescapePortableText */
+export declare const decodeFragment: typeof unescapePortableText;
+/**
+ * Split at the last literal '#' — escaped #s are %23 and do not split.
+ * Fragment is unescaped exactly once.
+ */
+export declare function splitPortableHandle(handle: string): {
+    body: string;
+    fragment?: string;
+};
+/** Stable fallback rootKey from normalized absolute dir path (§4.4 path-hash option). */
+export declare function stableUnclassifiedKey(kind: "skill" | "rule" | "memory", dir: string): string;
+/**
+ * Build labeled scan roots from harness context and scan directory spec.
+ * Same semantic root MUST use the same rootKey on every host (normative catalog).
+ */
+export declare function buildScanRoots(ctx: ScanRootContext, spec: ScanRootSpec): ScanRootRegistry;
+/**
+ * Absolute path (+ optional #fragment) → portable handle.
+ * Fail-open: returns null when mapping is impossible (caller should skip-with-warning).
+ */
+export declare function encodePortableLocation(registry: ScanRootRegistry, absolute: string, warn?: PortableLocationWarn, fragment?: string): string | null;
+/**
+ * Portable handle → absolute file path + optional section name.
+ * Fragment is split and %23-unescaped exactly once — never rejoin with '#'.
+ * Fail-closed on traversal escape.
+ */
+export declare function decodePortableLocationResolved(registry: ScanRootRegistry, handle: string): ResolvedPortableLocation;
+/**
+ * Portable handle → absolute path string (legacy join form).
+ * Prefer decodePortableLocationResolved when a fragment may be present.
+ */
+export declare function decodePortableLocation(registry: ScanRootRegistry, handle: string): string;
+/**
+ * Resolve portable handle or legacy absolute path for filesystem I/O.
+ * Phase 2: agent-facing read tools MUST pass `allowAbsolute: false` so untrusted
+ * absolute paths cannot bypass containment (memex-grok#19 closes only then).
+ */
+export declare function resolvePortableLocationResolved(registry: ScanRootRegistry, input: string, options?: {
+    warn?: PortableLocationWarn;
+    allowAbsolute?: boolean;
+}): ResolvedPortableLocation;
+/** @deprecated Prefer resolvePortableLocationResolved to avoid fragment double-decode. */
+export declare function resolvePortableLocation(registry: ScanRootRegistry, input: string, options?: {
+    warn?: PortableLocationWarn;
+    allowAbsolute?: boolean;
+}): string;
+//# sourceMappingURL=portable-location.d.ts.map

package/dist/portable-location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-location.d.ts","sourceRoot":"","sources":["../src/portable-location.ts"],"names":[],"mappings":"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"}

package/dist/portable-location.js

@@ -0,0 +1,248 @@
+import { createHash } from "node:crypto";
+import { join, relative, resolve, sep } from "node:path";
+export const HANDLE_PREFIX = "memex://";
+/**
+ * Portable handles are opaque location tokens — not general URIs.
+ * Form: memex://{rootKey}/{posix-rel}[#{fragment}]
+ */
+/** Injective escape for rel segments and fragments (% first, then #). */
+export function escapePortableText(text) {
+    return text.replace(/%/g, "%25").replace(/#/g, "%23");
+}
+/** Reverse of escapePortableText (# last on decode, then %). */
+export function unescapePortableText(text) {
+    return text.replace(/%23/g, "#").replace(/%25/g, "%");
+}
+/** @alias escapePortableText */
+export const encodeFragment = escapePortableText;
+/** @alias unescapePortableText */
+export const decodeFragment = unescapePortableText;
+/**
+ * Split at the last literal '#' — escaped #s are %23 and do not split.
+ * Fragment is unescaped exactly once.
+ */
+export function splitPortableHandle(handle) {
+    const lastHash = handle.lastIndexOf("#");
+    if (lastHash === -1)
+        return { body: handle };
+    return {
+        body: handle.slice(0, lastHash),
+        fragment: unescapePortableText(handle.slice(lastHash + 1)),
+    };
+}
+function encodeRelPath(rel) {
+    return normalizeRel(rel).split("/").map(escapePortableText).join("/");
+}
+function decodeRelPath(rel) {
+    return rel.split("/").map(unescapePortableText).join("/");
+}
+function normalizeRel(rel) {
+    return rel.split(sep).join("/");
+}
+function isAbsolutePath(p) {
+    return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p);
+}
+function hasUnsafeRelSegments(rel) {
+    const segments = rel.split("/");
+    return segments.some((s) => s === ".." || s === "");
+}
+function isPathContained(rootPath, absolute) {
+    const root = resolve(rootPath);
+    const normalized = resolve(absolute);
+    return normalized === root || normalized.startsWith(root + sep);
+}
+function sortRegistry(roots) {
+    return [...roots].sort((a, b) => b.rootPath.length - a.rootPath.length);
+}
+function matchRoot(registry, filePath) {
+    const normalized = resolve(filePath);
+    return registry.find((r) => isPathContained(r.rootPath, normalized));
+}
+function pathHasSegment(resolvedPath, segment) {
+    return resolve(resolvedPath).split(sep).includes(segment);
+}
+/** Stable fallback rootKey from normalized absolute dir path (§4.4 path-hash option). */
+export function stableUnclassifiedKey(kind, dir) {
+    const hash = createHash("sha256").update(resolve(dir)).digest("hex").slice(0, 8);
+    return `${kind}-unclassified-${hash}`;
+}
+/**
+ * Build labeled scan roots from harness context and scan directory spec.
+ * Same semantic root MUST use the same rootKey on every host (normative catalog).
+ */
+export function buildScanRoots(ctx, spec) {
+    const harness = ctx.harness;
+    const roots = [];
+    const seen = new Set();
+    const add = (key, dir) => {
+        const rootPath = resolve(dir);
+        if (seen.has(rootPath))
+            return;
+        seen.add(rootPath);
+        roots.push({ key, rootPath });
+    };
+    const globalSkillKeys = new Map();
+    for (const dir of ctx.globalSkillsDirs) {
+        const resolved = resolve(dir);
+        if (pathHasSegment(resolved, ".grok")) {
+            globalSkillKeys.set(resolved, "grok-global");
+        }
+        else if (pathHasSegment(resolved, ".claude")) {
+            globalSkillKeys.set(resolved, "claude-global");
+        }
+        else if (pathHasSegment(resolved, ".codex")) {
+            globalSkillKeys.set(resolved, "codex-global");
+        }
+        else if (pathHasSegment(resolved, ".hermes")) {
+            globalSkillKeys.set(resolved, "hermes-global");
+        }
+    }
+    const globalRuleKeys = new Map();
+    for (const dir of ctx.globalRulesDirs) {
+        const resolved = resolve(dir);
+        if (pathHasSegment(resolved, ".grok")) {
+            globalRuleKeys.set(resolved, "grok-rules-global");
+        }
+        else if (pathHasSegment(resolved, ".claude")) {
+            globalRuleKeys.set(resolved, "claude-rules-global");
+        }
+        else if (pathHasSegment(resolved, ".codex")) {
+            globalRuleKeys.set(resolved, "codex-rules-global");
+        }
+        else if (pathHasSegment(resolved, ".hermes")) {
+            globalRuleKeys.set(resolved, "hermes-rules-global");
+        }
+    }
+    const projectSkillsResolved = resolve(ctx.projectSkillsDir);
+    const projectRulesResolved = resolve(ctx.projectRulesDir);
+    const syncSkillsDir = ctx.syncEnabled && ctx.syncRepoDir ? resolve(join(ctx.syncRepoDir, "skills")) : undefined;
+    const syncRulesDir = ctx.syncEnabled && ctx.syncRepoDir ? resolve(join(ctx.syncRepoDir, "rules")) : undefined;
+    const unclassifiedSkillDirs = [];
+    for (const dir of spec.skillDirs) {
+        const resolved = resolve(dir);
+        const catalogKey = globalSkillKeys.get(resolved);
+        if (catalogKey) {
+            add(catalogKey, dir);
+        }
+        else if (resolved === projectSkillsResolved) {
+            add(`${harness}-project`, dir);
+        }
+        else if (syncSkillsDir && resolved === syncSkillsDir) {
+            add("sync-skills", dir);
+        }
+        else {
+            unclassifiedSkillDirs.push(dir);
+        }
+    }
+    for (const dir of unclassifiedSkillDirs) {
+        add(stableUnclassifiedKey("skill", dir), dir);
+    }
+    const unclassifiedRuleDirs = [];
+    for (const dir of spec.ruleDirs) {
+        const resolved = resolve(dir);
+        const catalogKey = globalRuleKeys.get(resolved);
+        if (catalogKey) {
+            add(catalogKey, dir);
+        }
+        else if (resolved === projectRulesResolved) {
+            add(`${harness}-rules-project`, dir);
+        }
+        else if (syncRulesDir && resolved === syncRulesDir) {
+            add("sync-rules", dir);
+        }
+        else {
+            unclassifiedRuleDirs.push(dir);
+        }
+    }
+    for (const dir of unclassifiedRuleDirs) {
+        add(stableUnclassifiedKey("rule", dir), dir);
+    }
+    for (const dir of spec.memoryDirs) {
+        add(stableUnclassifiedKey("memory", dir), dir);
+    }
+    return sortRegistry(roots);
+}
+/**
+ * Absolute path (+ optional #fragment) → portable handle.
+ * Fail-open: returns null when mapping is impossible (caller should skip-with-warning).
+ */
+export function encodePortableLocation(registry, absolute, warn, fragment) {
+    const body = resolve(absolute);
+    const root = matchRoot(registry, body);
+    if (!root) {
+        warn?.(`skipped indexing ${absolute} — no portable handle (outside registered scan roots)`);
+        return null;
+    }
+    const rel = normalizeRel(relative(root.rootPath, body));
+    if (hasUnsafeRelSegments(rel)) {
+        warn?.(`skipped indexing ${absolute} — no portable handle (unsafe relative path: ${rel})`);
+        return null;
+    }
+    const handle = `${HANDLE_PREFIX}${root.key}/${encodeRelPath(rel)}`;
+    if (fragment === undefined)
+        return handle;
+    return `${handle}#${escapePortableText(fragment)}`;
+}
+/**
+ * Portable handle → absolute file path + optional section name.
+ * Fragment is split and %23-unescaped exactly once — never rejoin with '#'.
+ * Fail-closed on traversal escape.
+ */
+export function decodePortableLocationResolved(registry, handle) {
+    if (!handle.startsWith(HANDLE_PREFIX)) {
+        throw new Error(`invalid portable location handle: ${handle}`);
+    }
+    const { body, fragment: sectionName } = splitPortableHandle(handle);
+    const pathBody = body.slice(HANDLE_PREFIX.length);
+    const slash = pathBody.indexOf("/");
+    if (slash === -1) {
+        throw new Error(`invalid portable location handle (missing path segment): ${handle}`);
+    }
+    const key = pathBody.slice(0, slash);
+    const rel = decodeRelPath(pathBody.slice(slash + 1));
+    if (hasUnsafeRelSegments(rel)) {
+        throw new Error(`portable location handle escapes scan root: ${handle}`);
+    }
+    const root = registry.find((r) => r.key === key);
+    if (!root) {
+        throw new Error(`unknown portable location root '${key}'`);
+    }
+    const filePath = resolve(root.rootPath, rel);
+    if (!isPathContained(root.rootPath, filePath)) {
+        throw new Error(`portable location handle escapes scan root: ${handle}`);
+    }
+    return sectionName !== undefined ? { filePath, sectionName } : { filePath };
+}
+/**
+ * Portable handle → absolute path string (legacy join form).
+ * Prefer decodePortableLocationResolved when a fragment may be present.
+ */
+export function decodePortableLocation(registry, handle) {
+    const { filePath, sectionName } = decodePortableLocationResolved(registry, handle);
+    return sectionName !== undefined ? `${filePath}#${sectionName}` : filePath;
+}
+/**
+ * Resolve portable handle or legacy absolute path for filesystem I/O.
+ * Phase 2: agent-facing read tools MUST pass `allowAbsolute: false` so untrusted
+ * absolute paths cannot bypass containment (memex-grok#19 closes only then).
+ */
+export function resolvePortableLocationResolved(registry, input, options) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return { filePath: trimmed };
+    if (trimmed.startsWith(HANDLE_PREFIX)) {
+        return decodePortableLocationResolved(registry, trimmed);
+    }
+    if (options?.allowAbsolute !== false && isAbsolutePath(trimmed)) {
+        options?.warn?.(`deprecated: readSkillContent received absolute path; use portable memex:// handles`);
+        const { body, fragment } = splitPortableHandle(trimmed);
+        return fragment !== undefined ? { filePath: body, sectionName: fragment } : { filePath: body };
+    }
+    throw new Error(`unrecognized location: ${input}`);
+}
+/** @deprecated Prefer resolvePortableLocationResolved to avoid fragment double-decode. */
+export function resolvePortableLocation(registry, input, options) {
+    const { filePath, sectionName } = resolvePortableLocationResolved(registry, input, options);
+    return sectionName !== undefined ? `${filePath}#${sectionName}` : filePath;
+}
+//# sourceMappingURL=portable-location.js.map

package/dist/portable-location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-location.js","sourceRoot":"","sources":["../src/portable-location.ts"],"names":[],"mappings":"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"}

package/dist/project-mapping.d.ts

@@ -3,11 +3,17 @@ import type { SyncConfig } from "./types.js";
  * Normalize a git remote URL to a canonical path segment.
  * Handles SSH, HTTPS, and .git suffix variations.
  *
+ * By default the result is lowercased so that clones of the same repo with
+ * different casing (`GitHub.com:Jim80Net/Repo` vs `github.com:jim80net/repo`)
+ * collapse onto a single canonical project id. Pass `caseSensitive = true`
+ * to preserve the original case.
+ *
  * Examples:
  *   git@github.com:jim80net/repo.git → github.com/jim80net/repo
+ *   git@GitHub.com:Jim80Net/Repo.git → github.com/jim80net/repo
  *   https://github.com/jim80net/repo.git → github.com/jim80net/repo
  */
-export declare function normalizeGitUrl(url: string): string;
+export declare function normalizeGitUrl(url: string, caseSensitive?: boolean): string;
 /**
  * Resolve the canonical project identifier for a given cwd.
  *
@@ -15,11 +21,22 @@ export declare function normalizeGitUrl(url: string): string;
  * 1. Manual mapping from config (explicit override)
  * 2. Git remote URL → normalized to host/owner/repo
  * 3. Encoded cwd path → stored under _local/
+ *
+ * All three paths are lowercased by default. Set `syncConfig.caseSensitive`
+ * to `true` to preserve the original casing.
  */
 export declare function resolveProjectId(cwd: string, syncConfig: SyncConfig): Promise<string>;
 /**
  * Find all project memory directories in the sync repo that match the current cwd.
- * Multiple matches are possible (e.g., same project stored under both URL and encoded path).
+ *
+ * Returns:
+ * - The canonical (lowercase) memory dir if it exists.
+ * - The `_local/<encoded>` fallback if it exists and differs from the canonical.
+ * - Any legacy mixed-case directory whose lowercase form equals the canonical id
+ *   (rollout window before a post-upgrade sync has migrated the repo).
+ *
+ * Multiple matches are expected during the upgrade window; callers should merge
+ * their contents.
  */
 export declare function findMatchingProjectMemoryDirs(cwd: string, syncRepoPath: string, syncConfig: SyncConfig): Promise<string[]>;
 /**

package/dist/project-mapping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-mapping.d.ts","sourceRoot":"","sources":["../src/project-mapping.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAmBnD;AAkBD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAc3F;AAED;;;GAGG;AACH,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBnB;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,MAAM,CAAC,CAGjB"}
+{"version":3,"file":"project-mapping.d.ts","sourceRoot":"","sources":["../src/project-mapping.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,UAAQ,GAAG,MAAM,CAqB1E;AAkBD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,MAAM,EAAE,CAAC,CA+BnB;AAmDD;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,MAAM,CAAC,CAGjB"}