facult 1.0.3 → 1.1.0

package/README.md

@@ -1,12 +1,28 @@
 # facult
 
-`facult` is a CLI for managing coding-agent skills and MCP configs across tools.
+<div align="center">
+  <a aria-label="NPM version" href="https://www.npmjs.com/package/facult">
+    <img alt="facult npm version" src="https://img.shields.io/npm/v/facult.svg?style=flat-square&logo=npm&labelColor=000000&label=facult">
+  </a>
+  <a aria-label="CI status" href="https://github.com/hack-dance/facult/actions/workflows/ci.yml">
+    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/hack-dance/facult/ci.yml?branch=main&style=flat-square&logo=github&label=ci&labelColor=000000">
+  </a>
+  <a aria-label="hack.dance" href="https://hack.dance">
+    <img alt="Made by hack.dance" src="https://img.shields.io/badge/MADE%20BY%20HACK.DANCE-000000.svg?style=flat-square&labelColor=000000">
+  </a>
+  <a aria-label="X" href="https://x.com/dimitrikennedy">
+    <img alt="Follow on X" src="https://img.shields.io/twitter/follow/dimitrikennedy?style=social">
+  </a>
+</div>
+
+`facult` is a CLI for managing coding-agent configuration 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
+- sync managed outputs into Codex, Cursor, and Claude
+- manage a git-backed personal AI store under `~/.ai`
 
 ## What facult Is
 
@@ -16,6 +32,7 @@ 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
+- canonical source manager for global AI instructions, agents, snippets, tool configs, and rules
 
 ## Quick Start
 
@@ -60,7 +77,17 @@ Pin to a specific version:
 facult self-update --version 0.0.1
 ```
 
-### 2. Import existing skills/configs
+### 2. Start with a read-only inventory (recommended first)
+
+```bash
+facult scan --show-duplicates
+# optional machine-readable output
+facult scan --json
+```
+
+`scan` is read-only. It inspects local configs and reports what `facult` found without changing files.
+
+### 3. Import existing skills/configs
 
 ```bash
 facult consolidate --auto keep-current --from ~/.codex/skills --from ~/.agents/skills
@@ -69,9 +96,9 @@ 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`.
+Canonical source root: `~/.ai`. Generated state remains under `~/.facult`.
 
-### 3. Inspect what you have
+### 4. Inspect what you have
 
 ```bash
 facult list skills
@@ -80,7 +107,7 @@ facult show requesting-code-review
 facult show mcp:github
 ```
 
-### 4. Enable managed mode for your tools
+### 5. Enable managed mode for your tools
 
 ```bash
 facult manage codex
@@ -93,7 +120,21 @@ facult sync
 
 At this point, your selected skills are actively synced to all managed tools.
 
