facult 1.0.1

package/src/source-trust.ts

@@ -0,0 +1,203 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { facultStateDir } from "./paths";
+import { parseJsonLenient } from "./util/json";
+
+export type SourceTrustLevel = "trusted" | "review" | "blocked";
+
+export interface SourceTrustPolicy {
+  level: SourceTrustLevel;
+  note?: string;
+  updatedAt: string;
+  updatedBy: "user";
+}
+
+export interface SourceTrustState {
+  version: 1;
+  updatedAt: string;
+  sources: Record<string, SourceTrustPolicy>;
+}
+
+const SOURCE_TRUST_VERSION = 1;
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function sourceTrustPath(home: string): string {
+  return join(facultStateDir(home), "trust", "sources.json");
+}
+
+function normalizeSourceName(name: string): string {
+  return name.trim();
+}
+
+function parseTrustLevel(raw: unknown): SourceTrustLevel | null {
+  if (raw !== "trusted" && raw !== "review" && raw !== "blocked") {
+    return null;
+  }
+  return raw;
+}
+
+function parsePolicy(raw: unknown): SourceTrustPolicy | null {
+  if (!isPlainObject(raw)) {
+    return null;
+  }
+  const level = parseTrustLevel(raw.level);
+  if (!level) {
+    return null;
+  }
+  const updatedAt = typeof raw.updatedAt === "string" ? raw.updatedAt : "";
+  if (!updatedAt) {
+    return null;
+  }
+  const updatedBy = raw.updatedBy === "user" ? "user" : "user";
+  const note = typeof raw.note === "string" ? raw.note.trim() : undefined;
+  return {
+    level,
+    note: note || undefined,
+    updatedAt,
+    updatedBy,
+  };
+}
+
+export function defaultSourceTrustLevel(args: {
+  sourceName: string;
+}): SourceTrustLevel {
+  // Builtin templates are local/offline and safe as a trusted base.
+  if (args.sourceName === "facult") {
+    return "trusted";
+  }
+  // External and custom sources default to review.
+  return "review";
+}
+
+export function sourceTrustLevelFor(args: {
+  sourceName: string;
+  state: SourceTrustState;
+}): {
+  level: SourceTrustLevel;
+  explicit: boolean;
+  policy?: SourceTrustPolicy;
+} {
+  const name = normalizeSourceName(args.sourceName);
+  const policy = args.state.sources[name];
+  if (policy) {
+    return {
+      level: policy.level,
+      explicit: true,
+      policy,
+    };
+  }
+  return {
+    level: defaultSourceTrustLevel({ sourceName: name }),
+    explicit: false,
+  };
+}
+
+export async function loadSourceTrustState(opts?: {
+  homeDir?: string;
+}): Promise<SourceTrustState> {
+  const home = opts?.homeDir ?? homedir();
+  const path = sourceTrustPath(home);
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = parseJsonLenient(raw);
+    if (!isPlainObject(parsed)) {
+      throw new Error("invalid");
+    }
+
+    const version =
+      typeof parsed.version === "number" && Number.isFinite(parsed.version)
+        ? Math.floor(parsed.version)
+        : SOURCE_TRUST_VERSION;
+    const updatedAt =
+      typeof parsed.updatedAt === "string"
+        ? parsed.updatedAt
+        : new Date(0).toISOString();
+    const sourcesRaw = isPlainObject(parsed.sources)
+      ? (parsed.sources as Record<string, unknown>)
+      : {};
+
+    const sources: Record<string, SourceTrustPolicy> = {};
+    for (const [name, value] of Object.entries(sourcesRaw)) {
+      const normalized = normalizeSourceName(name);
+      if (!normalized) {
+        continue;
+      }
+      const policy = parsePolicy(value);
+      if (!policy) {
+        continue;
+      }
+      sources[normalized] = policy;
+    }
+
+    return {
+      version: version === 1 ? 1 : SOURCE_TRUST_VERSION,
+      updatedAt,
+      sources,
+    };
+  } catch {
+    return {
+      version: SOURCE_TRUST_VERSION,
+      updatedAt: new Date(0).toISOString(),
+      sources: {},
+    };
+  }
+}
+
+export async function saveSourceTrustState(args: {
+  state: SourceTrustState;
+  homeDir?: string;
+}): Promise<void> {
+  const home = args.homeDir ?? homedir();
+  const path = sourceTrustPath(home);
+  await mkdir(join(facultStateDir(home), "trust"), { recursive: true });
+  await Bun.write(path, `${JSON.stringify(args.state, null, 2)}\n`);
+}
+
+export async function setSourceTrustPolicy(args: {
+  sourceName: string;
+  level: SourceTrustLevel;
+  note?: string;
+  homeDir?: string;
+  now?: () => Date;
+}): Promise<SourceTrustState> {
+  const home = args.homeDir ?? homedir();
+  const now = args.now ? args.now() : new Date();
+  const state = await loadSourceTrustState({ homeDir: home });
+  const sourceName = normalizeSourceName(args.sourceName);
+  if (!sourceName) {
+    throw new Error("Source name cannot be empty.");
+  }
+
+  state.sources[sourceName] = {
+    level: args.level,
+    note: args.note?.trim() || undefined,
+    updatedAt: now.toISOString(),
+    updatedBy: "user",
+  };
+  state.updatedAt = now.toISOString();
+  await saveSourceTrustState({ state, homeDir: home });
+  return state;
+}
+
+export async function clearSourceTrustPolicy(args: {
+  sourceName: string;
+  homeDir?: string;
+  now?: () => Date;
+}): Promise<SourceTrustState> {
+  const home = args.homeDir ?? homedir();
+  const now = args.now ? args.now() : new Date();
+  const state = await loadSourceTrustState({ homeDir: home });
+  const sourceName = normalizeSourceName(args.sourceName);
+  if (!sourceName) {
+    throw new Error("Source name cannot be empty.");
+  }
+
+  delete state.sources[sourceName];
+  state.updatedAt = now.toISOString();
+  await saveSourceTrustState({ state, homeDir: home });
+  return state;
+}

