facult 1.0.1

package/src/audit/types.ts

@@ -0,0 +1,68 @@
+export type Severity = "low" | "medium" | "high" | "critical";
+
+export const SEVERITY_ORDER: Record<Severity, number> = {
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3,
+};
+
+export function parseSeverity(raw: string): Severity | null {
+  const v = raw.trim().toLowerCase();
+  if (v === "low" || v === "medium" || v === "high" || v === "critical") {
+    return v;
+  }
+  return null;
+}
+
+export function isAtLeastSeverity(sev: Severity, min?: Severity): boolean {
+  if (!min) {
+    return true;
+  }
+  return SEVERITY_ORDER[sev] >= SEVERITY_ORDER[min];
+}
+
+export interface AuditRule {
+  id: string;
+  severity: Severity;
+  pattern: string;
+  message: string;
+  target?: "skill" | "mcp" | "any";
+}
+
+export interface CompiledAuditRule extends AuditRule {
+  regex: RegExp;
+}
+
+export interface AuditFinding {
+  severity: Severity;
+  ruleId: string;
+  message: string;
+  location?: string;
+  evidence?: string;
+}
+
+export interface AuditItemResult {
+  item: string;
+  type: "skill" | "mcp" | "mcp-config" | "asset";
+  sourceId?: string;
+  path: string;
+  passed: boolean;
+  findings: AuditFinding[];
+  /** Optional extra context (mostly for agent-assisted audits). */
+  notes?: string;
+}
+
+export interface StaticAuditReport {
+  timestamp: string;
+  mode: "static";
+  minSeverity?: Severity;
+  rulesPath?: string | null;
+  results: AuditItemResult[];
+  summary: {
+    totalItems: number;
+    totalFindings: number;
+    bySeverity: Record<Severity, number>;
+    flaggedItems: number;
+  };
+}

package/src/audit/update-index.ts

@@ -0,0 +1,115 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { FacultIndex } from "../index-builder";
+import { facultRootDir } from "../paths";
+import type { AuditItemResult, Severity } from "./types";
+import { SEVERITY_ORDER } from "./types";
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function ensureIndexStructure(index: FacultIndex): FacultIndex {
+  return {
+    version: index.version ?? 1,
+    updatedAt: index.updatedAt ?? new Date().toISOString(),
+    skills: index.skills ?? {},
+    mcp: index.mcp ?? { servers: {} },
+    agents: index.agents ?? {},
+    snippets: index.snippets ?? {},
+  };
+}
+
+function computeAuditStatus(
+  findings: { severity: Severity; ruleId: string }[]
+): "pending" | "passed" | "flagged" {
+  if (findings.some((f) => f.ruleId === "agent-error")) {
+    return "pending";
+  }
+  const worst = findings.reduce(
+    (m, f) => Math.max(m, SEVERITY_ORDER[f.severity]),
+    -1
+  );
+  return worst >= SEVERITY_ORDER.high ? "flagged" : "passed";
+}
+
+async function loadIndex(rootDir: string): Promise<FacultIndex | null> {
+  const indexPath = join(rootDir, "index.json");
+  const file = Bun.file(indexPath);
+  if (!(await file.exists())) {
+    return null;
+  }
+  try {
+    return JSON.parse(await file.text()) as FacultIndex;
+  } catch {
+    return null;
+  }
+}
+
+async function writeIndex(rootDir: string, index: FacultIndex) {
+  const indexPath = join(rootDir, "index.json");
+  await Bun.write(indexPath, `${JSON.stringify(index, null, 2)}\n`);
+}
+
+export async function updateIndexFromAuditReport(opts: {
+  homeDir?: string;
+  timestamp: string;
+  results: AuditItemResult[];
+}): Promise<{ updated: boolean; reason?: string }> {
+  const home = opts.homeDir ?? homedir();
+  const rootDir = facultRootDir(home);
+
+  const loaded = await loadIndex(rootDir);
+  if (!loaded) {
+    return { updated: false, reason: "index-missing" };
+  }
+
+  const index = ensureIndexStructure(loaded);
+  let changed = false;
+
+  for (const r of opts.results) {
+    if (r.type !== "skill" && r.type !== "mcp") {
+      continue;
+    }
+    if (r.type === "skill") {
+      const entry = index.skills[r.item] as unknown;
+      if (!(entry && isPlainObject(entry))) {
+        continue;
+      }
+      if (typeof entry.path === "string" && entry.path !== r.path) {
+        // Only update the canonical instance tracked in the index.
+        continue;
+      }
+      const status = computeAuditStatus(
+        r.findings.map((f) => ({ severity: f.severity, ruleId: f.ruleId }))
+      );
+      entry.auditStatus = status;
+      entry.lastAuditAt = opts.timestamp;
+      changed = true;
+      continue;
+    }
+
+    // MCP
+    const entry = index.mcp?.servers?.[r.item] as unknown;
+    if (!(entry && isPlainObject(entry))) {
+      continue;
+    }
+    if (typeof entry.path === "string" && entry.path !== r.path) {
+      continue;
+    }
+    const status = computeAuditStatus(
+      r.findings.map((f) => ({ severity: f.severity, ruleId: f.ruleId }))
+    );
+    entry.auditStatus = status;
+    entry.lastAuditAt = opts.timestamp;
+    changed = true;
+  }
+
+  if (!changed) {
+    return { updated: false, reason: "no-matching-items" };
+  }
+
+  index.updatedAt = new Date().toISOString();
+  await writeIndex(rootDir, index);
+  return { updated: true };
+}

package/src/conflicts.ts

