facult 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hack Dance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,383 @@
+# facult
+
+`facult` is a CLI for managing coding-agent skills and MCP configs across tools.
+
+It helps you:
+- discover what is installed on your machine
+- consolidate everything into one canonical store
+- review trust/security before installing remote content
+- enable a curated skill set across Codex, Cursor, and Claude
+
+## What facult Is
+
+If your agent setup feels scattered (`~/.codex`, `~/.agents`, tool-specific MCP JSON/TOML), `facult` gives you one place to manage it safely.
+
+Think of it as:
+- inventory + auditing for agent assets
+- package manager interface for skill/MCP catalogs
+- sync layer that applies your chosen setup to each tool
+
+## Quick Start
+
+### 1. Install facult
+
+Recommended global install:
+
+```bash
+npm install -g facult
+# or
+bun add -g facult
+facult --help
+```
+
+One-off usage without global install:
+
+```bash
+npx facult --help
+bunx facult --help
+```
+
+Direct binary install from GitHub Releases (macOS/Linux):
+
+```bash
+curl -fsSL https://github.com/hack-dance/facult/releases/latest/download/facult-install.sh | bash
+```
+
+If release assets are private, set a token first:
+
+```bash
+export FACULT_GITHUB_TOKEN="<github-token>"
+```
+
+Windows and manual installs can download the correct binary from each release page:
+`facult-<version>-<platform>-<arch>`.
+
+Update later with:
+
+```bash
+facult self-update
+# or
+facult update --self
+```
+
+Pin to a specific version:
+
+```bash
+facult self-update --version 0.0.1
+```
+
+### 2. Import existing skills/configs
+
+```bash
+facult consolidate --auto keep-current --from ~/.codex/skills --from ~/.agents/skills
+facult index
+```
+
+Why `keep-current`: it is deterministic and non-interactive for duplicate sources.
+
+Default canonical store: `~/agents/.facult`. You can change it later with `FACULT_ROOT_DIR` or `~/.facult/config.json`.
+
+### 3. Inspect what you have
+
+```bash
+facult list skills
+facult list mcp
+facult show requesting-code-review
+facult show mcp:github
+```
+
+### 4. Enable managed mode for your tools
+
+```bash
+facult manage codex
+facult manage cursor
+facult manage claude
+
+facult enable requesting-code-review receiving-code-review brainstorming systematic-debugging --for codex,cursor,claude
+facult sync
+```
+
+At this point, your selected skills are actively synced to all managed tools.
+
+### 5. Turn on source trust and strict install flow
+
+```bash
+facult sources list
+facult verify-source skills.sh --json
+facult sources trust skills.sh --note "reviewed"
+
+facult install skills.sh:code-review --as code-review-skills-sh --strict-source-trust
+```
+
+## Use facult from your agents
+
+`facult` is CLI-first. The practical setup is:
+1. Install `facult` globally so any agent runtime can execute it.
+2. Put allowed `facult` workflows in your agent instructions/skills.
+3. Optionally scaffold MCP wrappers if you want an MCP entry that delegates to `facult`.
+
+```bash
+# Scaffold reusable templates in the canonical store
+facult templates init agents
+facult templates init claude
+facult templates init skill facult-manager
+
+# Enable that skill for managed tools
+facult manage codex
+facult manage cursor
+facult manage claude
+facult enable facult-manager --for codex,cursor,claude
+facult sync
+```
+
+Optional MCP scaffold:
+
+```bash
+facult templates init mcp facult-cli
+facult enable mcp:facult-cli --for codex,cursor,claude
+facult sync
+```
+
+Note: `templates init mcp ...` is a scaffold, not a running server by itself.
+
+## Security and Trust
+
+`facult` has two trust layers:
+- Item trust: `facult trust <name>` / `facult untrust <name>`
+- Source trust: `facult sources ...` with levels `trusted`, `review`, `blocked`
+
+`facult` also supports two audit modes:
+
+1. Interactive audit workflow:
+```bash
+facult audit
+```
+2. Static audit rules (deterministic pattern checks):
+```bash
+facult audit --non-interactive --severity high
+facult audit --non-interactive mcp:github --severity medium --json
+```
+3. Agent-based audit (Claude/Codex review pass):
+```bash
+facult audit --non-interactive --with claude --max-items 50
+facult audit --non-interactive --with codex --max-items all --json
+```
+
+Recommended security flow:
+1. `facult verify-source <source>`
+2. `facult sources trust <source>` only after review
+3. use `--strict-source-trust` for `install`/`update`
+4. run both static and agent audits on a schedule
+
+## Comprehensive Reference
+
+### Capability categories
+
+- Inventory: discover local skills, MCP configs, hooks, and instruction files
+- Management: consolidate, index, manage/unmanage tools, enable/disable entries
+- Security: static audit, agent audit, item trust, source trust, source verification
+- Distribution: search/install/update from catalogs and verified manifests
+- DX: scaffold templates and sync snippets into instruction/config files
+
+### Command categories
+
+- Inventory and discovery
+```bash
+facult scan [--from <path>] [--json] [--show-duplicates]
+facult list [skills|mcp|agents|snippets] [--enabled-for <tool>] [--untrusted] [--flagged] [--pending]
+facult show <name>
+facult show mcp:<name> [--show-secrets]
+```
+
+- Canonical store and migration
+```bash
+facult consolidate [--auto keep-current|keep-incoming|keep-newest] [--from <path> ...]
+facult index [--force]
+facult migrate [--from <path>] [--dry-run] [--move] [--write-config]
+```
+
+- Managed mode and rollout
+```bash
+facult manage <tool>
+facult unmanage <tool>
+facult managed
+facult enable <name> [--for <tool1,tool2,...>]
+facult enable mcp:<name> [--for <tool1,tool2,...>]
+facult disable <name> [--for <tool1,tool2,...>]
+facult sync [tool] [--dry-run]
+```
+
+- Remote catalogs and policies
+```bash
+facult search <query> [--index <name>] [--limit <n>]
+facult install <index:item> [--as <name>] [--force] [--strict-source-trust]
+facult update [--apply] [--strict-source-trust]
+facult verify-source <name> [--json]
+facult sources list
+facult sources trust <source> [--note <text>]
+facult sources review <source> [--note <text>]
+facult sources block <source> [--note <text>]
+facult sources clear <source>
+```
+
+- Templates and snippets
+```bash
+facult templates list
+facult templates init skill <name>
+facult templates init mcp <name>
+facult templates init snippet <marker>
+facult templates init agents
+facult templates init claude
+
+facult snippets list
+facult snippets show <marker>
+facult snippets create <marker>
+facult snippets edit <marker>
+facult snippets sync [--dry-run] [file...]
+```
+
+For full flags and exact usage:
+```bash
+facult --help
+facult <command> --help
+```
+
+### Root resolution
+
+`facult` resolves the canonical root in this order:
+1. `FACULT_ROOT_DIR`
+2. `~/.facult/config.json` (`rootDir`)
+3. `~/agents/.facult` (or a detected legacy store under `~/agents/`)
+
+### Runtime env vars
+
+- `FACULT_ROOT_DIR`: override canonical store location
+- `FACULT_GITHUB_TOKEN`: auth token for private GitHub release asset downloads
+- `GITHUB_TOKEN` / `GH_TOKEN`: fallback tokens for release asset downloads
+- `FACULT_VERSION`: version selector for `scripts/install.sh` (`latest` by default)
+- `FACULT_INSTALL_DIR`: install target dir for `scripts/install.sh` (`~/.facult/bin` by default)
+- `FACULT_INSTALL_PM`: force package manager detection for npm bootstrap launcher (`npm` or `bun`)
+
+### State and report files
+
+Under `~/.facult/`:
+- `sources.json` (latest inventory scan state)
+- `consolidated.json` (consolidation state)
+- `managed.json` (managed tool state)
+- `audit/static-latest.json` (latest static audit report)
+- `audit/agent-latest.json` (latest agent audit report)
+- `trust/sources.json` (source trust policy state)
+
+### Config reference
+
+`~/.facult/config.json` supports:
+- `rootDir`
+- `scanFrom`
+- `scanFromIgnore`
+- `scanFromNoDefaultIgnore`
+- `scanFromMaxVisits`
+- `scanFromMaxResults`
+
+`scanFrom*` settings are used by `scan`/`audit` unless `--no-config-from` is passed.
+
+Example:
+```json
+{
+  "rootDir": "~/agents/.facult",
+  "scanFrom": ["~/dev", "~/work"],
+  "scanFromIgnore": ["vendor", ".venv"],
+  "scanFromNoDefaultIgnore": false,
+  "scanFromMaxVisits": 20000,
+  "scanFromMaxResults": 5000
+}
+```
+
+### Source aliases and custom indices
+
+Default source aliases:
+- `facult` (builtin templates)
+- `smithery`
+- `glama`
+- `skills.sh`
+- `clawhub`
+
+Custom remote sources can be defined in `~/.facult/indices.json` (manifest URL, optional integrity, optional signature keys/signature verification settings).
+
+## Local Install Modes
+
+For local CLI setup (outside npm global install), use:
+
+```bash
+bun run install:dev
+bun run install:bin
+bun run install:status
+```
+
+Default install path is `~/.facult/bin/facult`. You can pass a custom target dir via `--dir=/path`.
+
+## CI and Release Automation
+
+- CI workflow: `.github/workflows/ci.yml`
+- Release workflow: `.github/workflows/release.yml`
+- Semantic-release config: `.releaserc.json`
+
+Release behavior:
+1. Every push to `main` runs full checks.
+2. `semantic-release` creates the version/tag and GitHub release (npm publish is disabled in this phase).
+3. The same release workflow then builds platform binaries and uploads them to that GitHub release.
+4. npm publish runs only after binary asset upload succeeds (`publish-npm` depends on `publish-assets`).
+5. Published release assets include platform binaries, `facult-install.sh`, and `SHA256SUMS`.
+6. The npm package launcher resolves your platform, downloads the matching release binary, caches it under `~/.facult/runtime/<version>/<platform-arch>/`, and runs it.
+
+Current prebuilt binary targets:
+- `darwin-x64`
+- `darwin-arm64`
+- `linux-x64`
+- `windows-x64`
+
+Self-update behavior:
+1. npm/bun global install: updates via package manager (`npm install -g facult@...` or `bun add -g facult@...`).
+2. Direct binary install (release script/local binary path): downloads and replaces the binary in place.
+3. Use `facult self-update` (or `facult update --self`).
+
+Required secrets for publish:
+- `NPM_TOKEN`
+
+Local semantic-release dry-runs require a supported Node runtime (`>=24.10`).
+
+Recommended one-time bootstrap before first auto release:
+```bash
+git tag v0.0.0
+git push origin v0.0.0
+```
+
+This makes the first semantic-release increment land at `0.0.1` for patch-level changes.
+
+## Commit Hygiene
+
+Some MCP config files can contain secrets. Keep local generated artifacts and secret-bearing config files ignored and out of commits.
+
+## Local Development
+
+```bash
+bun run install:status
+bun run install:dev
+bun run install:bin
+bun run build
+bun run build:verify
+bun run type-check
+bun run test:ci
+bun test
+bun run check
+bun run fix
+bun run pack:dry-run
+bun run release:dry-run
+```
+
+## FAQ
+
+### Does facult run its own MCP server today?
+
+Not as a first-party `facult mcp serve` runtime.
+
+`facult` currently focuses on inventory, trust/audit, install/update, and managed sync of skills/MCP configs.