-### 5. Turn on source trust and strict install flow
+### 6. Turn on background autosync
+
+```bash
+facult autosync install --git-remote origin --git-branch main --git-interval-minutes 60
+facult autosync status
+```
+
+This installs a per-user macOS LaunchAgent that:
+- watches `~/.ai` for local changes and syncs managed tool outputs automatically
+- tracks dirty state for the canonical repo
+- runs a slower git autosync loop that batches changes, auto-commits them, rebases on the configured remote branch, and pushes on success
+
+If the repo hits a rebase conflict, remote autosync stops and reports the blocked state, but local tool sync continues.
+
+### 7. Turn on source trust and strict install flow
 
 ```bash
 facult sources list
@@ -134,6 +175,94 @@ facult sync
 
 Note: `templates init mcp ...` is a scaffold, not a running server by itself.
 
+## The `~/.ai` Model
+
+`facult` now treats `~/.ai` as the canonical, git-backed source of truth for personal AI configuration.
+
+Typical layout:
+
+```text
+~/.ai/
+  AGENTS.global.md
+  AGENTS.override.global.md
+  config.toml
+  config.local.toml
+  instructions/
+  snippets/
+  agents/
+  skills/
+  mcp/
+  templates/
+  tools/
+    codex/
+      config.toml
+      rules/
+  projects/
+    <slug>/
+      config.toml
+      config.local.toml
+      snippets/
+      instructions/
+```
+
+Important split:
+- `~/.ai` is canonical source
+- `~/.facult` is generated state, trust state, managed tool state, autosync state, and caches
+- tool homes such as `~/.codex` are rendered outputs
+
+### Canonical conventions
+
+- Use `instructions/` for reusable markdown documents
+- Use `snippets/` for composable partial blocks injected into markdown templates
+- Use `tools/codex/rules/*.rules` for actual Codex approval-policy rules
+- Use logical refs such as `@ai/instructions/WRITING.md` in tracked source
+- Use config-backed refs in prompts where you want stable named references such as `${refs.writing_rule}`
+
+### Config and env layering
+
+Canonical render context is layered explicitly:
+1. built-ins injected by `facult`
+2. `~/.ai/config.toml`
+3. `~/.ai/config.local.toml`
+4. `~/.ai/projects/<slug>/config.toml`
+5. `~/.ai/projects/<slug>/config.local.toml`
+6. explicit runtime overrides
+
+Built-ins currently include:
+- `AI_ROOT`
+- `HOME`
+- `PROJECT_ROOT`
+- `PROJECT_SLUG`
+- `TARGET_TOOL`
+- `TARGET_PATH`
+
+Recommended split:
+- `config.toml`: tracked, portable, non-secret refs/defaults
+- `config.local.toml`: ignored, machine-local paths and secrets
+
+### Snippets
+
+Snippets use HTML comment markers:
+
+```md
+<!-- fclty:global/codex/baseline -->
+<!-- /fclty:global/codex/baseline -->
+```
+
+Resolution rules:
+- unscoped marker `codingstyle` prefers `snippets/projects/<project>/codingstyle.md`, then falls back to `snippets/global/codingstyle.md`
+- explicit marker `global/codex/baseline` resolves directly to `snippets/global/codex/baseline.md`
+
+Commands:
+
+```bash
+facult snippets list
+facult snippets show global/codex/baseline
+facult snippets sync [--dry-run] [file...]
+```
+
+Snippets are already used during global Codex `AGENTS.md` rendering.
+
 ## Security and Trust
 
 `facult` has two trust layers:
@@ -168,10 +297,11 @@ Recommended security flow:
 ### Capability categories
 
 - Inventory: discover local skills, MCP configs, hooks, and instruction files
-- Management: consolidate, index, manage/unmanage tools, enable/disable entries
+- Management: consolidate, index, manage/unmanage tools, enable/disable entries, manage canonical AI config
 - 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
+- Automation: background autosync for local tool propagation and canonical repo git sync
 
 ### Command categories
 
@@ -199,6 +329,10 @@ facult enable <name> [--for <tool1,tool2,...>]
 facult enable mcp:<name> [--for <tool1,tool2,...>]
 facult disable <name> [--for <tool1,tool2,...>]
 facult sync [tool] [--dry-run]
+facult autosync install [tool] [--git-remote <name>] [--git-branch <name>] [--git-interval-minutes <n>] [--git-disable]
+facult autosync status [tool]
+facult autosync restart [tool]
+facult autosync uninstall [tool]
 ```
 
 - Remote catalogs and policies
@@ -241,7 +375,8 @@ facult <command> --help
 `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/`)
+3. `~/.ai`
+4. `~/agents/.facult` (or a detected legacy store under `~/agents/`)
 
 ### Runtime env vars
 
@@ -256,9 +391,13 @@ Under `~/.facult/`:
 - `sources.json` (latest inventory scan state)
 - `consolidated.json` (consolidation state)
 - `managed.json` (managed tool state)
+- `ai/index.json` (generated canonical AI inventory)
 - `audit/static-latest.json` (latest static audit report)
 - `audit/agent-latest.json` (latest agent audit report)
 - `trust/sources.json` (source trust policy state)
+- `autosync/services/*.json` (autosync service configs)
+- `autosync/state/*.json` (autosync runtime state)
+- `autosync/logs/*` (autosync service logs)
 
 ### Config reference
 
@@ -275,7 +414,7 @@ Under `~/.facult/`:
 Example:
 ```json
 {
-  "rootDir": "~/agents/.facult",
+  "rootDir": "~/.ai",
   "scanFrom": ["~/dev", "~/work"],
   "scanFromIgnore": ["vendor", ".venv"],
   "scanFromNoDefaultIgnore": false,
@@ -307,6 +446,42 @@ bun run install:status
 
 Default install path is `~/.facult/bin/facult`. You can pass a custom target dir via `--dir=/path`.
 
+## Autosync
+
+`facult autosync` is the background propagation layer for managed installs.
+
+Current v1 behavior:
+- macOS LaunchAgent-backed
+- immediate local managed-tool sync on `~/.ai` file changes
+- periodic git autosync for the canonical repo
+- automatic autosync commits with source-tagged commit messages such as:
+  - `chore(facult-autosync): sync canonical ai changes from <host> [service:all]`
+
+Recommended usage:
+
+```bash
+facult autosync install
+facult autosync status
+```
+
+Tool-scoped service:
+
+```bash
+facult autosync install codex
+```
+
+One-shot runner for verification/debugging:
+
+```bash
+facult autosync run --service all --once
+```
+
+Remote git policy:
+- do not sync on every file event
+- mark the canonical repo dirty on local changes
+- on the configured timer, fetch, auto-commit local canonical changes if needed, pull `--rebase`, then push
+- if rebase conflicts occur, remote autosync is blocked and reported, but local managed-tool sync keeps running
+
 ## CI and Release Automation
 
 - CI workflow: `.github/workflows/ci.yml`
@@ -373,3 +548,18 @@ bun run release:dry-run
 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.
+
+### Does facult now manage global AI config, not just skills and MCP?
+
+Yes. The core model now includes:
+- canonical personal AI source in `~/.ai`
+- rendered managed outputs in tool homes such as `~/.codex`
+- global instruction docs such as `AGENTS.global.md`
+- tool-native configs such as `~/.codex/config.toml`
+- tool-native rule files such as `~/.codex/rules/*.rules`
+
+### Do I still need to run `facult sync` manually?
+
+If autosync is not installed, yes.
+
+If autosync is installed, local changes under `~/.ai` propagate automatically to managed tools. Manual `facult sync` is still useful for explicit repair, dry-runs, and non-daemon workflows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Manage coding-agent skills and MCP configs across tools.",
   "type": "module",
   "license": "MIT",

package/src/adapters/codex.ts

@@ -11,6 +11,7 @@ export const codexAdapter: ToolAdapter = {
   getDefaultPaths: () => ({
     mcp: "~/.codex/mcp.json",
     skills: "~/.codex/skills",
+    agents: "~/.codex/agents",
     config: "~/.config/openai/codex.json",
   }),
   parseMcp: (config) => parseMcpConfig(config),

package/src/adapters/types.ts

@@ -21,6 +21,7 @@ export interface CanonicalSkill {
 export interface AdapterDefaultPaths {
   mcp?: string;
   skills?: string | string[];
+  agents?: string | string[];
   config?: string;
 }
 

package/src/agents.ts

@@ -0,0 +1,180 @@
+import { join } from "node:path";
+
+const AI_REF_RE = /(?<![\w@])@ai\/([^\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}`;
+  });
+}
+
+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 withRefs = renderAiRefs(interpolated, options.rootDir);
+    if (withRefs === rendered) {
+      return withRefs;
+    }
+    rendered = withRefs;
+  }
+
+  return rendered;
+}

package/src/ai-state.ts

@@ -0,0 +1,55 @@
+import { copyFile, mkdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { buildIndex } from "./index-builder";
+import { 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);
+  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" };
+}

package/src/audit/update-index.ts

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { ensureAiIndexPath } from "../ai-state";
 import type { FacultIndex } from "../index-builder";
-import { facultRootDir } from "../paths";
+import { facultAiIndexPath, facultRootDir } from "../paths";
 import type { AuditItemResult, Severity } from "./types";
 import { SEVERITY_ORDER } from "./types";
 
@@ -33,8 +33,12 @@ function computeAuditStatus(
   return worst >= SEVERITY_ORDER.high ? "flagged" : "passed";
 }
 
-async function loadIndex(rootDir: string): Promise<FacultIndex | null> {
-  const indexPath = join(rootDir, "index.json");
+async function loadIndex(homeDir: string): Promise<FacultIndex | null> {
+  const { path: indexPath } = await ensureAiIndexPath({
+    homeDir,
+    rootDir: facultRootDir(homeDir),
+    repair: true,
+  });
   const file = Bun.file(indexPath);
   if (!(await file.exists())) {
     return null;
@@ -46,8 +50,8 @@ async function loadIndex(rootDir: string): Promise<FacultIndex | null> {
   }
 }
 
-async function writeIndex(rootDir: string, index: FacultIndex) {
-  const indexPath = join(rootDir, "index.json");
+async function writeIndex(homeDir: string, index: FacultIndex) {
+  const indexPath = facultAiIndexPath(homeDir);
   await Bun.write(indexPath, `${JSON.stringify(index, null, 2)}\n`);
 }
 
@@ -57,9 +61,7 @@ export async function updateIndexFromAuditReport(opts: {
   results: AuditItemResult[];
 }): Promise<{ updated: boolean; reason?: string }> {
   const home = opts.homeDir ?? homedir();
-  const rootDir = facultRootDir(home);
-
-  const loaded = await loadIndex(rootDir);
+  const loaded = await loadIndex(home);
   if (!loaded) {
     return { updated: false, reason: "index-missing" };
   }
@@ -110,6 +112,6 @@ export async function updateIndexFromAuditReport(opts: {
   }
 
   index.updatedAt = new Date().toISOString();
-  await writeIndex(rootDir, index);
+  await writeIndex(home, index);
   return { updated: true };
 }