facult 1.0.3 → 1.2.0

package/src/agents.ts

@@ -0,0 +1,205 @@
+import { join } from "node:path";
+import { facultBuiltinPackRoot } from "./builtin";
+
+const AI_REF_RE = /(?<![\w@])@ai\/([^\s"'`<>]+)/g;
+const BUILTIN_REF_RE = /(?<![\w@])@builtin\/([^\s"'`<>]+)/g;
+const PROJECT_REF_RE = /(?<![\w@])@project\/([^\s"'`<>]+)/g;
+const INTERPOLATION_RE = /\$\{([^}]+)\}/g;
+const TRAILING_PUNCTUATION_RE = /[.,;:!?)}\]]+$/;
+const MAX_RENDER_PASSES = 10;
+
+export interface RenderCanonicalTextOptions {
+  homeDir?: string;
+  rootDir: string;
+  projectSlug?: string;
+  projectRoot?: string;
+  targetTool?: string;
+  targetPath?: string;
+  overrides?: Record<string, unknown>;
+}
+
+type RenderContext = Record<string, unknown>;
+
+function trimTrailingPunctuation(refPath: string): {
+  path: string;
+  suffix: string;
+} {
+  const match = TRAILING_PUNCTUATION_RE.exec(refPath);
+  if (!match) {
+    return { path: refPath, suffix: "" };
+  }
+
+  const suffix = match[0];
+  return {
+    path: refPath.slice(0, -suffix.length),
+    suffix,
+  };
+}
+
+export function renderAiRefs(input: string, canonicalRoot: string): string {
+  return input.replace(AI_REF_RE, (_match, refPath: string) => {
+    const { path, suffix } = trimTrailingPunctuation(refPath);
+    return `${join(canonicalRoot, path)}${suffix}`;
+  });
+}
+
+export function renderBuiltinRefs(input: string): string {
+  const builtinRoot = facultBuiltinPackRoot();
+  return input.replace(BUILTIN_REF_RE, (_match, refPath: string) => {
+    const { path, suffix } = trimTrailingPunctuation(refPath);
+    const relative = path.startsWith("facult-operating-model/")
+      ? path.slice("facult-operating-model/".length)
+      : path;
+    return `${join(builtinRoot, relative)}${suffix}`;
+  });
+}
+
+export function renderProjectRefs(input: string, projectRoot: string): string {
+  return input.replace(PROJECT_REF_RE, (_match, refPath: string) => {
+    const { path, suffix } = trimTrailingPunctuation(refPath);
+    return `${join(projectRoot, ".ai", path)}${suffix}`;
+  });
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function mergeContexts(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...base };
+
+  for (const [key, value] of Object.entries(override)) {
+    const current = merged[key];
+    if (isPlainObject(current) && isPlainObject(value)) {
+      merged[key] = mergeContexts(current, value);
+      continue;
+    }
+    merged[key] = value;
+  }
+
+  return merged;
+}
+
+async function readTomlFile(
+  pathValue: string
+): Promise<Record<string, unknown> | null> {
+  const file = Bun.file(pathValue);
+  if (!(await file.exists())) {
+    return null;
+  }
+
+  const text = await file.text();
+  const parsed = Bun.TOML.parse(text);
+  return isPlainObject(parsed) ? parsed : null;
+}
+
+function getContextValue(
+  context: Record<string, unknown>,
+  dottedPath: string
+): unknown {
+  const segments = dottedPath
+    .split(".")
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+  if (segments.length === 0) {
+    return undefined;
+  }
+
+  let current: unknown = context;
+  for (const segment of segments) {
+    if (!(isPlainObject(current) && segment in current)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+function interpolateString(
+  input: string,
+  context: Record<string, unknown>
+): string {
+  return input.replace(INTERPOLATION_RE, (match, keyPath: string) => {
+    const value = getContextValue(context, keyPath.trim());
+    return typeof value === "string" ? value : match;
+  });
+}
+
+export async function loadRenderContext(
+  options: RenderCanonicalTextOptions
+): Promise<RenderContext> {
+  const {
+    homeDir,
+    overrides,
+    projectRoot,
+    projectSlug,
+    rootDir,
+    targetPath,
+    targetTool,
+  } = options;
+  const contextBase: RenderContext = {
+    AI_ROOT: rootDir,
+    HOME: homeDir ?? "",
+    PROJECT_ROOT: projectRoot ?? "",
+    PROJECT_SLUG: projectSlug ?? "",
+    TARGET_PATH: targetPath ?? "",
+    TARGET_TOOL: targetTool ?? "",
+  };
+
+  let context = contextBase;
+  const layers = [
+    await readTomlFile(join(rootDir, "config.toml")),
+    await readTomlFile(join(rootDir, "config.local.toml")),
+    projectSlug
+      ? await readTomlFile(
+          join(rootDir, "projects", projectSlug, "config.toml")
+        )
+      : null,
+    projectSlug
+      ? await readTomlFile(
+          join(rootDir, "projects", projectSlug, "config.local.toml")
+        )
+      : null,
+    overrides && isPlainObject(overrides) ? overrides : null,
+  ];
+
+  for (const layer of layers) {
+    if (layer) {
+      context = mergeContexts(context, layer);
+    }
+  }
+
+  return context;
+}
+
+export async function renderCanonicalText(
+  input: string,
+  options: RenderCanonicalTextOptions
+): Promise<string> {
+  const context = await loadRenderContext(options);
+  let rendered = input;
+  const seen = new Set<string>();
+
+  for (let pass = 0; pass < MAX_RENDER_PASSES; pass += 1) {
+    if (seen.has(rendered)) {
+      break;
+    }
+    seen.add(rendered);
+
+    const interpolated = interpolateString(rendered, context);
+    const withAiRefs = renderAiRefs(interpolated, options.rootDir);
+    const withBuiltinRefs = renderBuiltinRefs(withAiRefs);
+    const withRefs = options.projectRoot
+      ? renderProjectRefs(withBuiltinRefs, options.projectRoot)
+      : withBuiltinRefs;
+    if (withRefs === rendered) {
+      return withRefs;
+    }
+    rendered = withRefs;
+  }
+
+  return rendered;
+}

package/src/ai-state.ts

@@ -0,0 +1,80 @@
+import { copyFile, mkdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { buildIndex } from "./index-builder";
+import { facultAiGraphPath, facultAiIndexPath } from "./paths";
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function legacyAiIndexPath(rootDir: string): string {
+  return join(rootDir, "index.json");
+}
+
+export async function ensureAiIndexPath(args: {
+  homeDir: string;
+  rootDir: string;
+  repair?: boolean;
+}): Promise<{
+  path: string;
+  repaired: boolean;
+  source: "generated" | "legacy" | "rebuilt" | "missing";
+}> {
+  const generatedPath = facultAiIndexPath(args.homeDir, args.rootDir);
+  if (await fileExists(generatedPath)) {
+    return { path: generatedPath, repaired: false, source: "generated" };
+  }
+
+  const legacyPath = legacyAiIndexPath(args.rootDir);
+  if (await fileExists(legacyPath)) {
+    if (args.repair !== false) {
+      await mkdir(dirname(generatedPath), { recursive: true });
+      await copyFile(legacyPath, generatedPath);
+    }
+    return {
+      path: generatedPath,
+      repaired: args.repair !== false,
+      source: "legacy",
+    };
+  }
+
+  if (args.repair !== false) {
+    const { outputPath } = await buildIndex({
+      rootDir: args.rootDir,
+      homeDir: args.homeDir,
+      force: false,
+    });
+    return { path: outputPath, repaired: true, source: "rebuilt" };
+  }
+
+  return { path: generatedPath, repaired: false, source: "missing" };
+}
+
+export async function ensureAiGraphPath(args: {
+  homeDir: string;
+  rootDir: string;
+  repair?: boolean;
+}): Promise<{
+  path: string;
+  rebuilt: boolean;
+}> {
+  const generatedPath = facultAiGraphPath(args.homeDir, args.rootDir);
+  if (await fileExists(generatedPath)) {
+    return { path: generatedPath, rebuilt: false };
+  }
+
+  if (args.repair !== false) {
+    const { graphPath } = await buildIndex({
+      rootDir: args.rootDir,
+      homeDir: args.homeDir,
+      force: false,
+    });
+    return { path: graphPath, rebuilt: true };
+  }
+
+  return { path: generatedPath, rebuilt: false };
+}