unfairly 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# unfairly
+
+CLI + stdio MCP for syncing Unfairly vaults to local markdown.
+
+## Quick start
+
+```bash
+npm install -g unfairly@latest
+cd ~/path/to/your/repo-or-workspace
+unfairly init        # interactive: paste mcp_* token from app.unfairly.ai/dashboard/setup
+unfairly pull        # fetch all accessible vaults to .unfairly/
+unfairly status      # show modified-locally count per vault
+# edit any .md file in .unfairly/{vault}/{section}/{slug}.md
+unfairly push        # broadcast back to cloud
+```
+
+## Commands
+
+- `unfairly init` — set up `.unfairly/` in cwd, prompt for token, run first pull
+- `unfairly pull [vault]` — paginated diff from cloud, write/update markdown files, propagate deletes
+- `unfairly push [vault]` — send dirty files to cloud with stale-check; conflicts get `<<<<<<< local / >>>>>>> cloud` markers in-place
+- `unfairly status` — per-vault last-pulled timestamp + modified-locally count
+- `unfairly resolve <path>` — mark a conflicted file as resolved (after editing out merge markers)
+- `unfairly watch` — opt-in fs watcher; debounced 5s auto-push on save
+- `unfairly mcp` — stdio MCP server exposing `pull_vault`, `push_vault`, `sync_status` tools to agent hosts (Claude Code, Codex, cowork)
+
+## Local store layout
+
+```
+.unfairly/
+├── manifest.json           # vault list + per-doc sha map; atomic writes
+├── .gitignore              # generated; ignores cache/
+├── unfairly-app/           # repo-bound vault, git-tracked
+│   └── architecture/
+│       └── system.md
+└── cache/                  # gitignored bucket for personal/sensitive vaults
+    └── hq/
+        └── people/
+            └── founders.md
+```
+
+Per-vault git-tracking is server-side via `rooms.track_in_git`. Tracked vaults live at the root; untracked vaults live under `cache/`.
+
+## Design
+
+See [`docs/superpowers/specs/2026-05-07-local-context-sync-design.md`](../docs/superpowers/specs/2026-05-07-local-context-sync-design.md) in the main repo for architecture, conflict resolution, and integration with the cloud `/api/mcp` endpoint.

package/dist/cmd/init.js

@@ -0,0 +1,80 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { SyncClient } from "../sync/api.js";
+import { emptyManifest, writeManifest } from "../sync/manifest.js";
+import { getToken, setToken } from "../sync/credentials.js";
+import { runPull } from "./pull.js";
+const DEFAULT_API = "https://app.unfairly.ai";
+export async function runInit() {
+    const cwd = process.cwd();
+    const target = path.join(cwd, ".unfairly");
+    // Confirm overwrite if .unfairly/ already exists
+    try {
+        await fs.access(target);
+        const rl = readline.createInterface({ input, output });
+        const ans = await rl.question(`.unfairly/ already exists. Re-initialize? [y/N] `);
+        rl.close();
+        if (ans.trim().toLowerCase() !== "y") {
+            console.log("aborted");
+            return;
+        }
+    }
+    catch {
+        // didn't exist; fine
+    }
+    // Token
+    let token = await getToken();
+    if (!token) {
+        const rl = readline.createInterface({ input, output });
+        console.log("Get a token at https://app.unfairly.ai/dashboard/setup (click 'Issue token').");
+        token = (await rl.question("Paste mcp_* token: ")).trim();
+        rl.close();
+        if (!token.startsWith("mcp_")) {
+            console.error("Token must start with mcp_");
+            process.exit(1);
+        }
+        await setToken(token);
+    }
+    // Verify token + list vaults
+    const apiUrl = process.env.UNFAIRLY_API_URL ?? DEFAULT_API;
+    const client = new SyncClient(apiUrl, token);
+    let status;
+    try {
+        status = await client.status();
+    }
+    catch (err) {
+        console.error(`Failed to reach ${apiUrl}/api/sync/status: ${err.message}`);
+        process.exit(1);
+    }
+    if (status.vaults.length === 0) {
+        console.error("No accessible vaults. Ask an admin to grant you access.");
+        process.exit(1);
+    }
+    console.log(`Found ${status.vaults.length} accessible vault(s):`);
+    for (const v of status.vaults) {
+        console.log(`  - ${v.name} (${v.slug}) — ${v.doc_count} docs${v.track_in_git ? "" : " · gitignored"}`);
+    }
+    // Seed manifest
+    await fs.mkdir(target, { recursive: true });
+    const manifest = emptyManifest(apiUrl);
+    for (const v of status.vaults) {
+        manifest.vaults[v.slug] = {
+            id: v.id,
+            slug: v.slug,
+            name: v.name,
+            track_in_git: v.track_in_git,
+            last_pulled_at: null,
+            last_pushed_at: null,
+            docs: {},
+        };
+    }
+    await writeManifest(cwd, manifest);
+    // Generate .gitignore (cache/ is the gitignored bucket for non-tracked vaults)
+    const gitignorePath = path.join(target, ".gitignore");
+    await fs.writeFile(gitignorePath, "# generated by `unfairly init`\ncache/\n*.tmp.*\n", "utf8");
+    // First pull (all vaults)
+    await runPull(undefined);
+    console.log("Done. Run `unfairly status` to confirm. Edit any .md file under .unfairly/ and run `unfairly push` to broadcast.");
+}

