facult 1.1.0 → 1.2.1

package/src/paths.ts

@@ -1,6 +1,6 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { parseJsonLenient } from "./util/json";
 
 export interface FacultConfig {
@@ -94,6 +94,7 @@ function looksLikeFacultRoot(root: string): boolean {
   // Heuristic: treat as a facult store if it contains something we'd create.
   return (
     dirExists(join(root, "rules")) ||
+    dirExists(join(root, "instructions")) ||
     dirExists(join(root, "agents")) ||
     dirExists(join(root, "skills")) ||
     dirExists(join(root, "mcp")) ||
@@ -135,12 +136,108 @@ export function facultStateDir(home: string = defaultHomeDir()): string {
   return join(home, ".facult");
 }
 
-export function facultAiStateDir(home: string = defaultHomeDir()): string {
-  return join(facultStateDir(home), "ai");
+export function projectRootFromAiRoot(
+  rootDir: string,
+  home: string = defaultHomeDir()
+): string | null {
+  const resolved = resolve(rootDir);
+  if (resolved === resolve(join(home, ".ai"))) {
+    return null;
+  }
+  if (resolved === resolve(legacyPreferredRoot(home))) {
+    return null;
+  }
+  return resolved.endsWith("/.ai") ? dirname(resolved) : null;
+}
+
+export function projectSlugFromAiRoot(
+  rootDir: string,
+  home: string = defaultHomeDir()
+): string | null {
+  const projectRoot = projectRootFromAiRoot(rootDir, home);
+  if (!projectRoot) {
+    return null;
+  }
+  const base = basename(projectRoot).trim().toLowerCase();
+  const slug = base.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "project";
+}
+
+export function facultGeneratedStateDir(args?: {
+  home?: string;
+  rootDir?: string;
+}): string {
+  const home = args?.home ?? defaultHomeDir();
+  const rootDir = args?.rootDir;
+  const projectRoot = rootDir ? projectRootFromAiRoot(rootDir, home) : null;
+  return projectRoot ? join(projectRoot, ".facult") : facultStateDir(home);
+}
+
+export function facultAiStateDir(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  return join(facultGeneratedStateDir({ home, rootDir }), "ai");
+}
+
+export function facultAiIndexPath(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  return join(facultAiStateDir(home, rootDir), "index.json");
+}
+
+export function facultAiGraphPath(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  return join(facultAiStateDir(home, rootDir), "graph.json");
+}
+
+export function facultAiRuntimeScopeDir(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  const slug = rootDir ? projectSlugFromAiRoot(rootDir, home) : null;
+  return slug
+    ? join(facultStateDir(home), "ai", "projects", slug)
+    : join(facultStateDir(home), "ai", "global");
+}
+
+export function facultAiJournalPath(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  return join(
+    facultAiRuntimeScopeDir(home, rootDir),
+    "journal",
+    "events.jsonl"
+  );
+}
+
+export function facultAiWritebackQueuePath(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  return join(
+    facultAiRuntimeScopeDir(home, rootDir),
+    "writeback",
+    "queue.jsonl"
+  );
 }
 
-export function facultAiIndexPath(home: string = defaultHomeDir()): string {
-  return join(facultAiStateDir(home), "index.json");
+export function facultAiProposalDir(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  return join(facultAiRuntimeScopeDir(home, rootDir), "evolution", "proposals");
+}
+
+export function facultAiDraftDir(
+  home: string = defaultHomeDir(),
+  rootDir?: string
+): string {
+  return join(facultAiRuntimeScopeDir(home, rootDir), "evolution", "drafts");
 }
 
 export function facultConfigPath(home: string = defaultHomeDir()): string {
@@ -268,3 +365,38 @@ export function facultRootDir(home: string = defaultHomeDir()): string {
   }
   return preferred;
 }
+
+export function findNearestProjectAiRoot(start: string): string | null {
+  let current = resolve(start);
+  while (true) {
+    const candidate = join(current, ".ai");
+    if (looksLikeFacultRoot(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+export function facultContextRootDir(args?: {
+  home?: string;
+  cwd?: string;
+}): string {
+  const home = args?.home ?? defaultHomeDir();
+  const envRoot = process.env.FACULT_ROOT_DIR?.trim();
+  if (envRoot) {
+    const resolved = resolvePath(envRoot, home);
+    return isSafePathString(resolved) ? resolved : join(home, ".ai");
+  }
+
+  const cwd = args?.cwd?.trim() || process.cwd();
+  const projectRoot = findNearestProjectAiRoot(cwd);
+  if (projectRoot) {
+    return projectRoot;
+  }
+
+  return facultRootDir(home);
+}

package/src/query.ts

@@ -1,13 +1,19 @@
 import { homedir } from "node:os";
 import { ensureAiIndexPath } from "./ai-state";
+import type { AssetScope, AssetSourceKind } from "./graph";
 import type {
   AgentEntry,
   FacultIndex,
+  InstructionEntry,
   McpEntry,
   SkillEntry,
   SnippetEntry,
 } from "./index-builder";
-import { facultAiIndexPath, facultRootDir } from "./paths";
+import {
+  facultAiIndexPath,
+  facultContextRootDir,
+  facultRootDir,
+} from "./paths";
 import { applyOrgTrustList } from "./trust-list";
 
 export interface QueryFilters {
@@ -23,6 +29,10 @@ export interface QueryFilters {
   tags?: string[];
   /** Full-text search query (case-insensitive). */
   text?: string;
+  /** Only include entries from a specific source layer. */
+  sourceKind?: AssetSourceKind;
+  /** Only include entries from a specific asset scope. */
+  scope?: AssetScope;
 }
 
 interface IndexEntry {
@@ -32,6 +42,18 @@ interface IndexEntry {
   enabledFor?: string[];
   trusted?: boolean;
   auditStatus?: string;
+  sourceKind?: AssetSourceKind;
+  scope?: AssetScope;
+}
+
+export interface CapabilityMatch {
+  kind: "skills" | "mcp" | "agents" | "snippets" | "instructions";
+  name: string;
+  path: string;
+  description?: string;
+  tags?: string[];
+  sourceKind?: string;
+  scope?: string;
 }
 
 const WHITESPACE_RE = /\s+/;
@@ -46,7 +68,7 @@ function matchesEnabledFor(entry: IndexEntry, tool?: string): boolean {
   }
   const enabledFor = entry.enabledFor;
   if (!Array.isArray(enabledFor)) {
-    return false;
+    return true;
   }
   const target = normalizeText(tool);
   return enabledFor.some((t) => normalizeText(t) === target);
@@ -99,16 +121,40 @@ function matchesText(entry: IndexEntry, text?: string): boolean {
   return terms.every((term) => haystack.includes(term.toLowerCase()));
 }
 
+function matchesSourceKind(
+  entry: IndexEntry,
+  sourceKind?: AssetSourceKind
+): boolean {
+  if (!sourceKind) {
+    return true;
+  }
+  return entry.sourceKind === sourceKind;
+}
+
+function matchesScope(entry: IndexEntry, scope?: AssetScope): boolean {
+  if (!scope) {
+    return true;
+  }
+  return entry.scope === scope;
+}
+
 /** Return the canonical facult root directory. */
 export function facultRootDirPath(home: string = homedir()): string {
   return facultRootDir(home);
 }
 
+export function facultContextRootDirPath(home: string = homedir()): string {
+  return facultContextRootDir({ home, cwd: process.cwd() });
+}
+
 /**
  * Return the path to the facult index.json file.
  */
 export function facultIndexPath(home: string = homedir()): string {
-  return facultAiIndexPath(home);
+  return facultAiIndexPath(
+    home,
+    facultContextRootDir({ home, cwd: process.cwd() })
+  );
 }
 
 /**
@@ -125,7 +171,9 @@ export async function loadIndex(opts?: {
   if (!resolvedHome) {
     throw new Error("HOME is not set.");
   }
-  const rootDir = opts?.rootDir ?? facultRootDir(resolvedHome);
+  const rootDir =
+    opts?.rootDir ??
+    facultContextRootDir({ home: resolvedHome, cwd: process.cwd() });
   const { path: indexPath } = await ensureAiIndexPath({
     homeDir: resolvedHome,
     rootDir,
@@ -180,6 +228,87 @@ export function filterSnippets(
   return filterEntries(entries, filters);
 }
 
+/**
+ * Filter instruction entries using query filters.
+ */
+export function filterInstructions(
+  entries: Record<string, InstructionEntry>,
+  filters?: QueryFilters
+): InstructionEntry[] {
+  return filterEntries(entries, filters);
+}
+
+export function findCapabilities(
+  index: FacultIndex,
+  filters: Pick<QueryFilters, "text" | "sourceKind" | "scope">
+): CapabilityMatch[] {
+  const results: CapabilityMatch[] = [];
+
+  for (const entry of filterSkills(index.skills, filters)) {
+    results.push({
+      kind: "skills",
+      name: entry.name,
+      path: entry.path,
+      description: entry.description,
+      tags: entry.tags,
+      sourceKind: entry.sourceKind,
+      scope: entry.scope,
+    });
+  }
+
+  for (const entry of filterMcp(index.mcp?.servers ?? {}, filters)) {
+    results.push({
+      kind: "mcp",
+      name: entry.name,
+      path: entry.path,
+      sourceKind: entry.sourceKind,
+      scope: entry.scope,
+    });
+  }
+
+  for (const entry of filterAgents(index.agents ?? {}, filters)) {
+    results.push({
+      kind: "agents",
+      name: entry.name,
+      path: entry.path,
+      description: entry.description,
+      sourceKind: entry.sourceKind,
+      scope: entry.scope,
+    });
+  }
+
+  for (const entry of filterSnippets(index.snippets ?? {}, filters)) {
+    results.push({
+      kind: "snippets",
+      name: entry.name,
+      path: entry.path,
+      description: entry.description,
+      tags: entry.tags,
+      sourceKind: entry.sourceKind,
+      scope: entry.scope,
+    });
+  }
+
+  for (const entry of filterInstructions(index.instructions ?? {}, filters)) {
+    results.push({
+      kind: "instructions",
+      name: entry.name,
+      path: entry.path,
+      description: entry.description,
+      tags: entry.tags,
+      sourceKind: entry.sourceKind,
+      scope: entry.scope,
+    });
+  }
+
+  return results.sort((a, b) => {
+    if (a.kind !== b.kind) {
+      return a.kind.localeCompare(b.kind);
+    }
+    return a.name.localeCompare(b.name);
+  });
+}
+
 function filterEntries<T extends IndexEntry>(
   entries: Record<string, T>,
   filters?: QueryFilters
@@ -189,6 +318,8 @@ function filterEntries<T extends IndexEntry>(
     .filter((entry) => matchesUntrusted(entry, filters?.untrusted))
     .filter((entry) => matchesFlagged(entry, filters?.flagged))
     .filter((entry) => matchesPending(entry, filters?.pending))
+    .filter((entry) => matchesSourceKind(entry, filters?.sourceKind))
+    .filter((entry) => matchesScope(entry, filters?.scope))
     .filter((entry) => matchesTags(entry, filters?.tags))
     .filter((entry) => matchesText(entry, filters?.text))
     .sort((a, b) => a.name.localeCompare(b.name));

package/src/remote.ts

@@ -1,6 +1,7 @@
-import { mkdir, readFile, rm } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { buildIndex } from "./index-builder";
 import { facultRootDir } from "./paths";
 import {
@@ -320,6 +321,100 @@ function renderTemplate(text: string, values: Record<string, string>): string {
   return out;
 }
 
+function builtinPackRoot(packName: string): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, "..", "assets", "packs", packName);
+}
+
+async function pathExists(pathValue: string): Promise<boolean> {
+  try {
+    await Bun.file(pathValue).stat();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listFilesRecursive(rootDir: string): Promise<string[]> {
+  const out: string[] = [];
+  const stack = [rootDir];
+  while (stack.length) {
+    const current = stack.pop();
+    if (!current) {
+      continue;
+    }
+    const entries = await readdir(current, { withFileTypes: true }).catch(
+      () => [] as import("node:fs").Dirent[]
+    );
+    for (const entry of entries) {
+      const fullPath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      } else if (entry.isFile()) {
+        out.push(fullPath);
+      }
+    }
+  }
+  return out.sort();
+}
+
+async function scaffoldBuiltinProjectAiPack(args: {
+  cwd?: string;
+  homeDir?: string;
+  dryRun?: boolean;
+  force?: boolean;
+}): Promise<InstallResult> {
+  const cwd = resolve(args.cwd ?? process.cwd());
+  const rootDir = join(cwd, ".ai");
+  const packRoot = builtinPackRoot("facult-operating-model");
+  const files = await listFilesRecursive(packRoot);
+  const changedPaths: string[] = [];
+
+  for (const sourcePath of files) {
+    const relPath = relative(packRoot, sourcePath);
+    if (!relPath || relPath.startsWith("..")) {
+      continue;
+    }
+    const targetPath = join(rootDir, relPath);
+    const exists = await pathExists(targetPath);
+    if (exists && !args.force) {
+      continue;
+    }
+    changedPaths.push(targetPath);
+    if (!args.dryRun) {
+      await mkdir(dirname(targetPath), { recursive: true });
+      await Bun.write(targetPath, await Bun.file(sourcePath).text());
+    }
+  }
+
+  const configPath = join(rootDir, "config.toml");
+  if (!(await pathExists(configPath)) || args.force) {
+    changedPaths.push(configPath);
+    if (!args.dryRun) {
+      await mkdir(dirname(configPath), { recursive: true });
+      await Bun.write(configPath, "version = 1\n");
+    }
+  }
+
+  if (!args.dryRun) {
+    await buildIndex({
+      homeDir: args.homeDir,
+      rootDir,
+      force: false,
+    });
+  }
+
+  return {
+    ref: `${BUILTIN_INDEX_NAME}:facult-operating-model`,
+    type: "skill",
+    installedAs: "project-ai",
+    path: rootDir,
+    sourceTrustLevel: "trusted",
+    dryRun: Boolean(args.dryRun),
+    changedPaths: uniqueSorted(changedPaths),
+  };
+}
+
 function compareVersions(a: string, b: string): number {
   const aTokens = (a.match(VERSION_TOKEN_RE) ?? []).map((t) => t.toLowerCase());
   const bTokens = (b.match(VERSION_TOKEN_RE) ?? []).map((t) => t.toLowerCase());
@@ -1589,6 +1684,7 @@ Usage:
   facult templates init snippet <marker> [--force] [--dry-run]
   facult templates init agents [--force] [--dry-run]
   facult templates init claude [--force] [--dry-run]
+  facult templates init project-ai [--force] [--dry-run]
 
 Notes:
   - Templates are powered by the builtin remote index (${BUILTIN_INDEX_NAME}).
@@ -1872,13 +1968,23 @@ export async function templatesCommand(
   }
   if (sub === "list") {
     const json = rest.includes("--json");
-    const rows = BUILTIN_MANIFEST.items.map((item) => ({
-      id: item.id,
-      type: item.type,
-      title: item.title ?? "",
-      description: item.description ?? "",
-      version: item.version ?? "",
-    }));
+    const rows = [
+      ...BUILTIN_MANIFEST.items.map((item) => ({
+        id: item.id,
+        type: item.type,
+        title: item.title ?? "",
+        description: item.description ?? "",
+        version: item.version ?? "",
+      })),
+      {
+        id: "project-ai",
+        type: "pack",
+        title: "Project AI Pack",
+        description:
+          "Seed a repo-local .ai with the built-in Facult operating-model pack.",
+        version: "1.0.0",
+      },
+    ];
     if (json) {
       console.log(JSON.stringify(rows, null, 2));
       return;
@@ -1897,7 +2003,7 @@ export async function templatesCommand(
   const [kind, ...args] = rest;
   if (!kind) {
     console.error(
-      "templates init requires a kind (skill|mcp|snippet|agents|claude)"
+      "templates init requires a kind (skill|mcp|snippet|agents|claude|project-ai)"
     );
     process.exitCode = 2;
     return;
@@ -1907,6 +2013,31 @@ export async function templatesCommand(
   const json = args.includes("--json");
   const positional = args.filter((a) => a && !a.startsWith("-"));
 
+  if (kind === "project-ai") {
+    try {
+      const result = await scaffoldBuiltinProjectAiPack({
+        cwd: ctx.cwd,
+        homeDir: ctx.homeDir,
+        dryRun,
+        force,
+      });
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      const action = dryRun ? "Would scaffold" : "Scaffolded";
+      console.log(`${action} ${kind} template as ${result.installedAs}`);
+      for (const path of result.changedPaths) {
+        console.log(`  - ${path}`);
+      }
+      return;
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   let ref = "";
   let as: string | undefined;
   if (kind === "skill") {

package/src/trust-list.ts

@@ -226,6 +226,7 @@ export async function applyOrgTrustList(
     },
     agents: index.agents ?? {},
     snippets: index.snippets ?? {},
+    instructions: index.instructions ?? {},
   };
 
   return next;

package/src/trust.ts

@@ -17,6 +17,7 @@ function ensureIndexStructure(index: FacultIndex): FacultIndex {
     mcp: index.mcp ?? { servers: {} },
     agents: index.agents ?? {},
     snippets: index.snippets ?? {},
+    instructions: index.instructions ?? {},
   };
 }