facult 1.0.2 → 1.1.0

package/src/paths.ts

@@ -43,6 +43,11 @@ function isSafePathString(p: string): boolean {
   return !p.includes("\0");
 }
 
+function defaultHomeDir(): string {
+  const fromEnv = process.env.HOME?.trim();
+  return fromEnv || homedir();
+}
+
 function expandHomePath(p: string, home: string): string {
   if (p === "~") {
     return home;
@@ -74,13 +79,22 @@ function fileExists(p: string): boolean {
   }
 }
 
+function legacyPreferredRoot(home: string): string {
+  return join(home, "agents", ".facult");
+}
+
+function isLegacyConfiguredRoot(root: string, home: string): boolean {
+  return resolve(root) === resolve(legacyPreferredRoot(home));
+}
+
 function looksLikeFacultRoot(root: string): boolean {
   if (!dirExists(root)) {
     return false;
   }
   // Heuristic: treat as a facult store if it contains something we'd create.
   return (
-    fileExists(join(root, "index.json")) ||
+    dirExists(join(root, "rules")) ||
+    dirExists(join(root, "agents")) ||
     dirExists(join(root, "skills")) ||
     dirExists(join(root, "mcp")) ||
     dirExists(join(root, "snippets"))
@@ -117,16 +131,24 @@ function detectLegacyStoreUnderAgents(home: string): string | null {
   return candidates.length === 1 ? (candidates[0] ?? null) : null;
 }
 
-export function facultStateDir(home: string = homedir()): string {
+export function facultStateDir(home: string = defaultHomeDir()): string {
   return join(home, ".facult");
 }
 
-export function facultConfigPath(home: string = homedir()): string {
+export function facultAiStateDir(home: string = defaultHomeDir()): string {
+  return join(facultStateDir(home), "ai");
+}
+
+export function facultAiIndexPath(home: string = defaultHomeDir()): string {
+  return join(facultAiStateDir(home), "index.json");
+}
+
+export function facultConfigPath(home: string = defaultHomeDir()): string {
   return join(facultStateDir(home), "config.json");
 }
 
 export function readFacultConfig(
-  home: string = homedir()
+  home: string = defaultHomeDir()
 ): FacultConfig | null {
   const p = facultConfigPath(home);
   if (!(isSafePathString(p) && fileExists(p))) {
@@ -203,33 +225,43 @@ export function readFacultConfig(
  * Precedence:
  * 1) `FACULT_ROOT_DIR` env var
  * 2) `~/.facult/config.json` { "rootDir": "..." }
- * 3) `~/agents/.facult` (if it looks like a store)
- * 4) a legacy store under `~/agents/` (if it looks like a store)
- * 5) default: `~/agents/.facult`
+ * 3) `~/.ai` (if it looks like a store)
+ * 4) `~/agents/.facult` (if it looks like a store)
+ * 5) a legacy store under `~/agents/` (if it looks like a store)
+ * 6) default: `~/.ai`
  */