package/dist/cmd/mcp.js

@@ -0,0 +1,85 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { runPull } from "./pull.js";
+import { runPush } from "./push.js";
+import { runStatus } from "./status.js";
+const PullSchema = z.object({ room: z.string().optional() }).strict();
+const PushSchema = z.object({ room: z.string().optional() }).strict();
+const StatusSchema = z.object({}).strict();
+export async function runMcp() {
+    const server = new Server({ name: "unfairly-sync", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "pull_vault",
+                description: "Sync local .unfairly/ from cloud. Pass `room` to scope to one vault, omit for all accessible vaults. Reports docs added/updated/deleted.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        room: {
+                            type: "string",
+                            description: "Vault slug to scope to (optional)",
+                        },
+                    },
+                },
+            },
+            {
+                name: "push_vault",
+                description: "Push locally-modified markdown to cloud. Stale-check via expected_updated_at. Returns 409s for conflicts; CLI rewrites those files with merge markers.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        room: {
+                            type: "string",
+                            description: "Vault slug to scope to (optional)",
+                        },
+                    },
+                },
+            },
+            {
+                name: "sync_status",
+                description: "Show local sync status: per-vault last-pulled timestamp + modified-locally count.",
+                inputSchema: { type: "object", properties: {} },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        const captured = [];
+        const origLog = console.log;
+        const origWarn = console.warn;
+        const origError = console.error;
+        console.log = (...a) => captured.push(a.map(String).join(" "));
+        console.warn = (...a) => captured.push("! " + a.map(String).join(" "));
+        console.error = (...a) => captured.push("ERR " + a.map(String).join(" "));
+        try {
+            if (name === "pull_vault") {
+                const { room } = PullSchema.parse(args ?? {});
+                await runPull(room);
+            }
+            else if (name === "push_vault") {
+                const { room } = PushSchema.parse(args ?? {});
+                await runPush(room);
+            }
+            else if (name === "sync_status") {
+                StatusSchema.parse(args ?? {});
+                await runStatus();
+            }
+            else {
+                throw new Error(`unknown tool: ${name}`);
+            }
+        }
+        finally {
+            console.log = origLog;
+            console.warn = origWarn;
+            console.error = origError;
+        }
+        return {
+            content: [{ type: "text", text: captured.join("\n") || "ok" }],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/cmd/pull.js

@@ -0,0 +1,98 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { SyncClient } from "../sync/api.js";
+import { readManifest, writeManifest } from "../sync/manifest.js";
+import { buildFileFromServer, writeDocFile } from "../sync/files.js";
+import { getToken } from "../sync/credentials.js";
+const execFileAsync = promisify(execFile);
+async function gitMv(from, to) {
+    try {
+        await execFileAsync("git", ["mv", from, to], { cwd: process.cwd() });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function tryUnlink(p) {
+    try {
+        await fs.unlink(p);
+    }
+    catch { }
+}
+export async function runPull(vaultArg) {
+    const cwd = process.cwd();
+    const manifest = await readManifest(cwd);
+    if (!manifest) {
+        console.error("No .unfairly/ found. Run `unfairly init` first.");
+        process.exit(1);
+    }
+    const token = await getToken();
+    if (!token) {
+        console.error("No token. Run `unfairly init` to authenticate.");
+        process.exit(1);
+    }
+    const client = new SyncClient(manifest.api_url, token);
+    const targets = vaultArg ? [vaultArg] : Object.keys(manifest.vaults);
+    for (const slug of targets) {
+        const v = manifest.vaults[slug];
+        if (!v) {
+            console.error(`No vault \`${slug}\` in manifest.`);
+            continue;
+        }
+        process.stdout.write(`pulling ${slug}... `);
+        const result = await client.pullAll(slug, v.last_pulled_at);
+        // Vault root: track_in_git → .unfairly/{slug}/, else .unfairly/cache/{slug}/
+        const vaultRoot = v.track_in_git ? slug : path.join("cache", slug);
+        const absVaultRoot = path.join(cwd, ".unfairly", vaultRoot);
+        await fs.mkdir(absVaultRoot, { recursive: true });
+        let upserts = 0;
+        let deletes = 0;
+        let renames = 0;
+        for (const doc of result.docs) {
+            const file = buildFileFromServer(doc, vaultRoot);
+            const relPath = file.path;
+            const absPath = path.join(cwd, ".unfairly", relPath);
+            // Detect rename: same id, different stored path
+            const prev = v.docs[doc.id];
+            if (prev && prev.path !== relPath) {
+                const prevAbs = path.join(cwd, ".unfairly", prev.path);
+                // Tracked vault → use git mv to preserve history
+                if (v.track_in_git) {
+                    await fs.mkdir(path.dirname(absPath), { recursive: true });
+                    const ok = await gitMv(prevAbs, absPath);
+                    if (!ok) {
+                        await tryUnlink(prevAbs);
+                    }
+                }
+                else {
+                    await tryUnlink(prevAbs);
+                }
+                renames++;
+            }
+            await writeDocFile(absPath, file.content);
+            v.docs[doc.id] = {
+                slug: doc.slug,
+                path: relPath,
+                sha: file.sha,
+                updated_at: doc.updated_at,
+                source_type: doc.source_type ?? "markdown",
+            };
+            upserts++;
+        }
+        for (const tomb of result.deleted) {
+            const prev = v.docs[tomb.id];
+            if (!prev)
+                continue;
+            const absPath = path.join(cwd, ".unfairly", prev.path);
+            await tryUnlink(absPath);
+            delete v.docs[tomb.id];
+            deletes++;
+        }
+        v.last_pulled_at = new Date().toISOString();
+        console.log(`+${upserts} -${deletes}${renames ? ` ~${renames}` : ""}`);
+    }
+    await writeManifest(cwd, manifest);
+}

package/dist/cmd/push.js

@@ -0,0 +1,84 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { SyncClient } from "../sync/api.js";
+import { readManifest, writeManifest } from "../sync/manifest.js";
+import { computeSha, readDocFile, readDocRaw } from "../sync/files.js";
+import { buildConflictFile } from "../sync/conflict.js";
+import { getToken } from "../sync/credentials.js";
+export async function runPush(vaultArg) {
+    const cwd = process.cwd();
+    const manifest = await readManifest(cwd);
+    if (!manifest) {
+        console.error("No .unfairly/ found. Run `unfairly init` first.");
+        process.exit(1);
+    }
+    const token = await getToken();
+    if (!token) {
+        console.error("No token. Run `unfairly init` to authenticate.");
+        process.exit(1);
+    }
+    const client = new SyncClient(manifest.api_url, token);
+    const targets = vaultArg ? [vaultArg] : Object.keys(manifest.vaults);
+    let conflicts = 0;
+    let pushed = 0;
+    for (const slug of targets) {
+        const v = manifest.vaults[slug];
+        if (!v) {
+            console.error(`No vault \`${slug}\` in manifest.`);
+            continue;
+        }
+        for (const [docId, entry] of Object.entries(v.docs)) {
+            const absPath = path.join(cwd, ".unfairly", entry.path);
+            let raw;
+            let local;
+            try {
+                raw = await readDocRaw(absPath);
+                local = await readDocFile(absPath);
+            }
+            catch {
+                // File missing locally — Phase 1 punt: skip (delete-locally not handled)
+                continue;
+            }
+            const currentSha = computeSha(raw);
+            if (currentSha === entry.sha)
+                continue; // not dirty
+            const result = await client.push({
+                vault: slug,
+                doc_id: docId,
+                expected_updated_at: entry.updated_at,
+                body: local.body,
+                client_frontmatter: local.frontmatter,
+            });
+            if (result.status === 200 && "ok" in result.data) {
+                const { updated_at, rejected_frontmatter } = result.data;
+                entry.sha = currentSha;
+                entry.updated_at = updated_at;
+                pushed++;
+                if (rejected_frontmatter.length > 0) {
+                    console.warn(`! ${entry.path}: server kept ${rejected_frontmatter.map((r) => r.key).join(", ")} (your changes ignored)`);
+                }
+            }
+            else if (result.status === 409 && "server_body" in result.data) {
+                const d = result.data;
+                const conflictContent = buildConflictFile({
+                    serverFrontmatter: d.server_frontmatter,
+                    localBody: local.body,
+                    serverBody: d.server_body,
+                    serverUpdatedAt: d.server_updated_at,
+                });
+                await fs.writeFile(absPath, conflictContent, "utf8");
+                // Update entry's known updated_at to the server's so a resolve+push works
+                entry.updated_at = d.server_updated_at;
+                console.warn(`! conflict: ${entry.path} (server updated ${d.server_updated_at}). Edit to remove merge markers, then \`unfairly resolve <path>\` and \`unfairly push\`.`);
+                conflicts++;
+            }
+            else {
+                const err = "error" in result.data ? result.data.error : "unknown";
+                console.error(`push failed for ${entry.path}: ${err}`);
+            }
+        }
+        v.last_pushed_at = new Date().toISOString();
+    }
+    await writeManifest(cwd, manifest);
+    console.log(`pushed ${pushed}, conflicts ${conflicts}`);
+}

package/dist/cmd/resolve.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { readManifest } from "../sync/manifest.js";
+export async function runResolve(relOrAbsPath) {
+    const cwd = process.cwd();
+    const manifest = await readManifest(cwd);
+    if (!manifest) {
+        console.error("No .unfairly/ found.");
+        process.exit(1);
+    }
+    const abs = path.isAbsolute(relOrAbsPath)
+        ? relOrAbsPath
+        : path.join(cwd, relOrAbsPath);
+    const raw = await fs.readFile(abs, "utf8");
+    if (raw.includes("<<<<<<< local") || raw.includes(">>>>>>> cloud")) {
+        console.error("Merge markers still present. Edit the file to remove them, then re-run resolve.");
+        process.exit(1);
+    }
+    // Verify the file is in the manifest. We do NOT mutate entry.sha — leaving
+    // the pre-conflict sha lets `push` detect the resolved content as dirty
+    // and ship it. entry.updated_at was already advanced to server's during
+    // the conflict, so the next push's expected_updated_at will match.
+    const relPath = path.relative(path.join(cwd, ".unfairly"), abs);
+    for (const v of Object.values(manifest.vaults)) {
+        for (const [, entry] of Object.entries(v.docs)) {
+            if (entry.path === relPath) {
+                console.log(`markers cleared. Run \`unfairly push\` to broadcast.`);
+                return;
+            }
+        }
+    }
+    console.error("path not found in manifest");
+    process.exit(1);
+}

package/dist/cmd/status.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { readManifest } from "../sync/manifest.js";
+import { computeSha, readDocRaw } from "../sync/files.js";
+export async function runStatus() {
+    const cwd = process.cwd();
+    const manifest = await readManifest(cwd);
+    if (!manifest) {
+        console.error("No .unfairly/ found. Run `unfairly init` first.");
+        process.exit(1);
+    }
+    for (const [slug, v] of Object.entries(manifest.vaults)) {
+        let modified = 0;
+        for (const [, entry] of Object.entries(v.docs)) {
+            try {
+                const raw = await readDocRaw(path.join(cwd, ".unfairly", entry.path));
+                if (computeSha(raw) !== entry.sha)
+                    modified++;
+            }
+            catch { }
+        }
+        const pulled = v.last_pulled_at ?? "never";
+        const pushed = v.last_pushed_at ?? "never";
+        console.log(`${slug.padEnd(20)} pulled ${pulled} · pushed ${pushed} · modified ${modified}`);
+    }
+}

package/dist/cmd/watch.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+import chokidar from "chokidar";
+import { runPush } from "./push.js";
+export async function runWatch() {
+    const cwd = process.cwd();
+    const dir = path.join(cwd, ".unfairly");
+    console.log(`watching ${dir} (Ctrl+C to stop)`);
+    let timer = null;
+    const debouncePush = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            runPush(undefined).catch((e) => console.error("push failed:", e.message));
+        }, 5000);
+    };
+    chokidar
+        .watch(dir, {
+        ignored: [/(^|[\/\\])\../, /manifest\.json$/, /\.tmp\./],
+        ignoreInitial: true,
+        persistent: true,
+    })
+        .on("change", debouncePush)
+        .on("add", debouncePush);
+    await new Promise(() => { }); // keep alive until SIGINT
+}

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+await yargs(hideBin(process.argv))
+    .scriptName("unfairly")
+    .usage("$0 <cmd> [args]")
+    .command("init", "Initialize .unfairly/ in cwd and pull all accessible vaults", () => { }, async () => {
+    const { runInit } = await import("./cmd/init.js");
+    await runInit();
+})
+    .command("pull [vault]", "Pull markdown from cloud", (y) => y.positional("vault", { type: "string" }), async (argv) => {
+    const { runPull } = await import("./cmd/pull.js");
+    await runPull(argv.vault);
+})
+    .command("push [vault]", "Push local edits to cloud", (y) => y.positional("vault", { type: "string" }), async (argv) => {
+    const { runPush } = await import("./cmd/push.js");
+    await runPush(argv.vault);
+})
+    .command("status", "Show local-vs-cloud sync status", () => { }, async () => {
+    const { runStatus } = await import("./cmd/status.js");
+    await runStatus();
+})
+    .command("resolve <path>", "Mark a conflicted file as resolved", (y) => y.positional("path", { type: "string", demandOption: true }), async (argv) => {
+    const { runResolve } = await import("./cmd/resolve.js");
+    await runResolve(argv.path);
+})
+    .command("watch", "Watch .unfairly/ for changes and auto-push", () => { }, async () => {
+    const { runWatch } = await import("./cmd/watch.js");
+    await runWatch();
+})
+    .command("mcp", "Run as a stdio MCP server (for agent host integration)", () => { }, async () => {
+    const { runMcp } = await import("./cmd/mcp.js");
+    await runMcp();
+})
+    .demandCommand(1)
+    .strict()
+    .help()
+    .parse();

package/dist/sync/api.js

@@ -0,0 +1,54 @@
+export class SyncClient {
+    apiUrl;
+    token;
+    constructor(apiUrl, token) {
+        this.apiUrl = apiUrl;
+        this.token = token;
+    }
+    headers() {
+        return {
+            Authorization: `Bearer ${this.token}`,
+            "Content-Type": "application/json",
+        };
+    }
+    async pull(vault, since) {
+        const url = new URL(`${this.apiUrl}/api/sync/pull`);
+        url.searchParams.set("vault", vault);
+        if (since)
+            url.searchParams.set("since", since);
+        const res = await fetch(url, { headers: this.headers() });
+        if (!res.ok) {
+            throw new Error(`pull failed: ${res.status} ${await res.text()}`);
+        }
+        return res.json();
+    }
+    /** Loop pull until has_more=false, merging pages. */
+    async pullAll(vault, since) {
+        const merged = await this.pull(vault, since);
+        while (merged.has_more && merged.next_cursor) {
+            const next = await this.pull(vault, merged.next_cursor);
+            merged.docs.push(...next.docs);
+            merged.deleted.push(...next.deleted);
+            merged.next_cursor = next.next_cursor;
+            merged.has_more = next.has_more;
+        }
+        return merged;
+    }
+    async push(args) {
+        const res = await fetch(`${this.apiUrl}/api/sync/push`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(args),
+        });
+        return { status: res.status, data: (await res.json()) };
+    }
+    async status() {
+        const res = await fetch(`${this.apiUrl}/api/sync/status`, {
+            headers: this.headers(),
+        });
+        if (!res.ok) {
+            throw new Error(`status failed: ${res.status} ${await res.text()}`);
+        }
+        return res.json();
+    }
+}