@@ -0,0 +1,135 @@
+import { spawnSync } from "node:child_process";
+import type { CanonicalMcpServer } from "./schema";
+
+const SHA_SPLIT_REGEX = /\s+/;
+
+export type AutoMode = "keep-newest" | "keep-current" | "keep-incoming";
+
+export type AutoDecision = "keep-current" | "keep-incoming" | "keep-both";
+
+export interface ConflictMeta {
+  modified: Date | null;
+}
+
+function normalizeLineEndings(input: string): string {
+  return input.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+function trimLineWhitespace(input: string): string {
+  return input
+    .split("\n")
+    .map((line) => line.replace(/\s+$/g, ""))
+    .join("\n");
+}
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortValue(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const obj = value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(obj).sort()) {
+    out[key] = sortValue(obj[key]);
+  }
+  return out;
+}
+
+/**
+ * Normalize text content for comparison.
+ *
+ * Trims surrounding whitespace, normalizes line endings to LF,
+ * and removes trailing whitespace on each line.
+ */
+export function normalizeText(input: string): string {
+  const normalized = normalizeLineEndings(input);
+  return trimLineWhitespace(normalized).trim();
+}
+
+/**
+ * Normalize JSON content for comparison.
+ *
+ * Parses JSON and stringifies with stable key ordering.
+ */
+export function normalizeJson(input: string): string {
+  const parsed = JSON.parse(input) as unknown;
+  const stable = sortValue(parsed);
+  return JSON.stringify(stable, null, 2).trim();
+}
+
+/**
+ * Compute a sha256 hash for normalized content.
+ */
+export function contentHash(input: string): string {
+  if (typeof Bun !== "undefined" && "CryptoHasher" in Bun) {
+    const hasher = new Bun.CryptoHasher("sha256");
+    hasher.update(input);
+    return hasher.digest("hex");
+  }
+
+  const res = spawnSync("shasum", ["-a", "256"], {
+    input,
+    encoding: "utf8",
+  });
+  if (res.status === 0 && res.stdout) {
+    return res.stdout.trim().split(SHA_SPLIT_REGEX)[0] ?? "";
+  }
+
+  throw new Error("Unable to compute content hash");
+}
+
+export function hashesMatch(
+  currentHash: string | null,
+  incomingHash: string | null
+): boolean {
+  return Boolean(currentHash && incomingHash && currentHash === incomingHash);
+}
+
+/**
+ * Normalize a canonical MCP server entry for hashing.
+ *
+ * Strips provenance metadata and normalizes JSON key ordering.
+ */
+export function normalizeMcpServer(entry: CanonicalMcpServer): string {
+  const { provenance: _provenance, ...rest } = entry;
+  return normalizeJson(JSON.stringify(rest, null, 2));
+}
+
+/**
+ * Compute a hash for a canonical MCP server entry.
+ */
+export function mcpServerHash(entry: CanonicalMcpServer): string {
+  return contentHash(normalizeMcpServer(entry));
+}
+
+/**
+ * Decide an automatic conflict resolution based on configured mode.
+ */
+export function decideAuto(
+  mode: AutoMode | undefined,
+  currentMeta: ConflictMeta,
+  incomingMeta: ConflictMeta
+): AutoDecision {
+  if (!mode) {
+    return "keep-both";
+  }
+  if (mode === "keep-current") {
+    return "keep-current";
+  }
+  if (mode === "keep-incoming") {
+    return "keep-incoming";
+  }
+
+  const currentTime = currentMeta.modified?.getTime() ?? null;
+  const incomingTime = incomingMeta.modified?.getTime() ?? null;
+
+  if (currentTime !== null && incomingTime !== null) {
+    return incomingTime > currentTime ? "keep-incoming" : "keep-current";
+  }
+  if (incomingTime !== null && currentTime === null) {
+    return "keep-incoming";
+  }
+  return "keep-current";
+}

package/src/consolidate-conflict-action.ts

@@ -0,0 +1,57 @@
+import {
+  type AutoDecision,
+  type AutoMode,
+  type ConflictMeta,
+  decideAuto,
+  hashesMatch,
+} from "./conflicts";
+
+export type ConflictDecision = AutoDecision | "skip";
+
+export interface PromptConflictResolutionArgs {
+  title: string;
+  currentLabel: string;
+  incomingLabel: string;
+  currentContent: string;
+  incomingContent: string;
+}
+
+export interface ResolveConflictActionArgs {
+  title: string;
+  currentLabel: string;
+  incomingLabel: string;
+  currentContent: string | null;
+  incomingContent: string | null;
+  currentHash: string | null;
+  incomingHash: string | null;
+  autoMode: AutoMode | undefined;
+  currentMeta: ConflictMeta;
+  incomingMeta: ConflictMeta;
+  promptConflictResolution: (
+    args: PromptConflictResolutionArgs
+  ) => Promise<ConflictDecision>;
+}
+
+export async function resolveConflictAction(
+  args: ResolveConflictActionArgs
+): Promise<ConflictDecision> {
+  if (!args.currentContent) {
+    return "keep-incoming";
+  }
+  if (!args.incomingContent) {
+    return "keep-current";
+  }
+  if (hashesMatch(args.currentHash, args.incomingHash)) {
+    return "keep-current";
+  }
+  if (args.autoMode) {
+    return decideAuto(args.autoMode, args.currentMeta, args.incomingMeta);
+  }
+  return await args.promptConflictResolution({
+    title: args.title,
+    currentLabel: args.currentLabel,
+    incomingLabel: args.incomingLabel,
+    currentContent: args.currentContent,
+    incomingContent: args.incomingContent,
+  });
+}