package/bin/facult.cjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const fsp = require("node:fs/promises");
+const https = require("node:https");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const pkg = require("../package.json");
+
+const REPO_OWNER = "hack-dance";
+const REPO_NAME = "facult";
+const DOWNLOAD_RETRIES = 12;
+const DOWNLOAD_RETRY_DELAY_MS = 5000;
+
+async function main() {
+  const resolved = resolveTarget();
+  if (!resolved.ok) {
+    console.error(resolved.message);
+    process.exit(1);
+  }
+
+  const version = String(pkg.version || "").trim();
+  if (!version) {
+    console.error("Invalid package version.");
+    process.exit(1);
+  }
+
+  const home = os.homedir();
+  const cacheRoot = path.join(home, ".facult", "runtime");
+  const installDir = path.join(
+    cacheRoot,
+    version,
+    `${resolved.platform}-${resolved.arch}`
+  );
+  const binaryName = resolved.platform === "windows" ? "facult.exe" : "facult";
+  const binaryPath = path.join(installDir, binaryName);
+  const githubToken = resolveGitHubToken();
+
+  if (!(await fileExists(binaryPath))) {
+    const tag = `v${version}`;
+    const assetName = `facult-${version}-${resolved.platform}-${resolved.arch}${resolved.ext}`;
+    const url = `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download/${tag}/${assetName}`;
+
+    await fsp.mkdir(installDir, { recursive: true });
+    const tmpPath = `${binaryPath}.tmp-${Date.now()}`;
+    try {
+      await downloadWithRetry(url, tmpPath, {
+        attempts: DOWNLOAD_RETRIES,
+        delayMs: DOWNLOAD_RETRY_DELAY_MS,
+        token: githubToken,
+      });
+      if (resolved.platform !== "windows") {
+        await fsp.chmod(tmpPath, 0o755);
+      }
+      await fsp.rename(tmpPath, binaryPath);
+    } catch (error) {
+      await safeUnlink(tmpPath);
+      const message =
+        error instanceof Error ? error.message : String(error ?? "");
+      console.error(
+        [
+          "Unable to download the facult binary for this platform.",
+          `Expected asset: ${assetName}`,
+          `URL: ${url}`,
+          `Reason: ${message}`,
+          "",
+          "Try installing directly from releases:",
+          "https://github.com/hack-dance/facult/releases",
+        ].join("\n")
+      );
+      process.exit(1);
+    }
+  }
+
+  const packageManager = detectPackageManager();
+  await writeInstallState({
+    method: "npm-binary-cache",
+    version,
+    binaryPath,
+    packageManager,
+  });
+
+  const args = process.argv.slice(2);
+  const result = spawnSync(binaryPath, args, {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      FACULT_INSTALL_METHOD: "npm-binary-cache",
+      FACULT_NPM_PACKAGE_VERSION: version,
+      FACULT_RUNTIME_BINARY: binaryPath,
+      FACULT_INSTALL_PM: packageManager,
+    },
+  });
+
+  if (typeof result.status === "number") {
+    process.exit(result.status);
+  }
+  process.exit(1);
+}
+
+function resolveTarget() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (platform === "darwin" && arch === "arm64") {
+    return { ok: true, platform: "darwin", arch: "arm64", ext: "" };
+  }
+  if (platform === "darwin" && arch === "x64") {
+    return { ok: true, platform: "darwin", arch: "x64", ext: "" };
+  }
+  if (platform === "linux" && arch === "x64") {
+    return { ok: true, platform: "linux", arch: "x64", ext: "" };
+  }
+  if (platform === "win32" && arch === "x64") {
+    return { ok: true, platform: "windows", arch: "x64", ext: ".exe" };
+  }
+  return {
+    ok: false,
+    message: [
+      `Unsupported platform/arch: ${platform}/${arch}`,
+      "Prebuilt binaries are currently available for:",
+      "  - darwin/x64",
+      "  - darwin/arm64",
+      "  - linux/x64",
+      "  - windows/x64",
+    ].join("\n"),
+  };
+}
+
+function detectPackageManager() {
+  const forced = String(process.env.FACULT_INSTALL_PM || "").trim();
+  if (forced === "bun" || forced === "npm") {
+    return forced;
+  }
+
+  const userAgent = String(process.env.npm_config_user_agent || "");
+  if (userAgent.startsWith("bun/")) {
+    return "bun";
+  }
+  if (userAgent.startsWith("npm/")) {
+    return "npm";
+  }
+  if (__filename.includes(`${path.sep}.bun${path.sep}`)) {
+    return "bun";
+  }
+  return "npm";
+}
+
+function resolveGitHubToken() {
+  const tokenCandidates = [
+    process.env.FACULT_GITHUB_TOKEN,
+    process.env.GITHUB_TOKEN,
+    process.env.GH_TOKEN,
+  ];
+  for (const candidate of tokenCandidates) {
+    const token = String(candidate || "").trim();
+    if (token) {
+      return token;
+    }
+  }
+  return "";
+}
+
+function buildRequestHeaders(url, token) {
+  const headers = {
+    "user-agent": "facult-installer",
+    accept: "application/octet-stream",
+  };
+  if (!token) {
+    return headers;
+  }
+
+  try {
+    const hostname = new URL(url).hostname.toLowerCase();
+    if (hostname === "github.com" || hostname === "api.github.com") {
+      headers.authorization = `Bearer ${token}`;
+    }
+  } catch {
+    // Keep default headers if URL parsing fails.
+  }
+
+  return headers;
+}
+
+async function download(url, destinationPath, options = {}) {
+  await new Promise((resolve, reject) => {
+    const request = https.get(
+      url,
+      {
+        headers: buildRequestHeaders(url, options.token),
+      },
+      (response) => {
+        if (
+          response.statusCode &&
+          response.statusCode >= 300 &&
+          response.statusCode < 400 &&
+          response.headers.location
+        ) {
+          response.resume();
+          download(response.headers.location, destinationPath, options)
+            .then(resolve)
+            .catch(reject);
+          return;
+        }
+
+        if (response.statusCode !== 200) {
+          response.resume();
+          reject(
+            new Error(
+              `HTTP ${response.statusCode ?? "unknown"} while downloading`
+            )
+          );
+          return;
+        }
+
+        const file = fs.createWriteStream(destinationPath);
+        response.pipe(file);
+        file.on("finish", () => {
+          file.close((err) => {
+            if (err) {
+              reject(err);
+              return;
+            }
+            resolve(undefined);
+          });
+        });
+        file.on("error", (err) => reject(err));
+      }
+    );
+
+    request.on("error", (err) => reject(err));
+  });
+}
+
+async function downloadWithRetry(url, destinationPath, options) {
+  let lastError = null;
+  for (let attempt = 1; attempt <= options.attempts; attempt += 1) {
+    try {
+      await safeUnlink(destinationPath);
+      await download(url, destinationPath, { token: options.token });
+      return;
+    } catch (error) {
+      lastError = error;
+      if (attempt >= options.attempts) {
+        break;
+      }
+      await sleep(options.delayMs);
+    }
+  }
+  throw lastError instanceof Error
+    ? lastError
+    : new Error(String(lastError ?? ""));
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+async function writeInstallState(state) {
+  const home = os.homedir();
+  const dir = path.join(home, ".facult");
+  const installPath = path.join(dir, "install.json");
+  await fsp.mkdir(dir, { recursive: true });
+  const payload = {
+    version: 1,
+    method: state.method,
+    installedAt: new Date().toISOString(),
+    packageVersion: state.version,
+    binaryPath: state.binaryPath,
+    source: "npm",
+    packageManager: state.packageManager,
+  };
+  await fsp.writeFile(installPath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+async function fileExists(filePath) {
+  try {
+    await fsp.stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function safeUnlink(filePath) {
+  try {
+    await fsp.unlink(filePath);
+  } catch {
+    // ignore
+  }
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  console.error(message);
+  process.exit(1);
+});