-export function facultRootDir(home: string = homedir()): string {
+export function facultRootDir(home: string = defaultHomeDir()): string {
   const envRoot = process.env.FACULT_ROOT_DIR?.trim();
+  const preferred = join(home, ".ai");
+
   if (envRoot) {
     const resolved = resolvePath(envRoot, home);
-    return isSafePathString(resolved)
-      ? resolved
-      : join(home, "agents", ".facult");
+    return isSafePathString(resolved) ? resolved : preferred;
   }
 
   const cfg = readFacultConfig(home);
   const cfgRoot = cfg?.rootDir?.trim();
   if (cfgRoot) {
     const resolved = resolvePath(cfgRoot, home);
-    return isSafePathString(resolved)
-      ? resolved
-      : join(home, "agents", ".facult");
+    if (!isSafePathString(resolved)) {
+      return preferred;
+    }
+    if (
+      isLegacyConfiguredRoot(resolved, home) &&
+      looksLikeFacultRoot(preferred)
+    ) {
+      return preferred;
+    }
+    return resolved;
   }
 
-  const preferred = join(home, "agents", ".facult");
-
   if (looksLikeFacultRoot(preferred)) {
     return preferred;
   }
+  const legacyPreferred = legacyPreferredRoot(home);
+  if (looksLikeFacultRoot(legacyPreferred)) {
+    return legacyPreferred;
+  }
   const legacy = detectLegacyStoreUnderAgents(home);
   if (legacy) {
     return legacy;

package/src/query.ts

@@ -1,5 +1,5 @@
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { ensureAiIndexPath } from "./ai-state";
 import type {
   AgentEntry,
   FacultIndex,
@@ -7,7 +7,7 @@ import type {
   SkillEntry,
   SnippetEntry,
 } from "./index-builder";
-import { facultRootDir } from "./paths";
+import { facultAiIndexPath, facultRootDir } from "./paths";
 import { applyOrgTrustList } from "./trust-list";
 
 export interface QueryFilters {
@@ -108,7 +108,7 @@ export function facultRootDirPath(home: string = homedir()): string {
  * Return the path to the facult index.json file.
  */
 export function facultIndexPath(home: string = homedir()): string {
-  return join(facultRootDir(home), "index.json");
+  return facultAiIndexPath(home);
 }
 
 /**
@@ -120,15 +120,24 @@ export async function loadIndex(opts?: {
   /** Override home directory for org trust-list loading (useful for tests). */
   homeDir?: string;
 }): Promise<FacultIndex> {
-  const root = opts?.rootDir ?? facultRootDir();
-  const indexPath = join(root, "index.json");
+  const homeDir = opts?.homeDir;
+  const resolvedHome = homeDir ?? process.env.HOME;
+  if (!resolvedHome) {
+    throw new Error("HOME is not set.");
+  }
+  const rootDir = opts?.rootDir ?? facultRootDir(resolvedHome);
+  const { path: indexPath } = await ensureAiIndexPath({
+    homeDir: resolvedHome,
+    rootDir,
+    repair: true,
+  });
   const file = Bun.file(indexPath);
   if (!(await file.exists())) {
     throw new Error(`Index not found at ${indexPath}. Run "facult index".`);
   }
   const raw = await file.text();
   const parsed = JSON.parse(raw) as FacultIndex;
-  return await applyOrgTrustList(parsed, { homeDir: opts?.homeDir });
+  return await applyOrgTrustList(parsed, { homeDir: resolvedHome });
 }
 
 /**

package/src/remote.ts

@@ -1106,7 +1106,11 @@ async function installParsedItem(args: {
     updatedAt: nowIso(args.now),
     items: dedup.sort((a, b) => a.ref.localeCompare(b.ref)),
   });
-  await buildIndex({ rootDir: args.rootDir, force: false });
+  await buildIndex({
+    rootDir: args.rootDir,
+    homeDir: args.homeDir,
+    force: false,
+  });
   return result;
 }
 

package/src/snippets.ts

@@ -230,6 +230,12 @@ export interface SyncResult {
   errors: string[];
 }
 
+export interface RenderSnippetTextResult {
+  text: string;
+  changes: SyncChange[];
+  errors: string[];
+}
+
 function isSafePathString(p: string): boolean {
   // Protect filesystem APIs from null-byte paths.
   return !p.includes("\0");
@@ -564,6 +570,106 @@ export async function syncFile(args: {
   return { filePath, dryRun, changed: true, changes, errors: [] };
 }
 
+export async function renderSnippetText(args: {
+  text: string;
+  project?: string | null;
+  filePath?: string;
+  rootDir?: string;
+}): Promise<RenderSnippetTextResult> {
+  const rootDir = args.rootDir ?? facultRootDir();
+  const text = args.text;
+  const filePath = args.filePath;
+  const errors: string[] = [];
+  const changes: SyncChange[] = [];
+
+  if (!hasMarkers(text)) {
+    return { text, changes, errors };
+  }
+
+  const found = findMarkersInText(text, filePath);
+  if (found.errors.length) {
+    return {
+      text,
+      changes,
+      errors: found.errors,
+    };
+  }
+
+  let lastEnd = -1;
+  for (const p of found.pairs) {
+    if (p.open.start < lastEnd) {
+      const location = filePath
+        ? `${filePath}:${p.open.line}`
+        : `line ${p.open.line}`;
+      errors.push(
+        `${location}: snippet markers may not be nested or overlapping (found ${p.name})`
+      );
+    }
+    lastEnd = p.close.end;
+  }
+  if (errors.length) {
+    return { text, changes, errors };
+  }
+
+  type Replacement = { start: number; end: number; next: string };
+  const replacements: Replacement[] = [];
+
+  for (const pair of found.pairs) {
+    const marker = pair.name;
+    const existing = text.slice(pair.contentStart, pair.contentEnd);
+    const existingNorm = normalizeSnippetBody(existing);
+
+    const snippet = await findSnippet({
+      marker,
+      project: args.project ?? null,
+      rootDir,
+    });
+
+    if (!snippet) {
+      changes.push({ marker, status: "not-found" });
+      continue;
+    }
+
+    const snippetNorm = normalizeSnippetBody(snippet.content);
+    if (existingNorm === snippetNorm) {
+      changes.push({
+        marker,
+        status: "unchanged",
+        snippetPath: snippet.path,
+        lines: countLines(snippetNorm),
+      });
+      continue;
+    }
+
+    replacements.push({
+      start: pair.contentStart,
+      end: pair.contentEnd,
+      next: formatSnippetInjection(snippet.content),
+    });
+    changes.push({
+      marker,
+      status: "updated",
+      snippetPath: snippet.path,
+      lines: countLines(snippetNorm),
+    });
+  }
+
+  if (replacements.length === 0) {
+    return { text, changes, errors };
+  }
+
+  let updated = text;
+  for (const r of replacements.sort((a, b) => b.start - a.start)) {
+    updated = updated.slice(0, r.start) + r.next + updated.slice(r.end);
+  }
+
+  return {
+    text: updated,
+    changes,
+    errors,
+  };
+}
+
 export async function syncAll(args?: {
   dryRun?: boolean;
   /** Override canonical root (useful for tests). */

package/src/trust.ts

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { ensureAiIndexPath } from "./ai-state";
 import type { FacultIndex } from "./index-builder";
-import { facultRootDir } from "./paths";
+import { facultAiIndexPath, facultRootDir } from "./paths";
 
 type TrustMode = "trust" | "untrust";
 
@@ -27,8 +27,12 @@ function parseEntryName(raw: string): { kind: "skill" | "mcp"; name: string } {
   return { kind: "skill", name: raw };
 }
 
-async function loadIndex(rootDir: string): Promise<FacultIndex> {
-  const indexPath = join(rootDir, "index.json");
+async function loadIndex(homeDir: string): Promise<FacultIndex> {
+  const { path: indexPath } = await ensureAiIndexPath({
+    homeDir,
+    rootDir: facultRootDir(homeDir),
+    repair: true,
+  });
   const file = Bun.file(indexPath);
   if (!(await file.exists())) {
     throw new Error(`Index not found at ${indexPath}. Run "facult index".`);
@@ -37,8 +41,8 @@ async function loadIndex(rootDir: string): Promise<FacultIndex> {
   return JSON.parse(raw) as FacultIndex;
 }
 
-async function writeIndex(rootDir: string, index: FacultIndex) {
-  const indexPath = join(rootDir, "index.json");
+async function writeIndex(homeDir: string, index: FacultIndex) {
+  const indexPath = facultAiIndexPath(homeDir);
   await Bun.write(indexPath, `${JSON.stringify(index, null, 2)}\n`);
 }
 
@@ -68,20 +72,17 @@ export async function applyTrust({
   names,
   mode,
   homeDir,
-  rootDir,
 }: {
   names: string[];
   mode: TrustMode;
   homeDir?: string;
-  rootDir?: string;
 }) {
   if (!names.length) {
     throw new Error("At least one name is required.");
   }
   const home = homeDir ?? homedir();
-  const root = rootDir ?? facultRootDir(home);
 
-  const index = ensureIndexStructure(await loadIndex(root));
+  const index = ensureIndexStructure(await loadIndex(home));
   const now = new Date().toISOString();
 
   const missing: string[] = [];
@@ -109,7 +110,7 @@ export async function applyTrust({
   }
 
   index.updatedAt = new Date().toISOString();
-  await writeIndex(root, index);
+  await writeIndex(home, index);
 }
 
 function parseNamesFromArgv(argv: string[]): string[] {