facult 1.0.1

package/src/remote-source-policy.ts

@@ -0,0 +1,237 @@
+import { homedir } from "node:os";
+import {
+  clearSourceTrustPolicy,
+  defaultSourceTrustLevel,
+  loadSourceTrustState,
+  type SourceTrustLevel,
+  type SourceTrustState,
+  setSourceTrustPolicy,
+  sourceTrustLevelFor,
+} from "./source-trust";
+
+const SOURCE_POLICY_ACTIONS = new Set(["trust", "review", "block", "clear"]);
+
+export interface SourceIndexRef {
+  name: string;
+  url: string;
+}
+
+export interface SourcePolicyCommandContext {
+  homeDir?: string;
+  cwd?: string;
+  now?: () => Date;
+}
+
+export interface SourcePolicyRow {
+  source: string;
+  level: SourceTrustLevel;
+  explicit: boolean;
+  defaultLevel: SourceTrustLevel;
+  note?: string;
+  updatedAt?: string;
+  url?: string;
+}
+
+function parseLongFlag(argv: string[], flag: string): string | null {
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg) {
+      continue;
+    }
+    if (arg === flag) {
+      return argv[i + 1] ?? null;
+    }
+    if (arg.startsWith(`${flag}=`)) {
+      return arg.slice(flag.length + 1);
+    }
+  }
+  return null;
+}
+
+function printSourcesHelp(args: { builtinIndexName: string }) {
+  console.log(`facult sources — manage source trust policy for remote indices
+
+Usage:
+  facult sources list [--json]
+  facult sources trust <source> [--note <text>]
+  facult sources review <source> [--note <text>]
+  facult sources block <source> [--note <text>]
+  facult sources clear <source>
+
+Notes:
+  - Default policy is "${args.builtinIndexName}=trusted", all other sources=review.
+  - Blocked sources are always denied for install/update.
+  - Review sources are allowed unless --strict-source-trust is enabled.
+`);
+}
+
+export function evaluateSourceTrust(args: {
+  sourceName: string;
+  trustState: SourceTrustState;
+}): {
+  level: SourceTrustLevel;
+  explicit: boolean;
+  note?: string;
+  updatedAt?: string;
+} {
+  const trust = sourceTrustLevelFor({
+    sourceName: args.sourceName,
+    state: args.trustState,
+  });
+  return {
+    level: trust.level,
+    explicit: trust.explicit,
+    note: trust.policy?.note,
+    updatedAt: trust.policy?.updatedAt,
+  };
+}
+
+export function assertSourceAllowed(args: {
+  sourceName: string;
+  trustState: SourceTrustState;
+  strictSourceTrust: boolean;
+}): SourceTrustLevel {
+  const trust = evaluateSourceTrust(args);
+  if (trust.level === "blocked") {
+    throw new Error(
+      `Source "${args.sourceName}" is blocked by policy. Use "facult sources clear ${args.sourceName}" to remove the block.`
+    );
+  }
+  if (args.strictSourceTrust && trust.level === "review") {
+    throw new Error(
+      `Source "${args.sourceName}" requires review (strict mode). Use "facult sources trust ${args.sourceName}" after review.`
+    );
+  }
+  return trust.level;
+}
+
+export async function sourcesCommand(args: {
+  argv: string[];
+  ctx?: SourcePolicyCommandContext;
+  readIndexSources: (home: string, cwd: string) => Promise<SourceIndexRef[]>;
+  builtinIndexName: string;
+}) {
+  const [sub = "list", ...rest] = args.argv;
+  if (
+    sub === "--help" ||
+    sub === "-h" ||
+    sub === "help" ||
+    (sub !== "list" && !SOURCE_POLICY_ACTIONS.has(sub))
+  ) {
+    printSourcesHelp({ builtinIndexName: args.builtinIndexName });
+    return;
+  }
+
+  const home = args.ctx?.homeDir ?? homedir();
+  const cwd = args.ctx?.cwd ?? process.cwd();
+  const json = rest.includes("--json");
+
+  if (sub === "list") {
+    try {
+      const [sources, trustState] = await Promise.all([
+        args.readIndexSources(home, cwd),
+        loadSourceTrustState({ homeDir: home }),
+      ]);
+
+      const urlsByName = new Map<string, string>();
+      for (const source of sources) {
+        urlsByName.set(source.name, source.url);
+      }
+
+      const names = new Set<string>([
+        ...sources.map((source) => source.name),
+        ...Object.keys(trustState.sources),
+      ]);
+      const rows: SourcePolicyRow[] = Array.from(names)
+        .sort((a, b) => a.localeCompare(b))
+        .map((name) => {
+          const assessed = evaluateSourceTrust({
+            sourceName: name,
+            trustState,
+          });
+          return {
+            source: name,
+            level: assessed.level,
+            explicit: assessed.explicit,
+            defaultLevel: defaultSourceTrustLevel({ sourceName: name }),
+            note: assessed.note,
+            updatedAt: assessed.updatedAt,
+            url: urlsByName.get(name),
+          };
+        });
+
+      if (json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+      }
+
+      if (!rows.length) {
+        console.log("(no sources)");
+        return;
+      }
+      for (const row of rows) {
+        const origin = row.explicit ? "explicit" : "default";
+        const url = row.url ?? "-";
+        const note = row.note ? `\t${row.note}` : "";
+        console.log(`${row.source}\t${row.level}\t${origin}\t${url}${note}`);
+      }
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const positional: string[] = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "--note") {
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--note=") || arg.startsWith("-")) {
+      continue;
+    }
+    positional.push(arg);
+  }
+  const sourceName = positional[0];
+  if (!sourceName) {
+    console.error(`${sub} requires a source name`);
+    process.exitCode = 1;
+    return;
+  }
+  const note = parseLongFlag(rest, "--note") ?? undefined;
+
+  try {
+    if (sub === "clear") {
+      await clearSourceTrustPolicy({
+        sourceName,
+        homeDir: home,
+        now: args.ctx?.now,
+      });
+      console.log(`Cleared source trust policy: ${sourceName}`);
+      return;
+    }
+
+    const level =
+      sub === "trust"
+        ? ("trusted" as const)
+        : sub === "review"
+          ? ("review" as const)
+          : ("blocked" as const);
+    await setSourceTrustPolicy({
+      sourceName,
+      level,
+      note,
+      homeDir: home,
+      now: args.ctx?.now,
+    });
+    console.log(`Set source policy: ${sourceName} -> ${level}`);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+}

package/src/remote-sources.ts

@@ -0,0 +1,162 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { facultStateDir } from "./paths";
+import {
+  type ManifestSignature,
+  type ManifestSignatureKey,
+  parseManifestIntegrity,
+  parseManifestSignature,
+  parseManifestSignatureKeys,
+} from "./remote-manifest-integrity";
+import {
+  BUILTIN_INDEX_NAME,
+  BUILTIN_INDEX_URL,
+  type IndexSource,
+  KNOWN_PROVIDER_SOURCES,
+} from "./remote-types";
+import { parseJsonLenient } from "./util/json";
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await Bun.file(path).stat();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseEntrySignature(
+  entry: Record<string, unknown>
+): ManifestSignature | undefined {
+  if (isPlainObject(entry.signature) || typeof entry.signature === "string") {
+    return parseManifestSignature(entry.signature);
+  }
+  const synthetic = {
+    algorithm: entry.signatureAlgorithm,
+    value: entry.sig ?? entry.signature,
+    keyId: entry.keyId ?? entry.signatureKeyId ?? entry.kid,
+    publicKey: entry.publicKey,
+    publicKeyPath: entry.publicKeyPath ?? entry.keyPath,
+  };
+  return parseManifestSignature(synthetic);
+}
+
+function mergeSignatureKeys(
+  globalKeys: ManifestSignatureKey[],
+  sourceKeys: ManifestSignatureKey[]
+): ManifestSignatureKey[] {
+  const merged = new Map<string, ManifestSignatureKey>();
+  for (const key of globalKeys) {
+    merged.set(key.id, key);
+  }
+  for (const key of sourceKeys) {
+    merged.set(key.id, key);
+  }
+  return Array.from(merged.values()).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export async function readIndexSources(
+  home: string,
+  cwd: string
+): Promise<IndexSource[]> {
+  const out: IndexSource[] = [
+    { name: BUILTIN_INDEX_NAME, url: BUILTIN_INDEX_URL, kind: "builtin" },
+  ];
+  const configPath = resolve(facultStateDir(home), "indices.json");
+  if (!(await fileExists(configPath))) {
+    return out;
+  }
+
+  try {
+    const parsed = parseJsonLenient(await readFile(configPath, "utf8"));
+    if (!isPlainObject(parsed)) {
+      return out;
+    }
+    const obj = parsed as Record<string, unknown>;
+    const globalKeys = parseManifestSignatureKeys(
+      obj.signatureKeys ?? obj.trustedKeys ?? obj.keys
+    );
+    const candidateLists: unknown[] = [obj.indices, obj.sources];
+    for (const list of candidateLists) {
+      if (!Array.isArray(list)) {
+        continue;
+      }
+      for (const entry of list) {
+        if (!isPlainObject(entry)) {
+          continue;
+        }
+        const name = typeof entry.name === "string" ? entry.name.trim() : "";
+        if (!name) {
+          continue;
+        }
+        const provider =
+          typeof entry.provider === "string" ? entry.provider.trim() : "";
+        const providerDefault = provider
+          ? KNOWN_PROVIDER_SOURCES[provider]
+          : undefined;
+        const rawUrl = typeof entry.url === "string" ? entry.url.trim() : "";
+        const integrity = parseManifestIntegrity(
+          entry.integrity ?? entry.checksum
+        );
+        const signature = parseEntrySignature(entry);
+        const sourceKeys = parseManifestSignatureKeys(
+          entry.signatureKeys ?? entry.trustedKeys ?? entry.keys
+        );
+        const signatureKeys = mergeSignatureKeys(globalKeys, sourceKeys);
+
+        if (providerDefault) {
+          out.push({
+            name,
+            kind: providerDefault.kind,
+            url: rawUrl || providerDefault.url,
+            integrity,
+            signature,
+            signatureKeys: signatureKeys.length ? signatureKeys : undefined,
+          });
+          continue;
+        }
+
+        if (!rawUrl) {
+          continue;
+        }
+        const resolvedUrl =
+          rawUrl.startsWith("http://") ||
+          rawUrl.startsWith("https://") ||
+          rawUrl.startsWith("file://") ||
+          isAbsolute(rawUrl)
+            ? rawUrl
+            : resolve(cwd, rawUrl);
+        out.push({
+          name,
+          url: resolvedUrl,
+          kind: "manifest",
+          integrity,
+          signature,
+          signatureKeys: signatureKeys.length ? signatureKeys : undefined,
+        });
+      }
+    }
+  } catch {
+    // Ignore malformed index config and keep builtin defaults.
+  }
+
+  const dedup = new Map<string, IndexSource>();
+  for (const source of out) {
+    dedup.set(source.name, source);
+  }
+  return Array.from(dedup.values()).sort((a, b) =>
+    a.name.localeCompare(b.name)
+  );
+}
+
+export function resolveKnownIndexSource(name: string): IndexSource | null {
+  const source = KNOWN_PROVIDER_SOURCES[name];
+  if (!source) {
+    return null;
+  }
+  return { ...source };
+}

package/src/remote-types.ts

@@ -0,0 +1,136 @@
+import type {
+  ManifestIntegrity,
+  ManifestSignature,
+  ManifestSignatureKey,
+} from "./remote-manifest-integrity";
+
+export type RemoteItemType = "skill" | "mcp" | "agent" | "snippet";
+
+export interface RemoteSkillPayload {
+  name: string;
+  files: Record<string, string>;
+}
+
+export interface RemoteMcpPayload {
+  name: string;
+  definition: Record<string, unknown>;
+}
+
+export interface RemoteAgentPayload {
+  fileName: string;
+  content: string;
+}
+
+export interface RemoteSnippetPayload {
+  marker: string;
+  content: string;
+}
+
+export interface RemoteIndexItemBase {
+  id: string;
+  type: RemoteItemType;
+  title?: string;
+  description?: string;
+  version?: string;
+  tags?: string[];
+  sourceUrl?: string;
+}
+
+export interface RemoteSkillItem extends RemoteIndexItemBase {
+  type: "skill";
+  skill: RemoteSkillPayload;
+}
+
+export interface RemoteMcpItem extends RemoteIndexItemBase {
+  type: "mcp";
+  mcp: RemoteMcpPayload;
+}
+
+export interface RemoteAgentItem extends RemoteIndexItemBase {
+  type: "agent";
+  agent: RemoteAgentPayload;
+}
+
+export interface RemoteSnippetItem extends RemoteIndexItemBase {
+  type: "snippet";
+  snippet: RemoteSnippetPayload;
+}
+
+export type RemoteIndexItem =
+  | RemoteSkillItem
+  | RemoteMcpItem
+  | RemoteAgentItem
+  | RemoteSnippetItem;
+
+export interface RemoteIndexManifest {
+  name: string;
+  url: string;
+  updatedAt?: string;
+  items: RemoteIndexItem[];
+}
+
+export type IndexSourceKind =
+  | "builtin"
+  | "manifest"
+  | "smithery"
+  | "glama"
+  | "skills-sh"
+  | "clawhub";
+
+export interface IndexSource {
+  name: string;
+  url: string;
+  kind: IndexSourceKind;
+  integrity?: ManifestIntegrity;
+  signature?: ManifestSignature;
+  signatureKeys?: ManifestSignatureKey[];
+}
+
+export interface LoadManifestHints {
+  query?: string;
+  itemId?: string;
+}
+
+export const BUILTIN_INDEX_NAME = "facult";
+export const BUILTIN_INDEX_URL = "builtin://facult";
+export const SMITHERY_INDEX_NAME = "smithery";
+export const GLAMA_INDEX_NAME = "glama";
+export const SKILLS_SH_INDEX_NAME = "skills.sh";
+export const CLAWHUB_INDEX_NAME = "clawhub";
+export const SMITHERY_API_BASE = "https://api.smithery.ai";
+export const GLAMA_API_BASE = "https://glama.ai/api/mcp/v1";
+export const SKILLS_SH_WEB_BASE = "https://skills.sh";
+export const CLAWHUB_API_BASE = "https://wry-manatee-359.convex.site/api/v1";
+
+export const KNOWN_PROVIDER_SOURCES: Record<string, IndexSource> = {
+  [SMITHERY_INDEX_NAME]: {
+    name: SMITHERY_INDEX_NAME,
+    url: SMITHERY_API_BASE,
+    kind: "smithery",
+  },
+  [GLAMA_INDEX_NAME]: {
+    name: GLAMA_INDEX_NAME,
+    url: GLAMA_API_BASE,
+    kind: "glama",
+  },
+  [SKILLS_SH_INDEX_NAME]: {
+    name: SKILLS_SH_INDEX_NAME,
+    url: SKILLS_SH_WEB_BASE,
+    kind: "skills-sh",
+  },
+  [CLAWHUB_INDEX_NAME]: {
+    name: CLAWHUB_INDEX_NAME,
+    url: CLAWHUB_API_BASE,
+    kind: "clawhub",
+  },
+  "skills-sh": {
+    name: SKILLS_SH_INDEX_NAME,
+    url: SKILLS_SH_WEB_BASE,
+    kind: "skills-sh",
+  },
+  "clawhub.ai": {
+    name: CLAWHUB_INDEX_NAME,
+    url: CLAWHUB_API_BASE,
+    kind: "clawhub",
+  },
+};