package/dist/sync/conflict.js

@@ -0,0 +1,15 @@
+import matter from "gray-matter";
+/**
+ * Build a three-way merge file: server frontmatter (always wins for
+ * authoritative keys), then a conflict-marked body section. The user
+ * (or their agent) edits to remove markers, then runs `unfairly resolve`.
+ */
+export function buildConflictFile(args) {
+    const conflictBody = `<<<<<<< local
+${args.localBody}
+=======
+${args.serverBody}
+>>>>>>> cloud (updated_at ${args.serverUpdatedAt})
+`;
+    return matter.stringify(conflictBody, args.serverFrontmatter);
+}

package/dist/sync/credentials.js

@@ -0,0 +1,50 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const SERVICE = "unfairly";
+const ACCOUNT = "default";
+const FILE_FALLBACK = path.join(os.homedir(), ".unfairly", "credentials");
+/**
+ * Try OS keychain via keytar; if unavailable (Linux without libsecret, CI,
+ * etc.), fall back to a 0600 file in ~/.unfairly/credentials.
+ */
+export async function getToken() {
+    try {
+        const keytar = (await import("keytar")).default;
+        const t = await keytar.getPassword(SERVICE, ACCOUNT);
+        if (t)
+            return t;
+    }
+    catch {
+        // keytar unavailable; fall through
+    }
+    try {
+        return (await fs.readFile(FILE_FALLBACK, "utf8")).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export async function setToken(token) {
+    try {
+        const keytar = (await import("keytar")).default;
+        await keytar.setPassword(SERVICE, ACCOUNT, token);
+        return;
+    }
+    catch {
+        // fall through
+    }
+    await fs.mkdir(path.dirname(FILE_FALLBACK), { recursive: true });
+    await fs.writeFile(FILE_FALLBACK, token, { mode: 0o600 });
+}
+export async function clearToken() {
+    try {
+        const keytar = (await import("keytar")).default;
+        await keytar.deletePassword(SERVICE, ACCOUNT);
+    }
+    catch { }
+    try {
+        await fs.unlink(FILE_FALLBACK);
+    }
+    catch { }
+}

package/dist/sync/files.js

@@ -0,0 +1,70 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import matter from "gray-matter";
+/**
+ * Sha of the canonical rendered file content. Pass the full markdown
+ * (frontmatter + body, as written to disk). Trailing whitespace is
+ * normalized so write→read round-trips don't trip false-dirty.
+ */
+export function computeSha(rendered) {
+    const h = crypto.createHash("sha256");
+    h.update(rendered.replace(/\s+$/, ""));
+    return h.digest("hex").slice(0, 16);
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9-]/g, "");
+}
+/** Build a relative path for a doc within a vault directory. */
+export function docPath(vaultSlug, sectionName, slug) {
+    const section = slugify(sectionName ?? "_root");
+    return path.join(vaultSlug, section, `${slug}.md`);
+}
+/**
+ * Build the markdown file content for a server-side doc. The caller
+ * substitutes the vaultSlug into `path` after this returns; we leave it
+ * generic so the same builder works for both tracked and cached vault
+ * roots.
+ */
+export function buildFileFromServer(doc, vaultRoot) {
+    const fm = {
+        unfairly_id: doc.id,
+        slug: doc.slug,
+        name: doc.name,
+        section: doc.sections?.name ?? null,
+        trust_tier: doc.trust_tier,
+        role: doc.role,
+        source_url: doc.source_url,
+        source_type: doc.source_type ?? "markdown",
+        updated_at: doc.updated_at,
+    };
+    const body = doc.markdown_content ?? "";
+    const content = matter.stringify(body, fm);
+    return {
+        path: docPath(vaultRoot, doc.sections?.name ?? null, doc.slug),
+        content,
+        sha: computeSha(content),
+    };
+}
+/** Read the raw file content (frontmatter + body, no parsing). */
+export async function readDocRaw(absPath) {
+    return fs.readFile(absPath, "utf8");
+}
+export async function readDocFile(absPath) {
+    const raw = await fs.readFile(absPath, "utf8");
+    const parsed = matter(raw);
+    return {
+        frontmatter: parsed.data,
+        body: parsed.content,
+    };
+}
+/** Atomic write (tmp + rename). */
+export async function writeDocFile(absPath, content) {
+    const tmp = `${absPath}.tmp.${process.pid}`;
+    await fs.mkdir(path.dirname(absPath), { recursive: true });
+    await fs.writeFile(tmp, content, "utf8");
+    await fs.rename(tmp, absPath);
+}