package/src/trust-list.ts

@@ -0,0 +1,232 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { FacultIndex, McpEntry, SkillEntry } from "./index-builder";
+import { facultStateDir } from "./paths";
+import { parseJsonLenient } from "./util/json";
+
+const SHA256_HEX_RE = /^[a-f0-9]{64}$/;
+
+export interface OrgTrustList {
+  version: number;
+  issuer?: string;
+  generatedAt?: string;
+  skills: Set<string>;
+  mcpServers: Set<string>;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortValue(item));
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(value).sort()) {
+    out[key] = sortValue(value[key]);
+  }
+  return out;
+}
+
+function stableStringify(value: unknown): string {
+  return JSON.stringify(sortValue(value));
+}
+
+function sha256Hex(text: string): string {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+function normalizeNameList(raw: unknown): string[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return Array.from(
+    new Set(
+      raw
+        .filter((v): v is string => typeof v === "string")
+        .map((v) => v.trim())
+        .filter(Boolean)
+    )
+  ).sort();
+}
+
+function normalizeChecksum(raw: unknown): string | null {
+  if (typeof raw !== "string") {
+    return null;
+  }
+  const trimmed = raw.trim().toLowerCase();
+  if (!trimmed) {
+    return null;
+  }
+  const value = trimmed.startsWith("sha256:")
+    ? trimmed.slice("sha256:".length)
+    : trimmed;
+  if (!SHA256_HEX_RE.test(value)) {
+    return null;
+  }
+  return value;
+}
+
+function buildCanonicalPayload(args: {
+  version: number;
+  issuer?: string;
+  generatedAt?: string;
+  skills: string[];
+  mcpServers: string[];
+}): Record<string, unknown> {
+  const payload: Record<string, unknown> = {
+    version: args.version,
+    skills: args.skills,
+    mcp: args.mcpServers,
+  };
+  if (args.issuer) {
+    payload.issuer = args.issuer;
+  }
+  if (args.generatedAt) {
+    payload.generatedAt = args.generatedAt;
+  }
+  return payload;
+}
+
+function extractTrustLists(obj: Record<string, unknown>): {
+  skills: string[];
+  mcpServers: string[];
+} {
+  const topLevelSkills = normalizeNameList(obj.skills);
+  const topLevelMcp = normalizeNameList(obj.mcp);
+
+  const trust = isPlainObject(obj.trust)
+    ? (obj.trust as Record<string, unknown>)
+    : null;
+  const nestedSkills = normalizeNameList(trust?.skills);
+  const nestedMcp = normalizeNameList(trust?.mcp);
+
+  return {
+    skills: topLevelSkills.length ? topLevelSkills : nestedSkills,
+    mcpServers: topLevelMcp.length ? topLevelMcp : nestedMcp,
+  };
+}
+
+function localTrustIsExplicit(entry: { trusted?: boolean }): boolean {
+  return typeof entry.trusted === "boolean";
+}
+
+function applyTrustOverlay<T extends SkillEntry | McpEntry>(args: {
+  entries: Record<string, T>;
+  trustedNames: Set<string>;
+  trustedBy: string;
+  trustedAt?: string;
+}): Record<string, T> {
+  const next: Record<string, T> = { ...args.entries };
+  for (const name of args.trustedNames) {
+    const current = next[name];
+    if (!current || localTrustIsExplicit(current)) {
+      continue;
+    }
+    const withTrust = {
+      ...current,
+      trusted: true,
+      trustedBy: args.trustedBy,
+      trustedAt: current.trustedAt ?? args.trustedAt,
+    } as T;
+    next[name] = withTrust;
+  }
+  return next;
+}
+
+export async function loadOrgTrustList(opts?: {
+  homeDir?: string;
+}): Promise<OrgTrustList | null> {
+  const home = opts?.homeDir ?? homedir();
+  const trustPath = join(facultStateDir(home), "trust", "org-list.json");
+  const file = Bun.file(trustPath);
+  if (!(await file.exists())) {
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseJsonLenient(await file.text());
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(parsed)) {
+    return null;
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  const version =
+    typeof obj.version === "number" && Number.isFinite(obj.version)
+      ? Math.floor(obj.version)
+      : 1;
+  const issuer = typeof obj.issuer === "string" ? obj.issuer.trim() : "";
+  const generatedAt =
+    typeof obj.generatedAt === "string" ? obj.generatedAt : undefined;
+  const { skills, mcpServers } = extractTrustLists(obj);
+
+  const expectedChecksum = normalizeChecksum(obj.checksum);
+  if (!expectedChecksum) {
+    return null;
+  }
+
+  const payload = buildCanonicalPayload({
+    version,
+    issuer: issuer || undefined,
+    generatedAt,
+    skills,
+    mcpServers,
+  });
+  const actualChecksum = sha256Hex(stableStringify(payload));
+  if (actualChecksum !== expectedChecksum) {
+    return null;
+  }
+
+  return {
+    version,
+    issuer: issuer || undefined,
+    generatedAt,
+    skills: new Set(skills),
+    mcpServers: new Set(mcpServers),
+  };
+}
+
+export async function applyOrgTrustList(
+  index: FacultIndex,
+  opts?: {
+    homeDir?: string;
+  }
+): Promise<FacultIndex> {
+  const orgList = await loadOrgTrustList(opts);
+  if (!orgList) {
+    return index;
+  }
+
+  const trustedBy = orgList.issuer ? `org:${orgList.issuer}` : "org";
+  const next: FacultIndex = {
+    version: index.version,
+    updatedAt: index.updatedAt,
+    skills: applyTrustOverlay({
+      entries: index.skills,
+      trustedNames: orgList.skills,
+      trustedBy,
+      trustedAt: orgList.generatedAt,
+    }),
+    mcp: {
+      servers: applyTrustOverlay({
+        entries: index.mcp?.servers ?? {},
+        trustedNames: orgList.mcpServers,
+        trustedBy,
+        trustedAt: orgList.generatedAt,
+      }),
+    },
+    agents: index.agents ?? {},
+    snippets: index.snippets ?? {},
+  };
+
+  return next;
+}

package/src/trust.ts

@@ -0,0 +1,170 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { FacultIndex } from "./index-builder";
+import { facultRootDir } from "./paths";
+
+type TrustMode = "trust" | "untrust";
+
+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 parseEntryName(raw: string): { kind: "skill" | "mcp"; name: string } {
+  if (raw.startsWith("mcp:")) {
+    return { kind: "mcp", name: raw.slice("mcp:".length) };
+  }
+  return { kind: "skill", name: raw };
+}
+
+async function loadIndex(rootDir: string): Promise<FacultIndex> {
+  const indexPath = join(rootDir, "index.json");
+  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();
+  return JSON.parse(raw) as FacultIndex;
+}
+
+async function writeIndex(rootDir: string, index: FacultIndex) {
+  const indexPath = join(rootDir, "index.json");
+  await Bun.write(indexPath, `${JSON.stringify(index, null, 2)}\n`);
+}
+
+function setTrustFields(
+  entry: Record<string, unknown>,
+  mode: TrustMode,
+  nowIso: string
+) {
+  if (mode === "trust") {
+    entry.trusted = true;
+    entry.trustedAt = nowIso;
+    entry.trustedBy = "user";
+  } else {
+    entry.trusted = false;
+    entry.trustedAt = undefined;
+    entry.trustedBy = undefined;
+  }
+
+  // Ensure auditStatus exists for downstream filtering.
+  const rawStatus = entry.auditStatus;
+  if (typeof rawStatus !== "string" || rawStatus.trim() === "") {
+    entry.auditStatus = "pending";
+  }
+}
+
+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 now = new Date().toISOString();
+
+  const missing: string[] = [];
+  for (const raw of names) {
+    const { kind, name } = parseEntryName(raw);
+    if (kind === "skill") {
+      const entry = index.skills[name] as unknown;
+      if (!(entry && isPlainObject(entry))) {
+        missing.push(raw);
+        continue;
+      }
+      setTrustFields(entry, mode, now);
+    } else {
+      const entry = index.mcp?.servers?.[name] as unknown;
+      if (!(entry && isPlainObject(entry))) {
+        missing.push(raw);
+        continue;
+      }
+      setTrustFields(entry, mode, now);
+    }
+  }
+
+  if (missing.length) {
+    throw new Error(`Entries not found: ${missing.join(", ")}`);
+  }
+
+  index.updatedAt = new Date().toISOString();
+  await writeIndex(root, index);
+}
+
+function parseNamesFromArgv(argv: string[]): string[] {
+  const names: string[] = [];
+  for (const arg of argv) {
+    if (!arg) {
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    names.push(arg);
+  }
+  return names;
+}
+
+export async function trustCommand(argv: string[]) {
+  if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+    console.log(`facult trust — mark skills or MCP servers as trusted (annotation only)
+
+Usage:
+  facult trust <name> [moreNames...]
+  facult trust mcp:<name> [moreNames...]
+`);
+    return;
+  }
+  try {
+    const names = parseNamesFromArgv(argv);
+    await applyTrust({ names, mode: "trust" });
+    console.log(`Marked as trusted: ${names.join(", ")}`);
+    console.log(
+      'Note: Trust is an annotation. Run "facult audit" for security review.'
+    );
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+}
+
+export async function untrustCommand(argv: string[]) {
+  if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+    console.log(`facult untrust — remove trusted annotation
+
+Usage:
+  facult untrust <name> [moreNames...]
+  facult untrust mcp:<name> [moreNames...]
+`);
+    return;
+  }
+  try {
+    const names = parseNamesFromArgv(argv);
+    await applyTrust({ names, mode: "untrust" });
+    console.log(`Marked as untrusted: ${names.join(", ")}`);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+}

package/src/tui.ts

@@ -0,0 +1,118 @@
+import {
+  BoxRenderable,
+  createCliRenderer,
+  type KeyEvent,
+  type SelectOption,
+  SelectRenderable,
+  TextRenderable,
+} from "@opentui/core";
+import type { ScanResult } from "./scan";
+import { computeSkillOccurrences } from "./util/skills";
+
+export async function runSkillsTui(res: ScanResult): Promise<void> {
+  const renderer = await createCliRenderer({
+    // Keep default exit-on-ctrl+c behavior.
+    exitOnCtrlC: true,
+  });
+
+  renderer.setBackgroundColor("#001122");
+
+  const width = renderer.width;
+  const height = renderer.height;
+
+  const container = new BoxRenderable(renderer, {
+    id: "container",
+    position: "absolute",
+    left: 0,
+    top: 0,
+    width,
+    height,
+    borderStyle: "double",
+    borderColor: "#4CC9F0",
+    title: "facult scan — skills",
+    titleAlignment: "center",
+    backgroundColor: "#001122",
+  });
+
+  const hint = new TextRenderable(renderer, {
+    id: "hint",
+    position: "absolute",
+    left: 2,
+    top: 1,
+    width: Math.max(10, width - 4),
+    height: 1,
+    fg: "#E0FBFC",
+    content:
+      "↑/↓ or j/k to scroll • Enter to copy name • d = duplicates-only • a = all • q / Esc to quit",
+  });
+
+  const occurrencesAll = computeSkillOccurrences(res);
+
+  function toOptions(occ: typeof occurrencesAll): SelectOption[] {
+    return occ.map((o) => ({
+      name: `${o.count > 1 ? "[dup] " : ""}${o.name}  (${o.count})`,
+      description: o.locations.join(" · "),
+      value: o.name,
+    }));
+  }
+
+  const options: SelectOption[] = toOptions(occurrencesAll);
+
+  const select = new SelectRenderable(renderer, {
+    id: "skills",
+    position: "absolute",
+    left: 1,
+    top: 3,
+    width: Math.max(10, width - 2),
+    height: Math.max(5, height - 4),
+    options,
+    showDescription: true,
+    showScrollIndicator: true,
+    wrapSelection: true,
+  });
+
+  // Focus so it receives key input.
+  select.focus();
+
+  // Key handling: quit + enter to copy.
+  renderer.keyInput.on("keypress", async (key: KeyEvent) => {
+    if (key.name === "escape" || key.name === "q") {
+      renderer.destroy();
+      return;
+    }
+
+    if (key.name === "d") {
+      const next = occurrencesAll.filter((o) => o.count > 1);
+      select.options = toOptions(next);
+      return;
+    }
+
+    if (key.name === "a") {
+      select.options = toOptions(occurrencesAll);
+      return;
+    }
+
+    if (key.name === "return" || key.name === "enter") {
+      const opt = select.getSelectedOption();
+      const value = typeof opt?.value === "string" ? opt.value : "";
+      if (value) {
+        // Best-effort clipboard support (macOS pbcopy).
+        try {
+          await Bun.$`printf %s ${value} | pbcopy`.quiet();
+        } catch {
+          // ignore
+        }
+      }
+    }
+  });
+
+  renderer.root.add(container);
+  renderer.root.add(hint);
+  renderer.root.add(select);
+
+  // Keep it live for smoother scrolling.
+  renderer.start();
+
+  // Wait until renderer destroys (q/esc/ctrl+c).
+  await renderer.idle();
+}