@knowalabs/knowa 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @knowalabs/knowa
+
+Sync your team's AI context — agents, commands, skills, rules, and docs — from
+[Knowa](https://knowalabs.com) into the folders your AI tools actually read:
+
+- `.claude/agents/`, `.claude/commands/`, `.claude/skills/` and a managed
+  team-rules block in `CLAUDE.md` (Claude Code)
+- `.cursor/rules/knowa/`, `.cursor/commands/` (Cursor)
+- `.knowa/docs/` (your team's docs as Markdown, for any tool)
+
+Edit an agent in Knowa once; every teammate's repo picks it up on the next
+`knowa pull` (or automatically under `knowa watch`).
+
+## Quick start
+
+```sh
+npm install -g @knowalabs/knowa
+knowa init     # link this repo to a Knowa space (asks for an API key)
+knowa pull     # materialize the folders
+knowa watch    # keep them in sync while you work
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `knowa init` | Link the repo to a space; store your API key outside the repo |
+| `knowa pull [--force] [--dry-run]` | Sync down. Never overwrites files you changed or created — conflicts are reported instead (exit code 2) |
+| `knowa watch [--interval N]` | Poll for team changes (default 30s) and pull them |
+| `knowa status [--porcelain]` | Show local edits and upstream changes |
+| `knowa push [path…] [--org]` | Publish local asset edits back to Knowa; offers to adopt new untracked files in managed folders |
+
+## How syncing stays safe
+
+- `knowa.json` (committed) holds the repo↔space link; your API key lives in
+  `KNOWA_API_KEY` or `~/.config/knowa/credentials.json` — never in the repo.
+- `.knowa/state.json` (git-ignored) records what Knowa wrote. The CLI only
+  ever touches files it owns; anything you created or edited is left alone.
+- Pushes are guarded by content hashes: if a teammate edited the same asset
+  since your last sync, you get a conflict instead of a silent overwrite.
+- In `CLAUDE.md`, only the block between `<!-- knowa:begin -->` and
+  `<!-- knowa:end -->` is managed; the rest of the file is yours.
+
+Requires Node 18+. Mint API keys in Knowa under **Settings → Organization →
+API keys** (enable *write access* if you want `knowa push`).

package/dist/adapters/claude-md.js

@@ -0,0 +1,72 @@
+/**
+ * Managed rules block inside CLAUDE.md — the ONLY user-owned file Knowa
+ * touches, so editing is deliberately paranoid:
+ *
+ * - Only the region between the begin/end markers is ever rewritten.
+ * - Missing both markers → the block is appended (or the file created).
+ * - Exactly one begin AND one end marker, in order → rewrite between them.
+ * - Anything else (one marker missing, duplicated, out of order) → refuse
+ *   with an error instead of guessing. The user repairs the markers by hand.
+ */
+export const BEGIN_MARKER = "<!-- knowa:begin — managed by `knowa pull`, do not edit inside this block -->";
+export const END_MARKER = "<!-- knowa:end -->";
+/** Marker-only matching (any text after "knowa:begin" is tolerated). */
+const BEGIN_RE = /<!--\s*knowa:begin[^>]*-->/g;
+const END_RE = /<!--\s*knowa:end\s*-->/g;
+/** Render the block's inner content (between the markers). */
+export function renderRulesBlock(rules) {
+    if (rules.length === 0)
+        return "";
+    const sections = rules.map((r) => `## ${r.name}${r.scope === "org" ? "" : " (this project)"}\n\n${r.body.trim()}`);
+    return `# Team rules (synced from Knowa)\n\n${sections.join("\n\n")}`;
+}
+/**
+ * Insert or replace the managed block in a CLAUDE.md's content. `existing`
+ * is null when the file doesn't exist yet. An empty `block` removes the
+ * managed region (leaving user content untouched).
+ */
+export function applyRulesBlock(existing, block) {
+    const wrapped = block === "" ? "" : `${BEGIN_MARKER}\n\n${block}\n\n${END_MARKER}`;
+    if (existing === null) {
+        if (wrapped === "")
+            return { ok: true, content: "", changed: false };
+        return { ok: true, content: wrapped + "\n", changed: true };
+    }
+    const begins = [...existing.matchAll(BEGIN_RE)];
+    const ends = [...existing.matchAll(END_RE)];
+    if (begins.length === 0 && ends.length === 0) {
+        if (wrapped === "")
+            return { ok: true, content: existing, changed: false };
+        const sep = existing === "" ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+        return { ok: true, content: existing + sep + wrapped + "\n", changed: true };
+    }
+    if (begins.length !== 1 || ends.length !== 1) {
+        return {
+            ok: false,
+            error: "CLAUDE.md has duplicated knowa markers — expected exactly one knowa:begin and one knowa:end. Fix the markers (or delete the whole block) and re-run.",
+        };
+    }
+    const begin = begins[0];
+    const end = ends[0];
+    const beginStart = begin.index;
+    const endStop = end.index + end[0].length;
+    if (endStop < beginStart + begin[0].length) {
+        return {
+            ok: false,
+            error: "CLAUDE.md has knowa:end before knowa:begin. Fix the markers (or delete the whole block) and re-run.",
+        };
+    }
+    let replacement = wrapped;
+    let before = existing.slice(0, beginStart);
+    let after = existing.slice(endStop);
+    if (wrapped === "") {
+        // Removing the block: also collapse the blank lines that framed it.
+        before = before.replace(/\n+$/, before.trim() === "" ? "" : "\n");
+        after = after.replace(/^\n+/, "\n");
+        if (before === "")
+            after = after.replace(/^\n+/, "");
+        replacement = "";
+    }
+    const content = before + replacement + after;
+    return { ok: true, content, changed: content !== existing };
+}

package/dist/adapters/index.js

@@ -0,0 +1,89 @@
+/** Claude Code folder conventions. RULEs go to CLAUDE.md via claude-md.ts. */
+const claude = {
+    target: "claude",
+    mapAsset(asset) {
+        switch (asset.type) {
+            case "AGENT":
+                return `.claude/agents/${asset.slug}.md`;
+            case "COMMAND":
+                return `.claude/commands/${asset.slug}.md`;
+            case "SKILL":
+                return `.claude/skills/${asset.slug}/SKILL.md`;
+            case "RULE":
+                return null;
+        }
+    },
+};
+/**
+ * Cursor conventions. Rules live under a knowa/ subdirectory so tombstone
+ * deletion never has to touch user-authored rules. Cursor has no agent/skill
+ * equivalent — those are skipped.
+ */
+const cursor = {
+    target: "cursor",
+    mapAsset(asset) {
+        switch (asset.type) {
+            case "RULE":
+                return `.cursor/rules/knowa/${asset.slug}.mdc`;
+            case "COMMAND":
+                return `.cursor/commands/${asset.slug}.md`;
+            default:
+                return null;
+        }
+    },
+};
+const docs = {
+    target: "docs",
+    mapDoc(doc) {
+        return `.knowa/docs/${doc.path}`;
+    },
+};
+const ADAPTERS = { claude, cursor, docs };
+/**
+ * Manifest → the complete list of files the linked repo should contain.
+ * Space-scoped assets shadow org-global ones with the same (type, slug):
+ * the shadowed asset produces no files at all (both would map to the same
+ * path).
+ */
+export function desiredFiles(manifest, targets) {
+    const shadowed = new Set(manifest.assets.filter((a) => a.shadows && !a.deletedAt).map((a) => a.shadows));
+    const files = [];
+    const seen = new Set();
+    for (const target of targets) {
+        const adapter = ADAPTERS[target];
+        if (adapter.mapAsset) {
+            for (const asset of manifest.assets) {
+                if (shadowed.has(asset.id))
+                    continue;
+                const path = adapter.mapAsset(asset);
+                if (!path || seen.has(path))
+                    continue;
+                seen.add(path);
+                files.push({
+                    path,
+                    kind: "asset",
+                    id: asset.id,
+                    remoteHash: asset.hash,
+                    deleted: asset.deletedAt !== null,
+                });
+            }
+        }
+        if (adapter.mapDoc) {
+            for (const doc of manifest.docs) {
+                const path = adapter.mapDoc(doc);
+                if (!path || seen.has(path))
+                    continue;
+                seen.add(path);
+                files.push({ path, kind: "doc", id: doc.id, remoteHash: doc.hash, deleted: false });
+            }
+        }
+    }
+    return files;
+}
+/** The live RULE assets that make up the managed CLAUDE.md block, org rules first. */
+export function claudeRules(manifest) {
+    const shadowed = new Set(manifest.assets.filter((a) => a.shadows && !a.deletedAt).map((a) => a.shadows));
+    return manifest.assets
+        .filter((a) => a.type === "RULE" && !a.deletedAt && !shadowed.has(a.id))
+        .sort((a, b) => a.scope === b.scope ? a.slug.localeCompare(b.slug) : a.scope === "org" ? -1 : 1);
+}

package/dist/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/api.js

@@ -0,0 +1,87 @@
+/** Typed client for the Knowa context API (see src/app/api/v1/context). */
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}
+export class KnowaClient {
+    url;
+    apiKey;
+    constructor(url, apiKey) {
+        this.url = url;
+        this.apiKey = apiKey;
+    }
+    async request(path, init) {
+        const res = await fetch(`${this.url}${path}`, {
+            ...init,
+            headers: {
+                authorization: `Bearer ${this.apiKey}`,
+                ...(init?.body ? { "content-type": "application/json" } : {}),
+                ...(init?.etag ? { "if-none-match": init.etag } : {}),
+                ...init?.headers,
+            },
+        });
+        if (!res.ok && res.status !== 304) {
+            let body;
+            let message = `${res.status} ${res.statusText}`;
+            try {
+                body = await res.json();
+                const err = body;
+                if (err.message)
+                    message = err.message;
+                else if (err.error)
+                    message = err.error;
+            }
+            catch {
+                // Non-JSON error body — keep the status line.
+            }
+            throw new ApiError(res.status, message, body);
+        }
+        return res;
+    }
+    /** List spaces the key can read — also serves as key validation for init. */
+    async spaces() {
+        const res = await this.request("/api/v1/spaces");
+        const body = (await res.json());
+        return body.spaces;
+    }
+    /** Manifest, or null when the stored ETag still matches (nothing changed). */
+    async manifest(space, etag) {
+        const res = await this.request(`/api/v1/context/manifest?space=${encodeURIComponent(space)}`, {
+            etag,
+        });
+        if (res.status === 304)
+            return null;
+        return {
+            manifest: (await res.json()),
+            etag: res.headers.get("etag") ?? "",
+        };
+    }
+    async assets(space, ids) {
+        const res = await this.request(`/api/v1/context/assets?space=${encodeURIComponent(space)}&ids=${ids.map(encodeURIComponent).join(",")}`);
+        const body = (await res.json());
+        return body.assets;
+    }
+    async docMarkdown(pageId) {
+        const res = await this.request(`/api/v1/pages/${encodeURIComponent(pageId)}?format=md`);
+        return res.text();
+    }
+    async pushUpdate(id, baseHash, content) {
+        const res = await this.request(`/api/v1/context/assets/${encodeURIComponent(id)}`, {
+            method: "PUT",
+            body: JSON.stringify({ baseHash, content }),
+        });
+        return (await res.json());
+    }
+    async pushCreate(input) {
+        const res = await this.request(`/api/v1/context/assets`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+        return (await res.json());
+    }
+}

package/dist/commands/init.js

@@ -0,0 +1,57 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { KnowaClient } from "../api.js";
+import { ALL_TARGETS, CONFIG_FILENAME, DEFAULT_URL, resolveApiKey, storeApiKey, writeRepoConfig, } from "../config.js";
+/**
+ * Link this repo to a Knowa space: validate a key, pick a space, write
+ * knowa.json (committed) + per-user credentials, and prepare .knowa/.
+ */
+export async function runInit() {
+    const root = process.cwd();
+    if (existsSync(join(root, CONFIG_FILENAME))) {
+        console.log(`${CONFIG_FILENAME} already exists here — this repo is already linked.`);
+        console.log("Edit it directly, or delete it and re-run `knowa init`.");
+        return;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const urlInput = (await rl.question(`Knowa URL [${DEFAULT_URL}]: `)).trim();
+        const url = (urlInput || DEFAULT_URL).replace(/\/+$/, "");
+        let apiKey = resolveApiKey(url);
+        if (apiKey) {
+            console.log("Using the API key from your environment/credentials.");
+        }
+        else {
+            apiKey = (await rl.question("API key (mint one at Settings → Organization → API keys): ")).trim();
+            if (!apiKey.startsWith("knowa_sk_")) {
+                throw new Error("That doesn't look like a Knowa key (expected knowa_sk_…).");
+            }
+        }
+        const client = new KnowaClient(url, apiKey);
+        const spaces = await client.spaces();
+        if (spaces.length === 0) {
+            throw new Error("This key can't see any spaces. Create a space in Knowa first.");
+        }
+        console.log("\nWhich space is this repository's project?");
+        spaces.forEach((s, i) => console.log(`  ${i + 1}. ${s.name} (${s.key})`));
+        const answer = (await rl.question(`Space [1-${spaces.length}]: `)).trim();
+        const index = Number(answer) - 1;
+        const space = spaces[index];
+        if (!space)
+            throw new Error("Invalid selection.");
+        writeRepoConfig(root, { url, space: space.key, targets: [...ALL_TARGETS] });
+        storeApiKey(url, apiKey);
+        mkdirSync(join(root, ".knowa"), { recursive: true });
+        writeFileSync(join(root, ".knowa", ".gitignore"), "state.json\n");
+        console.log(`\nLinked to "${space.name}".`);
+        console.log(`- ${CONFIG_FILENAME} written — commit it so teammates share the link.`);
+        console.log("- Your API key is stored in ~/.config/knowa/credentials.json (never in the repo).");
+        console.log("- Synced outputs (.claude/, .cursor/, .knowa/docs/) are safe to commit;");
+        console.log("  .knowa/state.json is per-checkout and already git-ignored.");
+        console.log("\nNext: `knowa pull`");
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/commands/pull.js

@@ -0,0 +1,146 @@
+import { claudeRules, desiredFiles } from "../adapters/index.js";
+import { applyRulesBlock, renderRulesBlock } from "../adapters/claude-md.js";
+import { bodyOf } from "../context.js";
+import { deleteFileAndPrune, diskSnapshot, readFileOrNull, writeFileAtomic } from "../fsops.js";
+import { sha256 } from "../hash.js";
+import { planSync } from "../sync.js";
+import { readState, writeState } from "../state.js";
+const ASSET_BATCH = 50;
+const DOC_CONCURRENCY = 5;
+async function fetchAssets(ctx, ids) {
+    const byId = new Map();
+    for (let i = 0; i < ids.length; i += ASSET_BATCH) {
+        const batch = await ctx.client.assets(ctx.config.space, ids.slice(i, i + ASSET_BATCH));
+        for (const asset of batch)
+            byId.set(asset.id, asset);
+    }
+    return byId;
+}
+async function fetchDocs(ctx, ids) {
+    const byId = new Map();
+    for (let i = 0; i < ids.length; i += DOC_CONCURRENCY) {
+        const batch = ids.slice(i, i + DOC_CONCURRENCY);
+        const bodies = await Promise.all(batch.map((id) => ctx.client.docMarkdown(id)));
+        batch.forEach((id, idx) => byId.set(id, bodies[idx]));
+    }
+    return byId;
+}
+export async function runPull(ctx, opts = {}) {
+    const log = (msg) => {
+        if (!opts.quiet)
+            console.log(msg);
+    };
+    const state = readState(ctx.root);
+    const result = await ctx.client.manifest(ctx.config.space);
+    if (!result)
+        throw new Error("Unexpected 304 for an unconditional manifest request");
+    const { manifest, etag } = result;
+    const desired = desiredFiles(manifest, ctx.config.targets);
+    const plan = planSync(desired, state.files, diskSnapshot(ctx.root));
+    const conflicts = [];
+    const writes = [];
+    for (const action of plan.actions) {
+        if (action.op === "conflict-modified" || action.op === "conflict-untracked") {
+            if (opts.force) {
+                writes.push({ op: action.op === "conflict-untracked" ? "create" : "update", file: action.file });
+            }
+            else {
+                conflicts.push(action.path);
+                const why = action.op === "conflict-modified"
+                    ? "locally modified — pull skipped it (use --force to overwrite, or `knowa push` to publish your edit)"
+                    : "an untracked file already exists there — pull will never clobber it (use --force to adopt)";
+                log(`conflict  ${action.path}  (${why})`);
+            }
+        }
+        else {
+            writes.push(action);
+        }
+    }
+    const assetIds = new Set();
+    const docIds = new Set();
+    for (const action of writes) {
+        if (action.op === "create" || action.op === "update") {
+            (action.file.kind === "asset" ? assetIds : docIds).add(action.file.id);
+        }
+    }
+    // Rules render into CLAUDE.md — their bodies ride along in the same bulk fetch.
+    const rules = ctx.config.targets.includes("claude") ? claudeRules(manifest) : [];
+    for (const rule of rules)
+        assetIds.add(rule.id);
+    const [assetById, docById] = await Promise.all([
+        fetchAssets(ctx, [...assetIds]),
+        fetchDocs(ctx, [...docIds]),
+    ]);
+    // Next state: start from entries that carry forward (unchanged + still-conflicted).
+    const nextFiles = {};
+    for (const path of plan.unchanged)
+        nextFiles[path] = state.files[path];
+    for (const path of conflicts) {
+        if (state.files[path])
+            nextFiles[path] = state.files[path];
+    }
+    let applied = 0;
+    for (const action of writes) {
+        switch (action.op) {
+            case "create":
+            case "update": {
+                const { file } = action;
+                const content = file.kind === "asset" ? assetById.get(file.id)?.content : docById.get(file.id);
+                if (content === undefined) {
+                    // Raced with a server-side delete between manifest and fetch — skip;
+                    // the next pull's manifest will carry the tombstone.
+                    continue;
+                }
+                if (!opts.dryRun)
+                    writeFileAtomic(ctx.root, file.path, content);
+                nextFiles[file.path] = {
+                    kind: file.kind,
+                    id: file.id,
+                    remoteHash: file.remoteHash,
+                    fileHash: sha256(content),
+                    ...(file.kind === "asset" ? { version: assetById.get(file.id)?.version } : {}),
+                };
+                applied++;
+                log(`${action.op === "create" ? "created " : "updated "} ${file.path}`);
+                break;
+            }
+            case "delete":
+                if (!opts.dryRun)
+                    deleteFileAndPrune(ctx.root, action.path);
+                applied++;
+                log(`deleted   ${action.path}`);
+                break;
+            case "orphan":
+                log(`orphaned  ${action.path}  (deleted upstream but locally modified — keeping your copy, no longer managed)`);
+                break;
+        }
+    }
+    const nextState = { files: nextFiles, claudeMd: state.claudeMd, etag };
+    // Managed CLAUDE.md rules block (claude target only).
+    if (ctx.config.targets.includes("claude")) {
+        const block = renderRulesBlock(rules.map((rule) => ({
+            name: rule.name,
+            scope: rule.scope,
+            body: bodyOf(assetById.get(rule.id)?.content ?? ""),
+        })));
+        const existing = readFileOrNull(ctx.root, "CLAUDE.md");
+        const applyResult = applyRulesBlock(existing, block);
+        if (!applyResult.ok) {
+            conflicts.push("CLAUDE.md");
+            log(`conflict  CLAUDE.md  (${applyResult.error})`);
+        }
+        else if (applyResult.changed) {
+            if (!opts.dryRun)
+                writeFileAtomic(ctx.root, "CLAUDE.md", applyResult.content);
+            applied++;
+            log(`updated   CLAUDE.md  (team rules block)`);
+        }
+        nextState.claudeMd = { blockHash: sha256(block), assetIds: rules.map((r) => r.id) };
+    }
+    if (!opts.dryRun)
+        writeState(ctx.root, nextState);
+    log(applied === 0 && conflicts.length === 0
+        ? "Already up to date."
+        : `Done: ${applied} file${applied === 1 ? "" : "s"} synced${conflicts.length ? `, ${conflicts.length} conflict${conflicts.length === 1 ? "" : "s"} skipped` : ""}.`);
+    return { applied, conflicts, etag };
+}

package/dist/commands/push.js

@@ -0,0 +1,157 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { ApiError } from "../api.js";
+import { loadContext } from "../context.js";
+import { sha256 } from "../hash.js";
+import { readState, writeState } from "../state.js";
+/**
+ * Untracked files inside the folders Knowa manages can be adopted as new
+ * assets — the path infers the type, the filename the slug.
+ */
+function inferAsset(path) {
+    let m = /^\.claude\/agents\/([a-z0-9][a-z0-9-]*)\.md$/.exec(path);
+    if (m)
+        return { type: "AGENT", slug: m[1] };
+    m = /^\.claude\/commands\/([a-z0-9][a-z0-9-]*)\.md$/.exec(path);
+    if (m)
+        return { type: "COMMAND", slug: m[1] };
+    m = /^\.claude\/skills\/([a-z0-9][a-z0-9-]*)\/SKILL\.md$/.exec(path);
+    if (m)
+        return { type: "SKILL", slug: m[1] };
+    m = /^\.cursor\/rules\/knowa\/([a-z0-9][a-z0-9-]*)\.mdc$/.exec(path);
+    if (m)
+        return { type: "RULE", slug: m[1] };
+    return null;
+}
+function* managedDirFiles(root) {
+    const dirs = [".claude/agents", ".claude/commands", ".cursor/rules/knowa", ".cursor/commands"];
+    for (const dir of dirs) {
+        if (!existsSync(join(root, dir)))
+            continue;
+        for (const name of readdirSync(join(root, dir))) {
+            if (name.endsWith(".md") || name.endsWith(".mdc"))
+                yield `${dir}/${name}`;
+        }
+    }
+    const skills = join(root, ".claude/skills");
+    if (existsSync(skills)) {
+        for (const slug of readdirSync(skills)) {
+            const skillFile = `.claude/skills/${slug}/SKILL.md`;
+            if (existsSync(join(root, skillFile)))
+                yield skillFile;
+        }
+    }
+}
+/** Ensure pushed content parses server-side: minimal frontmatter if missing. */
+function withFrontmatter(content, slug) {
+    return content.startsWith("---\n") ? content : `---\nname: ${slug}\n---\n\n${content}`;
+}
+export async function runPush(paths, opts = {}) {
+    const ctx = loadContext();
+    const state = readState(ctx.root);
+    const wanted = paths.length > 0 ? new Set(paths.map((p) => p.replace(/^\.\//, ""))) : null;
+    let failures = 0;
+    // 1. Tracked asset files with local edits → PUT with the 3-way base hash.
+    for (const [path, entry] of Object.entries(state.files)) {
+        if (wanted && !wanted.has(path))
+            continue;
+        if (entry.kind === "doc") {
+            if (wanted) {
+                console.log(`skip      ${path}  (docs are pull-only — edit them in the Knowa web app)`);
+            }
+            continue;
+        }
+        const abs = join(ctx.root, path);
+        if (!existsSync(abs))
+            continue;
+        const content = readFileSync(abs, "utf8");
+        if (sha256(content) === entry.fileHash)
+            continue;
+        try {
+            const res = await ctx.client.pushUpdate(entry.id, entry.remoteHash, content);
+            state.files[path] = { ...entry, remoteHash: res.hash, fileHash: sha256(content), version: res.version };
+            console.log(`pushed    ${path}  (now v${res.version})`);
+        }
+        catch (err) {
+            failures++;
+            if (err instanceof ApiError && err.status === 409) {
+                console.error(`conflict  ${path}  — remote changed since your last sync. Run \`knowa pull\`, resolve, then push again.`);
+            }
+            else if (err instanceof ApiError && err.status === 403) {
+                console.error(`denied    ${path}  — ${err.message}`);
+            }
+            else if (err instanceof ApiError && err.status === 422) {
+                console.error(`invalid   ${path}  — ${err.message}`);
+            }
+            else {
+                console.error(`error     ${path}  — ${err.message}`);
+            }
+        }
+    }
+    // 2. CLAUDE.md rules-block edits can't round-trip to individual rule assets.
+    if (state.claudeMd && existsSync(join(ctx.root, "CLAUDE.md"))) {
+        // Block extraction is fuzzy on hand-edited files; a cheap full-file check
+        // is enough to warn — the authoritative editor for rules is the web UI.
+        const wantsClaudeMd = !wanted || wanted.has("CLAUDE.md");
+        if (wantsClaudeMd && wanted) {
+            console.log("skip      CLAUDE.md  (team rules are edited in the Knowa web app, not pushed)");
+        }
+    }
+    // 3. Untracked files in managed folders → offer to create.
+    const untracked = [];
+    for (const path of managedDirFiles(ctx.root)) {
+        if (state.files[path])
+            continue;
+        if (wanted && !wanted.has(path))
+            continue;
+        const inferred = inferAsset(path);
+        if (inferred)
+            untracked.push({ path, ...inferred });
+    }
+    if (untracked.length > 0) {
+        const scope = opts.org ? "org" : "space";
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            for (const item of untracked) {
+                const answer = (await rl.question(`Publish untracked ${item.path} as a new ${scope === "org" ? "org-global" : "project"} ${item.type.toLowerCase()} "${item.slug}"? [y/N] `))
+                    .trim()
+                    .toLowerCase();
+                if (answer !== "y" && answer !== "yes")
+                    continue;
+                const content = withFrontmatter(readFileSync(join(ctx.root, item.path), "utf8"), item.slug);
+                try {
+                    const res = await ctx.client.pushCreate({
+                        space: ctx.config.space,
+                        type: item.type,
+                        scope,
+                        slug: item.slug,
+                        content,
+                    });
+                    state.files[item.path] = {
+                        kind: "asset",
+                        id: res.id,
+                        remoteHash: res.hash,
+                        fileHash: sha256(readFileSync(join(ctx.root, item.path), "utf8")),
+                        version: res.version,
+                    };
+                    console.log(`created   ${item.path}  → ${item.slug} (v1)`);
+                }
+                catch (err) {
+                    failures++;
+                    if (err instanceof ApiError && err.status === 409) {
+                        console.error(`conflict  ${item.path}  — slug "${item.slug}" already exists. Run \`knowa pull\` first.`);
+                    }
+                    else {
+                        console.error(`error     ${item.path}  — ${err.message}`);
+                    }
+                }
+            }
+        }
+        finally {
+            rl.close();
+        }
+    }
+    writeState(ctx.root, state);
+    return failures > 0 ? 1 : 0;
+}

package/dist/commands/status.js

@@ -0,0 +1,68 @@
+import { desiredFiles } from "../adapters/index.js";
+import { loadContext } from "../context.js";
+import { diskSnapshot } from "../fsops.js";
+import { planSync } from "../sync.js";
+import { readState } from "../state.js";
+/**
+ * What would `pull` and `push` do? Local view first (works offline in
+ * spirit; the manifest fetch adds the upstream view). `--porcelain` prints
+ * one `<state>\t<path>` line per finding for CI.
+ */
+export async function runStatus(porcelain = false) {
+    const ctx = loadContext();
+    const state = readState(ctx.root);
+    const disk = diskSnapshot(ctx.root);
+    const lines = [];
+    for (const [path, entry] of Object.entries(state.files)) {
+        const diskHash = disk.hashOf(path);
+        if (diskHash === null)
+            lines.push(["missing", path]);
+        else if (diskHash !== entry.fileHash)
+            lines.push(["modified", path]);
+    }
+    const result = await ctx.client.manifest(ctx.config.space);
+    if (result) {
+        const plan = planSync(desiredFiles(result.manifest, ctx.config.targets), state.files, disk);
+        for (const action of plan.actions) {
+            switch (action.op) {
+                case "create":
+                    lines.push(["new-upstream", action.file.path]);
+                    break;
+                case "update":
+                    lines.push(["outdated", action.file.path]);
+                    break;
+                case "delete":
+                    lines.push(["deleted-upstream", action.path]);
+                    break;
+                case "conflict-modified":
+                case "conflict-untracked":
+                    lines.push(["conflict", action.path]);
+                    break;
+                case "orphan":
+                    lines.push(["orphaned", action.path]);
+                    break;
+            }
+        }
+    }
+    if (porcelain) {
+        for (const [kind, path] of lines)
+            console.log(`${kind}\t${path}`);
+    }
+    else if (lines.length === 0) {
+        console.log("Up to date — local files match the last sync and nothing changed upstream.");
+    }
+    else {
+        const label = {
+            missing: "missing locally (pull restores)",
+            modified: "modified locally (push publishes, pull skips)",
+            "new-upstream": "new upstream (pull creates)",
+            outdated: "changed upstream (pull updates)",
+            "deleted-upstream": "deleted upstream (pull removes)",
+            conflict: "conflict (see `knowa pull` output)",
+            orphaned: "deleted upstream but modified locally",
+        };
+        for (const [kind, path] of lines)
+            console.log(`${kind.padEnd(17)} ${path}  — ${label[kind]}`);
+    }
+    return lines.some(([kind]) => kind === "conflict") ? 2 : 0;
+}

package/dist/commands/watch.js

@@ -0,0 +1,39 @@
+import { loadContext } from "../context.js";
+import { readState } from "../state.js";
+import { runPull } from "./pull.js";
+const DEFAULT_INTERVAL_S = 30;
+const MAX_BACKOFF_S = 300;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll the manifest and pull on change. A quiet poll is one conditional GET
+ * answered 304 — no body, no writes. Never pushes. Network errors back off
+ * exponentially and recover on their own.
+ */
+export async function runWatch(intervalArg) {
+    const interval = Math.max(5, Number(intervalArg) || DEFAULT_INTERVAL_S);
+    const ctx = loadContext();
+    console.log(`Watching "${ctx.config.space}" on ${ctx.config.url} every ~${interval}s. Ctrl-C to stop.`);
+    // First sync immediately so a fresh clone materializes without waiting.
+    let backoff = interval;
+    for (;;) {
+        try {
+            const etag = readState(ctx.root).etag;
+            const changed = etag
+                ? (await ctx.client.manifest(ctx.config.space, etag)) !== null
+                : true;
+            if (changed) {
+                const { conflicts } = await runPull(ctx);
+                if (conflicts.length > 0) {
+                    console.log("(conflicted paths stay untouched until resolved or --force pulled)");
+                }
+            }
+            backoff = interval;
+        }
+        catch (err) {
+            console.error(`watch: ${err.message} — retrying in ${backoff}s`);
+            backoff = Math.min(backoff * 2, MAX_BACKOFF_S);
+        }
+        // ±20% jitter so a team's watchers don't thundering-herd the manifest.
+        await sleep(backoff * 1000 * (0.8 + Math.random() * 0.4));
+    }
+}

package/dist/config.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Two config layers:
+ *
+ * - `knowa.json` at the repo root — the team's repo↔space link, COMMITTED.
+ *   Never holds credentials.
+ * - The API key — `KNOWA_API_KEY` env var, falling back to
+ *   `~/.config/knowa/credentials.json` (`{ "<url>": "knowa_sk_…" }`, 0600),
+ *   written by `knowa init`. Per-user, never in the repo.
+ */
+export const CONFIG_FILENAME = "knowa.json";
+export const DEFAULT_URL = "https://app.knowalabs.com";
+export const ALL_TARGETS = ["claude", "cursor", "docs"];
+/** Walk up from cwd to the nearest directory containing knowa.json. */
+export function findRepoRoot(from = process.cwd()) {
+    let dir = from;
+    for (;;) {
+        if (existsSync(join(dir, CONFIG_FILENAME)))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function readRepoConfig(root) {
+    const raw = JSON.parse(readFileSync(join(root, CONFIG_FILENAME), "utf8"));
+    if (typeof raw.space !== "string" || raw.space === "") {
+        throw new Error(`${CONFIG_FILENAME} is missing "space"`);
+    }
+    const targets = Array.isArray(raw.targets)
+        ? raw.targets.filter((t) => ALL_TARGETS.includes(t))
+        : [...ALL_TARGETS];
+    return {
+        url: typeof raw.url === "string" && raw.url !== "" ? raw.url.replace(/\/+$/, "") : DEFAULT_URL,
+        space: raw.space,
+        targets,
+    };
+}
+export function writeRepoConfig(root, config) {
+    writeFileSync(join(root, CONFIG_FILENAME), JSON.stringify(config, null, 2) + "\n");
+}
+function credentialsPath() {
+    return join(homedir(), ".config", "knowa", "credentials.json");
+}
+export function resolveApiKey(url) {
+    const fromEnv = process.env.KNOWA_API_KEY;
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const creds = JSON.parse(readFileSync(credentialsPath(), "utf8"));
+        return creds[url] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function storeApiKey(url, key) {
+    const path = credentialsPath();
+    let creds = {};
+    try {
+        creds = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        // First key — start fresh.
+    }
+    creds[url] = key;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(creds, null, 2) + "\n");
+    chmodSync(path, 0o600);
+}

package/dist/context.js

@@ -0,0 +1,24 @@
+import { KnowaClient } from "./api.js";
+import { findRepoRoot, readRepoConfig, resolveApiKey } from "./config.js";
+/** Resolve repo root + config + credentials, with actionable errors. */
+export function loadContext() {
+    const root = findRepoRoot();
+    if (!root) {
+        throw new Error("No knowa.json found in this directory or any parent. Run `knowa init` first.");
+    }
+    const config = readRepoConfig(root);
+    const apiKey = resolveApiKey(config.url);
+    if (!apiKey) {
+        throw new Error(`No API key for ${config.url}. Set KNOWA_API_KEY or run \`knowa init\` to store one.`);
+    }
+    return { root, config, client: new KnowaClient(config.url, apiKey) };
+}
+/** Strip the frontmatter block from a canonical asset file, leaving the body. */
+export function bodyOf(content) {
+    if (!content.startsWith("---\n"))
+        return content;
+    const closing = content.indexOf("\n---\n", 4);
+    if (closing === -1)
+        return content;
+    return content.slice(closing + 5).replace(/^\n+/, "");
+}

package/dist/fsops.js

@@ -0,0 +1,51 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, unlinkSync, writeFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { sha256 } from "./hash.js";
+/** Hash-on-demand view of the working tree, rooted at the repo. */
+export function diskSnapshot(root) {
+    return {
+        hashOf(path) {
+            try {
+                return sha256(readFileSync(join(root, path)));
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+export function readFileOrNull(root, path) {
+    try {
+        return readFileSync(join(root, path), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomic write: temp file in the same directory, then rename over. */
+export function writeFileAtomic(root, path, content) {
+    const abs = join(root, path);
+    mkdirSync(dirname(abs), { recursive: true });
+    const tmp = `${abs}.knowa-tmp`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, abs);
+}
+/** Delete a managed file, then prune now-empty parent dirs up to the root. */
+export function deleteFileAndPrune(root, path) {
+    const abs = join(root, path);
+    if (existsSync(abs))
+        unlinkSync(abs);
+    let dir = dirname(abs);
+    const stop = join(root, ".");
+    while (dir !== stop && dir.startsWith(root)) {
+        try {
+            if (readdirSync(dir).length > 0)
+                break;
+            rmdirSync(dir);
+        }
+        catch {
+            break;
+        }
+        dir = dirname(dir);
+    }
+}

package/dist/hash.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+/**
+ * SHA-256 hex of exact bytes — must match the server's contentHashOf
+ * (src/lib/context/frontmatter.ts) so a file written verbatim from the API
+ * hashes to the manifest's value.
+ */
+export function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}

package/dist/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { loadContext } from "./context.js";
+import { runInit } from "./commands/init.js";
+import { runPull } from "./commands/pull.js";
+import { runPush } from "./commands/push.js";
+import { runStatus } from "./commands/status.js";
+import { runWatch } from "./commands/watch.js";
+const VERSION = "0.1.0";
+const HELP = `knowa ${VERSION} — sync your team's AI context into this repo
+
+Usage:
+  knowa init                 Link this repo to a Knowa space
+  knowa pull [--force] [--dry-run]
+                             Materialize .claude/ .cursor/ .knowa/ from Knowa
+  knowa watch [--interval N] Keep them in sync (polls; pulls on change)
+  knowa status [--porcelain] What pull/push would do
+  knowa push [path…] [--org] Publish local asset edits back to Knowa
+
+The repo link lives in knowa.json (commit it). Your API key comes from
+KNOWA_API_KEY or ~/.config/knowa/credentials.json (never the repo).`;
+function flag(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1)
+        return false;
+    args.splice(i, 1);
+    return true;
+}
+function option(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1 || i + 1 >= args.length)
+        return undefined;
+    const [, value] = args.splice(i, 2);
+    return value;
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args.shift();
+    switch (command) {
+        case "init":
+            await runInit();
+            return 0;
+        case "pull": {
+            const force = flag(args, "--force");
+            const dryRun = flag(args, "--dry-run");
+            const { conflicts } = await runPull(loadContext(), { force, dryRun });
+            return conflicts.length > 0 ? 2 : 0;
+        }
+        case "watch":
+            return runWatch(option(args, "--interval"));
+        case "status":
+            return runStatus(flag(args, "--porcelain"));
+        case "push":
+            return runPush(args.filter((a) => !a.startsWith("--")), { org: flag(args, "--org") });
+        case "--version":
+        case "-v":
+            console.log(VERSION);
+            return 0;
+        default:
+            console.log(HELP);
+            return command === undefined || command === "help" || command === "--help" ? 0 : 1;
+    }
+}
+main().then((code) => process.exit(code), (err) => {
+    console.error(`knowa: ${err.message}`);
+    process.exit(1);
+});

package/dist/state.js

@@ -0,0 +1,20 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const STATE_PATH = join(".knowa", "state.json");
+export function readState(root) {
+    const path = join(root, STATE_PATH);
+    if (!existsSync(path))
+        return { files: {} };
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return { files: raw.files ?? {}, claudeMd: raw.claudeMd, etag: raw.etag };
+    }
+    catch {
+        return { files: {} };
+    }
+}
+export function writeState(root, state) {
+    const path = join(root, STATE_PATH);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2) + "\n");
+}

package/dist/sync.js

@@ -0,0 +1,61 @@
+export function planSync(desired, stateFiles, disk) {
+    const actions = [];
+    const unchanged = [];
+    // Ownership and diffing are strictly per-path (one asset can map to
+    // several paths — a COMMAND syncs to both .claude/ and .cursor/).
+    // Tombstones and renames need no special casing: their paths simply stop
+    // being desired, and the leftover sweep below retires them.
+    const live = desired.filter((f) => !f.deleted);
+    const handled = new Set();
+    for (const file of live) {
+        handled.add(file.path);
+        const tracked = stateFiles[file.path];
+        const diskHash = disk.hashOf(file.path);
+        if (!tracked) {
+            if (diskHash === null) {
+                actions.push({ op: "create", file });
+            }
+            else {
+                actions.push({ op: "conflict-untracked", path: file.path, file });
+            }
+            continue;
+        }
+        if (diskHash === null) {
+            // The user deleted a managed file that's still desired: restore it.
+            actions.push({ op: "create", file });
+            continue;
+        }
+        // A different asset now claims a path we own (e.g. doc renames swapped
+        // paths): the remote effectively changed even if hashes coincide.
+        const sameEntity = tracked.kind === file.kind && tracked.id === file.id;
+        const remoteChanged = !sameEntity || tracked.remoteHash !== file.remoteHash;
+        const locallyModified = diskHash !== tracked.fileHash;
+        if (!remoteChanged) {
+            unchanged.push(file.path);
+        }
+        else if (!locallyModified) {
+            actions.push({ op: "update", file });
+        }
+        else {
+            actions.push({ op: "conflict-modified", path: file.path, file });
+        }
+    }
+    // Leftover sweep: every tracked path that's no longer desired (tombstoned,
+    // renamed away, aged-out, or turned invisible) is retired — deleted when
+    // the local copy is untouched, orphaned (kept, untracked) when modified.
+    for (const [path, entry] of Object.entries(stateFiles)) {
+        if (handled.has(path))
+            continue;
+        const diskHash = disk.hashOf(path);
+        if (diskHash === null) {
+            // Nothing on disk — silently drop the state entry.
+        }
+        else if (diskHash === entry.fileHash) {
+            actions.push({ op: "delete", path });
+        }
+        else {
+            actions.push({ op: "orphan", path });
+        }
+    }
+    return { actions, unchanged };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@knowalabs/knowa",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Sync your team's AI context — agents, commands, skills, rules, docs — from Knowa into .claude/, .cursor/ and .knowa/ folders.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "knowa": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "ai",
+    "context",
+    "mcp",
+    "claude",
+    "cursor",
+    "agents",
+    "sync"
+  ],
+  "homepage": "https://knowalabs.com",
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0"
+  }
+}