package/dist/sync/manifest.js

@@ -0,0 +1,36 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const MANIFEST_FILE = "manifest.json";
+export function manifestPath(rootDir) {
+    return path.join(rootDir, ".unfairly", MANIFEST_FILE);
+}
+export async function readManifest(rootDir) {
+    try {
+        const raw = await fs.readFile(manifestPath(rootDir), "utf8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/**
+ * Atomic write: tmp file → fsync → rename. Rename is atomic on POSIX,
+ * preventing a half-written manifest if the process is killed mid-write.
+ */
+export async function writeManifest(rootDir, m) {
+    const target = manifestPath(rootDir);
+    const tmp = `${target}.tmp.${process.pid}`;
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(tmp, JSON.stringify(m, null, 2), "utf8");
+    await fs.rename(tmp, target);
+}
+export function emptyManifest(apiUrl) {
+    return {
+        version: 1,
+        api_url: apiUrl,
+        vaults: {},
+        generated_at: new Date().toISOString(),
+    };
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "unfairly",
+  "version": "0.1.0",
+  "description": "CLI + stdio MCP for syncing Unfairly vaults to local markdown — the multiplayer context layer for AI agents",
+  "keywords": ["unfairly", "mcp", "ai", "context", "agents", "knowledge-base", "claude", "codex"],
+  "homepage": "https://unfairly.ai",
+  "repository": { "type": "git", "url": "git+https://github.com/Unfairly-AI/unfairly-app.git", "directory": "cli" },
+  "bugs": { "url": "https://github.com/Unfairly-AI/unfairly-app/issues" },
+  "license": "MIT",
+  "author": "Unfairly <bob@hq.unfairly.ai>",
+  "bin": { "unfairly": "dist/index.js" },
+  "type": "module",
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "chokidar": "^4.0.1",
+    "gray-matter": "^4.0.3",
+    "keytar": "^7.9.0",
+    "yargs": "^17.7.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/yargs": "^17.0.33",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": { "node": ">=20" },
+  "files": ["dist", "README.md"]
+}