diffwiki-core 0.2.0-rc.202607210907.c99416d

package/dist/index.cjs

@@ -0,0 +1,538 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ArticleNotFoundError: () => ArticleNotFoundError,
+  CollectionExistsError: () => CollectionExistsError,
+  CollectionNotFoundError: () => CollectionNotFoundError,
+  DiffwikiError: () => DiffwikiError,
+  InvalidTargetError: () => InvalidTargetError,
+  NoDefaultCollectionError: () => NoDefaultCollectionError,
+  REPO_CONFIG_FILE: () => REPO_CONFIG_FILE,
+  addTags: () => addTags,
+  collectionDir: () => collectionDir,
+  collectionsDir: () => collectionsDir,
+  configPath: () => configPath,
+  createArticle: () => createArticle,
+  createCollection: () => createCollection,
+  doctor: () => doctor,
+  findCollection: () => findCollection,
+  getConfigValue: () => getConfigValue,
+  initRepoWiki: () => initRepoWiki,
+  listCollections: () => listCollections,
+  parseAddTarget: () => parseAddTarget,
+  parseArticle: () => parseArticle,
+  parsePathTarget: () => parsePathTarget,
+  query: () => query,
+  readConfig: () => readConfig,
+  readRegistry: () => readRegistry,
+  readRepoConfig: () => readRepoConfig,
+  registerCollection: () => registerCollection,
+  registryPath: () => registryPath,
+  removeArticle: () => removeArticle,
+  removeCollection: () => removeCollection,
+  removeTags: () => removeTags,
+  resolveHome: () => resolveHome,
+  serializeArticle: () => serializeArticle,
+  setConfigValue: () => setConfigValue,
+  setTags: () => setTags,
+  slugify: () => slugify,
+  unregisterCollection: () => unregisterCollection,
+  updateArticleBody: () => updateArticleBody,
+  writeConfig: () => writeConfig,
+  writeRegistry: () => writeRegistry
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var DiffwikiError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var CollectionExistsError = class extends DiffwikiError {
+  constructor(name) {
+    super(`collection "${name}" already exists`);
+  }
+};
+var CollectionNotFoundError = class extends DiffwikiError {
+  constructor(name) {
+    super(`collection "${name}" not found`);
+  }
+};
+var NoDefaultCollectionError = class extends DiffwikiError {
+  constructor() {
+    super("no default collection set (use: diffwiki config-set defaultCollection <name>)");
+  }
+};
+var ArticleNotFoundError = class extends DiffwikiError {
+  constructor(target) {
+    super(`article "${target}" not found`);
+  }
+};
+var InvalidTargetError = class extends DiffwikiError {
+  constructor(target, expected) {
+    super(`invalid target "${target}" \u2014 ${expected}`);
+  }
+};
+
+// src/paths.ts
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path = __toESM(require("path"), 1);
+function resolveHome() {
+  const override = process.env.DIFFWIKI_HOME;
+  return override && override.length > 0 ? override : import_node_path.default.join(import_node_os.default.homedir(), ".diffwiki");
+}
+function registryPath() {
+  return import_node_path.default.join(resolveHome(), "registry.json");
+}
+function configPath() {
+  return import_node_path.default.join(resolveHome(), "config.json");
+}
+function collectionsDir() {
+  return import_node_path.default.join(resolveHome(), "collections");
+}
+function collectionDir(name) {
+  return import_node_path.default.join(collectionsDir(), name);
+}
+
+// src/config.ts
+var import_promises3 = __toESM(require("fs/promises"), 1);
+
+// src/collections.ts
+var import_promises2 = __toESM(require("fs/promises"), 1);
+
+// src/registry.ts
+var import_promises = __toESM(require("fs/promises"), 1);
+function isMissing(err) {
+  return err?.code === "ENOENT";
+}
+async function readRegistry() {
+  try {
+    const parsed = JSON.parse(await import_promises.default.readFile(registryPath(), "utf8"));
+    return { version: parsed.version ?? 1, collections: parsed.collections ?? [] };
+  } catch (err) {
+    if (isMissing(err)) return { version: 1, collections: [] };
+    throw err;
+  }
+}
+async function writeRegistry(registry) {
+  await import_promises.default.mkdir(resolveHome(), { recursive: true });
+  await import_promises.default.writeFile(registryPath(), `${JSON.stringify(registry, null, 2)}
+`, "utf8");
+}
+async function registerCollection(entry) {
+  const registry = await readRegistry();
+  const index = registry.collections.findIndex((c) => c.name === entry.name);
+  if (index >= 0) {
+    registry.collections[index] = entry;
+  } else {
+    registry.collections.push(entry);
+  }
+  await writeRegistry(registry);
+}
+async function unregisterCollection(name) {
+  const registry = await readRegistry();
+  registry.collections = registry.collections.filter((c) => c.name !== name);
+  await writeRegistry(registry);
+}
+
+// src/collections.ts
+async function listCollections() {
+  return (await readRegistry()).collections;
+}
+async function findCollection(name) {
+  return (await readRegistry()).collections.find((c) => c.name === name);
+}
+async function createCollection(name) {
+  if (await findCollection(name)) throw new CollectionExistsError(name);
+  const dir = collectionDir(name);
+  await import_promises2.default.mkdir(dir, { recursive: true });
+  const entry = {
+    name,
+    type: "global",
+    path: dir,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await registerCollection(entry);
+  return entry;
+}
+async function removeCollection(name) {
+  const entry = await findCollection(name);
+  if (!entry) throw new CollectionNotFoundError(name);
+  await unregisterCollection(name);
+  if (entry.type === "global") {
+    await import_promises2.default.rm(entry.path, { recursive: true, force: true });
+  }
+  return entry;
+}
+
+// src/config.ts
+function isMissing2(err) {
+  return err?.code === "ENOENT";
+}
+async function readConfig() {
+  try {
+    return JSON.parse(await import_promises3.default.readFile(configPath(), "utf8"));
+  } catch (err) {
+    if (isMissing2(err)) return {};
+    throw err;
+  }
+}
+async function writeConfig(config) {
+  await import_promises3.default.mkdir(resolveHome(), { recursive: true });
+  await import_promises3.default.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
+async function setConfigValue(key, value) {
+  if (key === "defaultCollection" && !await findCollection(value)) {
+    throw new CollectionNotFoundError(value);
+  }
+  const config = await readConfig();
+  config[key] = value;
+  await writeConfig(config);
+}
+async function getConfigValue(key) {
+  const config = await readConfig();
+  const value = config[key];
+  return typeof value === "string" ? value : void 0;
+}
+
+// src/slugify.ts
+function slugify(input) {
+  const slug = input.toLowerCase().replace(/^#+\s*/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80).replace(/-+$/g, "");
+  return slug.length > 0 ? slug : "untitled";
+}
+
+// src/frontmatter.ts
+var import_gray_matter = __toESM(require("gray-matter"), 1);
+function parseArticle(raw) {
+  const { data, content } = (0, import_gray_matter.default)(raw);
+  const title = typeof data.title === "string" ? data.title : "";
+  const tags = Array.isArray(data.tags) ? data.tags.map((t) => String(t)) : [];
+  const created = typeof data.created === "string" ? data.created : void 0;
+  return { title, tags, created, body: content.replace(/^\n+/, "") };
+}
+function serializeArticle(article) {
+  const front = { title: article.title, tags: article.tags };
+  if (article.created) front.created = article.created;
+  if (article.updated) front.updated = article.updated;
+  return import_gray_matter.default.stringify(article.body, front);
+}
+
+// src/articles.ts
+var import_promises4 = __toESM(require("fs/promises"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+function parseAddTarget(target) {
+  const idx = target.indexOf(":");
+  if (idx === -1) {
+    const title2 = target.trim();
+    if (!title2) throw new InvalidTargetError(target, 'expected "[collection:]title"');
+    return { title: title2 };
+  }
+  const collection = target.slice(0, idx).trim();
+  const title = target.slice(idx + 1).trim();
+  if (!title) throw new InvalidTargetError(target, 'expected "[collection:]title"');
+  return collection ? { collection, title } : { title };
+}
+function parsePathTarget(target) {
+  const idx = target.indexOf(":");
+  if (idx === -1) throw new InvalidTargetError(target, 'expected "collection:path"');
+  const collection = target.slice(0, idx).trim();
+  const file = target.slice(idx + 1).trim();
+  if (!collection || !file) throw new InvalidTargetError(target, 'expected "collection:path"');
+  return { collection, file };
+}
+async function resolveCollectionDir(name) {
+  let coll = name;
+  if (!coll) {
+    coll = (await readConfig()).defaultCollection;
+    if (!coll) throw new NoDefaultCollectionError();
+  }
+  const entry = await findCollection(coll);
+  if (!entry) throw new CollectionNotFoundError(coll);
+  return { name: coll, dir: entry.path };
+}
+function ensureMdPath(file) {
+  if (/\.mdx?$/.test(file)) return file;
+  const dir = import_node_path2.default.dirname(file);
+  const base = slugify(import_node_path2.default.basename(file));
+  const rel = dir === "." ? `${base}.md` : import_node_path2.default.join(dir, `${base}.md`);
+  return rel;
+}
+async function createArticle(opts) {
+  const { collection, title } = parseAddTarget(opts.target);
+  const { name, dir } = await resolveCollectionDir(collection);
+  const filePath = import_node_path2.default.join(dir, `${slugify(title)}.md`);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const body = opts.body ?? `# ${title}
+`;
+  await import_promises4.default.mkdir(dir, { recursive: true });
+  await import_promises4.default.writeFile(filePath, serializeArticle({ title, tags: opts.tags, created: now, updated: now, body }), "utf8");
+  return { title, tags: opts.tags, path: filePath, collection: name };
+}
+async function loadArticle(target) {
+  const { collection, file } = parsePathTarget(target);
+  const { dir } = await resolveCollectionDir(collection);
+  const filePath = import_node_path2.default.join(dir, ensureMdPath(file));
+  try {
+    return { filePath, raw: await import_promises4.default.readFile(filePath, "utf8"), collection };
+  } catch (err) {
+    if (err.code === "ENOENT") throw new ArticleNotFoundError(target);
+    throw err;
+  }
+}
+async function updateArticleBody(target, body) {
+  const { filePath, raw, collection } = await loadArticle(target);
+  const parsed = parseArticle(raw);
+  await import_promises4.default.writeFile(
+    filePath,
+    serializeArticle({
+      title: parsed.title,
+      tags: parsed.tags,
+      created: parsed.created,
+      updated: (/* @__PURE__ */ new Date()).toISOString(),
+      body
+    }),
+    "utf8"
+  );
+  return { title: parsed.title, tags: parsed.tags, path: filePath, collection };
+}
+async function mutateTags(target, fn) {
+  const { filePath, raw, collection } = await loadArticle(target);
+  const parsed = parseArticle(raw);
+  const tags = fn(parsed.tags);
+  await import_promises4.default.writeFile(
+    filePath,
+    serializeArticle({
+      title: parsed.title,
+      tags,
+      created: parsed.created,
+      updated: (/* @__PURE__ */ new Date()).toISOString(),
+      body: parsed.body
+    }),
+    "utf8"
+  );
+  return { title: parsed.title, tags, path: filePath, collection };
+}
+function addTags(target, tags) {
+  return mutateTags(target, (current) => Array.from(/* @__PURE__ */ new Set([...current, ...tags])));
+}
+function removeTags(target, tags) {
+  const drop = new Set(tags);
+  return mutateTags(target, (current) => current.filter((t) => !drop.has(t)));
+}
+function setTags(target, tags) {
+  return mutateTags(target, () => Array.from(new Set(tags)));
+}
+async function removeArticle(target) {
+  const { filePath } = await loadArticle(target);
+  await import_promises4.default.rm(filePath);
+  return filePath;
+}
+
+// src/repo.ts
+var import_promises5 = __toESM(require("fs/promises"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
+var import_node_child_process = require("child_process");
+var import_node_util = require("util");
+var import_yaml = require("yaml");
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var REPO_CONFIG_FILE = "diffwiki.yaml";
+async function detectRepoName(cwd) {
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd });
+    return import_node_path3.default.basename(stdout.trim());
+  } catch {
+    return import_node_path3.default.basename(import_node_path3.default.resolve(cwd));
+  }
+}
+async function readRepoConfig(cwd) {
+  try {
+    const raw = await import_promises5.default.readFile(import_node_path3.default.join(cwd, REPO_CONFIG_FILE), "utf8");
+    const parsed = (0, import_yaml.parse)(raw) ?? {};
+    if (!parsed.path) return void 0;
+    return {
+      collection: parsed.collection ?? import_node_path3.default.basename(import_node_path3.default.resolve(cwd)),
+      path: parsed.path
+    };
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+}
+async function initRepoWiki(opts) {
+  const cwd = import_node_path3.default.resolve(opts.cwd);
+  const wikiPath = opts.wikiPath ?? "wiki";
+  const absWiki = import_node_path3.default.join(cwd, wikiPath);
+  let name = opts.collection ?? await detectRepoName(cwd);
+  const existing = await findCollection(name);
+  if (existing && existing.path !== absWiki) {
+    let n = 2;
+    for (; ; ) {
+      const candidate = `${name}-${n}`;
+      const clash = await findCollection(candidate);
+      if (!clash || clash.path === absWiki) {
+        name = candidate;
+        break;
+      }
+      n += 1;
+    }
+  }
+  await import_promises5.default.mkdir(absWiki, { recursive: true });
+  const config = { collection: name, path: wikiPath };
+  await import_promises5.default.writeFile(import_node_path3.default.join(cwd, REPO_CONFIG_FILE), (0, import_yaml.stringify)(config), "utf8");
+  const entry = {
+    name,
+    type: "repo",
+    path: absWiki,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await registerCollection(entry);
+  return entry;
+}
+
+// src/query.ts
+var import_promises6 = __toESM(require("fs/promises"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
+async function query(term, collection) {
+  let targets;
+  if (collection) {
+    const one = await findCollection(collection);
+    if (!one) throw new CollectionNotFoundError(collection);
+    targets = [one];
+  } else {
+    targets = await listCollections();
+  }
+  const needle = term.toLowerCase();
+  const hits = [];
+  for (const entry of targets) {
+    let files;
+    try {
+      files = await import_promises6.default.readdir(entry.path);
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      if (!/\.mdx?$/.test(file)) continue;
+      const full = import_node_path4.default.join(entry.path, file);
+      const parsed = parseArticle(await import_promises6.default.readFile(full, "utf8"));
+      const haystack = [parsed.title, file, ...parsed.tags].join(" ").toLowerCase();
+      if (!needle || haystack.includes(needle)) {
+        hits.push({ collection: entry.name, path: full, title: parsed.title, tags: parsed.tags });
+      }
+    }
+  }
+  return hits;
+}
+
+// src/doctor.ts
+var import_promises7 = __toESM(require("fs/promises"), 1);
+async function exists(target) {
+  try {
+    await import_promises7.default.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function doctor() {
+  const out = [];
+  const home = resolveHome();
+  out.push(
+    await exists(home) ? { level: "ok", message: `home directory present: ${home}` } : { level: "warn", message: `home directory missing (created on first write): ${home}` }
+  );
+  out.push(
+    await exists(registryPath()) ? { level: "ok", message: `registry present: ${registryPath()}` } : { level: "warn", message: `registry missing: ${registryPath()}` }
+  );
+  const registry = await readRegistry();
+  for (const c of registry.collections) {
+    out.push(
+      await exists(c.path) ? { level: "ok", message: `collection "${c.name}" \u2192 ${c.path}` } : { level: "error", message: `collection "${c.name}" points to missing path: ${c.path}` }
+    );
+  }
+  const config = await readConfig();
+  if (config.defaultCollection) {
+    const found = registry.collections.some((c) => c.name === config.defaultCollection);
+    out.push(
+      found ? { level: "ok", message: `default collection: ${config.defaultCollection}` } : {
+        level: "error",
+        message: `default collection "${config.defaultCollection}" is not registered`
+      }
+    );
+  } else {
+    out.push({ level: "warn", message: "no default collection set" });
+  }
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ArticleNotFoundError,
+  CollectionExistsError,
+  CollectionNotFoundError,
+  DiffwikiError,
+  InvalidTargetError,
+  NoDefaultCollectionError,
+  REPO_CONFIG_FILE,
+  addTags,
+  collectionDir,
+  collectionsDir,
+  configPath,
+  createArticle,
+  createCollection,
+  doctor,
+  findCollection,
+  getConfigValue,
+  initRepoWiki,
+  listCollections,
+  parseAddTarget,
+  parseArticle,
+  parsePathTarget,
+  query,
+  readConfig,
+  readRegistry,
+  readRepoConfig,
+  registerCollection,
+  registryPath,
+  removeArticle,
+  removeCollection,
+  removeTags,
+  resolveHome,
+  serializeArticle,
+  setConfigValue,
+  setTags,
+  slugify,
+  unregisterCollection,
+  updateArticleBody,
+  writeConfig,
+  writeRegistry
+});

package/dist/index.d.cts

@@ -0,0 +1,145 @@
+type CollectionType = 'global' | 'repo';
+interface CollectionEntry {
+    name: string;
+    type: CollectionType;
+    /** Absolute path to the collection's directory. */
+    path: string;
+    createdAt: string;
+}
+interface Registry {
+    version: number;
+    collections: CollectionEntry[];
+}
+interface Config {
+    defaultCollection?: string;
+}
+interface Article {
+    title: string;
+    tags: string[];
+    /** Absolute path to the article file. */
+    path: string;
+    collection: string;
+}
+interface RepoConfig {
+    collection: string;
+    /** Path to the wiki directory, relative to the repo root. */
+    path: string;
+}
+
+/** Base class for all expected, user-facing diffwiki failures. */
+declare class DiffwikiError extends Error {
+    constructor(message: string);
+}
+declare class CollectionExistsError extends DiffwikiError {
+    constructor(name: string);
+}
+declare class CollectionNotFoundError extends DiffwikiError {
+    constructor(name: string);
+}
+declare class NoDefaultCollectionError extends DiffwikiError {
+    constructor();
+}
+declare class ArticleNotFoundError extends DiffwikiError {
+    constructor(target: string);
+}
+declare class InvalidTargetError extends DiffwikiError {
+    constructor(target: string, expected: string);
+}
+
+/** Root of all global diffwiki state. Overridable via DIFFWIKI_HOME (used by tests). */
+declare function resolveHome(): string;
+declare function registryPath(): string;
+declare function configPath(): string;
+declare function collectionsDir(): string;
+declare function collectionDir(name: string): string;
+
+declare function readConfig(): Promise<Config>;
+declare function writeConfig(config: Config): Promise<void>;
+declare function setConfigValue(key: string, value: string): Promise<void>;
+declare function getConfigValue(key: string): Promise<string | undefined>;
+
+declare function readRegistry(): Promise<Registry>;
+declare function writeRegistry(registry: Registry): Promise<void>;
+/** Insert or replace the entry with the same name. */
+declare function registerCollection(entry: CollectionEntry): Promise<void>;
+declare function unregisterCollection(name: string): Promise<void>;
+
+/** Turn a title (or a "# Heading" line) into a filesystem-safe slug. */
+declare function slugify(input: string): string;
+
+interface ParsedArticle {
+    title: string;
+    tags: string[];
+    created?: string;
+    body: string;
+}
+interface SerializableArticle {
+    title: string;
+    tags: string[];
+    created?: string;
+    updated?: string;
+    body: string;
+}
+declare function parseArticle(raw: string): ParsedArticle;
+declare function serializeArticle(article: SerializableArticle): string;
+
+declare function listCollections(): Promise<CollectionEntry[]>;
+declare function findCollection(name: string): Promise<CollectionEntry | undefined>;
+declare function createCollection(name: string): Promise<CollectionEntry>;
+/**
+ * Remove a collection from the registry. For `global` collections we own the
+ * storage, so its directory is deleted too; for `repo` wikis we only deregister
+ * (the files live in the user's repo and are left untouched).
+ */
+declare function removeCollection(name: string): Promise<CollectionEntry>;
+
+/** Parse "[collection:]title" (collection optional) for `add`. */
+declare function parseAddTarget(target: string): {
+    collection?: string;
+    title: string;
+};
+/** Parse "collection:path" (both required) for update/remove/tags. */
+declare function parsePathTarget(target: string): {
+    collection: string;
+    file: string;
+};
+declare function createArticle(opts: {
+    target: string;
+    tags: string[];
+    body?: string;
+}): Promise<Article>;
+declare function updateArticleBody(target: string, body: string): Promise<Article>;
+declare function addTags(target: string, tags: string[]): Promise<Article>;
+declare function removeTags(target: string, tags: string[]): Promise<Article>;
+declare function setTags(target: string, tags: string[]): Promise<Article>;
+declare function removeArticle(target: string): Promise<string>;
+
+declare const REPO_CONFIG_FILE = "diffwiki.yaml";
+declare function readRepoConfig(cwd: string): Promise<RepoConfig | undefined>;
+interface InitOptions {
+    cwd: string;
+    collection?: string;
+    wikiPath?: string;
+}
+declare function initRepoWiki(opts: InitOptions): Promise<CollectionEntry>;
+
+interface QueryHit {
+    collection: string;
+    path: string;
+    title: string;
+    tags: string[];
+}
+/**
+ * DUMMY search: case-insensitive substring match over title, filename, and tags.
+ * Real QMD-based semantic search replaces this later.
+ */
+declare function query(term: string, collection?: string): Promise<QueryHit[]>;
+
+type DiagnosticLevel = 'ok' | 'warn' | 'error';
+interface Diagnostic {
+    level: DiagnosticLevel;
+    message: string;
+}
+declare function doctor(): Promise<Diagnostic[]>;
+
+export { type Article, ArticleNotFoundError, type CollectionEntry, CollectionExistsError, CollectionNotFoundError, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type InitOptions, InvalidTargetError, NoDefaultCollectionError, type ParsedArticle, type QueryHit, REPO_CONFIG_FILE, type Registry, type RepoConfig, type SerializableArticle, addTags, collectionDir, collectionsDir, configPath, createArticle, createCollection, doctor, findCollection, getConfigValue, initRepoWiki, listCollections, parseAddTarget, parseArticle, parsePathTarget, query, readConfig, readRegistry, readRepoConfig, registerCollection, registryPath, removeArticle, removeCollection, removeTags, resolveHome, serializeArticle, setConfigValue, setTags, slugify, unregisterCollection, updateArticleBody, writeConfig, writeRegistry };

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+type CollectionType = 'global' | 'repo';
+interface CollectionEntry {
+    name: string;
+    type: CollectionType;
+    /** Absolute path to the collection's directory. */
+    path: string;
+    createdAt: string;
+}
+interface Registry {
+    version: number;
+    collections: CollectionEntry[];
+}
+interface Config {
+    defaultCollection?: string;
+}
+interface Article {
+    title: string;
+    tags: string[];
+    /** Absolute path to the article file. */
+    path: string;
+    collection: string;
+}
+interface RepoConfig {
+    collection: string;
+    /** Path to the wiki directory, relative to the repo root. */
+    path: string;
+}
+
+/** Base class for all expected, user-facing diffwiki failures. */
+declare class DiffwikiError extends Error {
+    constructor(message: string);
+}
+declare class CollectionExistsError extends DiffwikiError {
+    constructor(name: string);
+}
+declare class CollectionNotFoundError extends DiffwikiError {
+    constructor(name: string);
+}
+declare class NoDefaultCollectionError extends DiffwikiError {
+    constructor();
+}
+declare class ArticleNotFoundError extends DiffwikiError {
+    constructor(target: string);
+}
+declare class InvalidTargetError extends DiffwikiError {
+    constructor(target: string, expected: string);
+}
+
+/** Root of all global diffwiki state. Overridable via DIFFWIKI_HOME (used by tests). */
+declare function resolveHome(): string;
+declare function registryPath(): string;
+declare function configPath(): string;
+declare function collectionsDir(): string;
+declare function collectionDir(name: string): string;
+
+declare function readConfig(): Promise<Config>;
+declare function writeConfig(config: Config): Promise<void>;
+declare function setConfigValue(key: string, value: string): Promise<void>;
+declare function getConfigValue(key: string): Promise<string | undefined>;
+
+declare function readRegistry(): Promise<Registry>;
+declare function writeRegistry(registry: Registry): Promise<void>;
+/** Insert or replace the entry with the same name. */
+declare function registerCollection(entry: CollectionEntry): Promise<void>;
+declare function unregisterCollection(name: string): Promise<void>;
+
+/** Turn a title (or a "# Heading" line) into a filesystem-safe slug. */
+declare function slugify(input: string): string;
+
+interface ParsedArticle {
+    title: string;
+    tags: string[];
+    created?: string;
+    body: string;
+}
+interface SerializableArticle {
+    title: string;
+    tags: string[];
+    created?: string;
+    updated?: string;
+    body: string;
+}
+declare function parseArticle(raw: string): ParsedArticle;
+declare function serializeArticle(article: SerializableArticle): string;
+
+declare function listCollections(): Promise<CollectionEntry[]>;
+declare function findCollection(name: string): Promise<CollectionEntry | undefined>;
+declare function createCollection(name: string): Promise<CollectionEntry>;
+/**
+ * Remove a collection from the registry. For `global` collections we own the
+ * storage, so its directory is deleted too; for `repo` wikis we only deregister
+ * (the files live in the user's repo and are left untouched).
+ */
+declare function removeCollection(name: string): Promise<CollectionEntry>;
+
+/** Parse "[collection:]title" (collection optional) for `add`. */
+declare function parseAddTarget(target: string): {
+    collection?: string;
+    title: string;
+};
+/** Parse "collection:path" (both required) for update/remove/tags. */
+declare function parsePathTarget(target: string): {
+    collection: string;
+    file: string;
+};
+declare function createArticle(opts: {
+    target: string;
+    tags: string[];
+    body?: string;
+}): Promise<Article>;
+declare function updateArticleBody(target: string, body: string): Promise<Article>;
+declare function addTags(target: string, tags: string[]): Promise<Article>;
+declare function removeTags(target: string, tags: string[]): Promise<Article>;
+declare function setTags(target: string, tags: string[]): Promise<Article>;
+declare function removeArticle(target: string): Promise<string>;
+
+declare const REPO_CONFIG_FILE = "diffwiki.yaml";
+declare function readRepoConfig(cwd: string): Promise<RepoConfig | undefined>;
+interface InitOptions {
+    cwd: string;
+    collection?: string;
+    wikiPath?: string;
+}
+declare function initRepoWiki(opts: InitOptions): Promise<CollectionEntry>;
+
+interface QueryHit {
+    collection: string;
+    path: string;
+    title: string;
+    tags: string[];
+}
+/**
+ * DUMMY search: case-insensitive substring match over title, filename, and tags.
+ * Real QMD-based semantic search replaces this later.
+ */
+declare function query(term: string, collection?: string): Promise<QueryHit[]>;
+
+type DiagnosticLevel = 'ok' | 'warn' | 'error';
+interface Diagnostic {
+    level: DiagnosticLevel;
+    message: string;
+}
+declare function doctor(): Promise<Diagnostic[]>;
+
+export { type Article, ArticleNotFoundError, type CollectionEntry, CollectionExistsError, CollectionNotFoundError, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type InitOptions, InvalidTargetError, NoDefaultCollectionError, type ParsedArticle, type QueryHit, REPO_CONFIG_FILE, type Registry, type RepoConfig, type SerializableArticle, addTags, collectionDir, collectionsDir, configPath, createArticle, createCollection, doctor, findCollection, getConfigValue, initRepoWiki, listCollections, parseAddTarget, parseArticle, parsePathTarget, query, readConfig, readRegistry, readRepoConfig, registerCollection, registryPath, removeArticle, removeCollection, removeTags, resolveHome, serializeArticle, setConfigValue, setTags, slugify, unregisterCollection, updateArticleBody, writeConfig, writeRegistry };

package/dist/index.js

@@ -0,0 +1,463 @@
+// src/errors.ts
+var DiffwikiError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var CollectionExistsError = class extends DiffwikiError {
+  constructor(name) {
+    super(`collection "${name}" already exists`);
+  }
+};
+var CollectionNotFoundError = class extends DiffwikiError {
+  constructor(name) {
+    super(`collection "${name}" not found`);
+  }
+};
+var NoDefaultCollectionError = class extends DiffwikiError {
+  constructor() {
+    super("no default collection set (use: diffwiki config-set defaultCollection <name>)");
+  }
+};
+var ArticleNotFoundError = class extends DiffwikiError {
+  constructor(target) {
+    super(`article "${target}" not found`);
+  }
+};
+var InvalidTargetError = class extends DiffwikiError {
+  constructor(target, expected) {
+    super(`invalid target "${target}" \u2014 ${expected}`);
+  }
+};
+
+// src/paths.ts
+import os from "os";
+import path from "path";
+function resolveHome() {
+  const override = process.env.DIFFWIKI_HOME;
+  return override && override.length > 0 ? override : path.join(os.homedir(), ".diffwiki");
+}
+function registryPath() {
+  return path.join(resolveHome(), "registry.json");
+}
+function configPath() {
+  return path.join(resolveHome(), "config.json");
+}
+function collectionsDir() {
+  return path.join(resolveHome(), "collections");
+}
+function collectionDir(name) {
+  return path.join(collectionsDir(), name);
+}
+
+// src/config.ts
+import fs3 from "fs/promises";
+
+// src/collections.ts
+import fs2 from "fs/promises";
+
+// src/registry.ts
+import fs from "fs/promises";
+function isMissing(err) {
+  return err?.code === "ENOENT";
+}
+async function readRegistry() {
+  try {
+    const parsed = JSON.parse(await fs.readFile(registryPath(), "utf8"));
+    return { version: parsed.version ?? 1, collections: parsed.collections ?? [] };
+  } catch (err) {
+    if (isMissing(err)) return { version: 1, collections: [] };
+    throw err;
+  }
+}
+async function writeRegistry(registry) {
+  await fs.mkdir(resolveHome(), { recursive: true });
+  await fs.writeFile(registryPath(), `${JSON.stringify(registry, null, 2)}
+`, "utf8");
+}
+async function registerCollection(entry) {
+  const registry = await readRegistry();
+  const index = registry.collections.findIndex((c) => c.name === entry.name);
+  if (index >= 0) {
+    registry.collections[index] = entry;
+  } else {
+    registry.collections.push(entry);
+  }
+  await writeRegistry(registry);
+}
+async function unregisterCollection(name) {
+  const registry = await readRegistry();
+  registry.collections = registry.collections.filter((c) => c.name !== name);
+  await writeRegistry(registry);
+}
+
+// src/collections.ts
+async function listCollections() {
+  return (await readRegistry()).collections;
+}
+async function findCollection(name) {
+  return (await readRegistry()).collections.find((c) => c.name === name);
+}
+async function createCollection(name) {
+  if (await findCollection(name)) throw new CollectionExistsError(name);
+  const dir = collectionDir(name);
+  await fs2.mkdir(dir, { recursive: true });
+  const entry = {
+    name,
+    type: "global",
+    path: dir,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await registerCollection(entry);
+  return entry;
+}
+async function removeCollection(name) {
+  const entry = await findCollection(name);
+  if (!entry) throw new CollectionNotFoundError(name);
+  await unregisterCollection(name);
+  if (entry.type === "global") {
+    await fs2.rm(entry.path, { recursive: true, force: true });
+  }
+  return entry;
+}
+
+// src/config.ts
+function isMissing2(err) {
+  return err?.code === "ENOENT";
+}
+async function readConfig() {
+  try {
+    return JSON.parse(await fs3.readFile(configPath(), "utf8"));
+  } catch (err) {
+    if (isMissing2(err)) return {};
+    throw err;
+  }
+}
+async function writeConfig(config) {
+  await fs3.mkdir(resolveHome(), { recursive: true });
+  await fs3.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
+async function setConfigValue(key, value) {
+  if (key === "defaultCollection" && !await findCollection(value)) {
+    throw new CollectionNotFoundError(value);
+  }
+  const config = await readConfig();
+  config[key] = value;
+  await writeConfig(config);
+}
+async function getConfigValue(key) {
+  const config = await readConfig();
+  const value = config[key];
+  return typeof value === "string" ? value : void 0;
+}
+
+// src/slugify.ts
+function slugify(input) {
+  const slug = input.toLowerCase().replace(/^#+\s*/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80).replace(/-+$/g, "");
+  return slug.length > 0 ? slug : "untitled";
+}
+
+// src/frontmatter.ts
+import matter from "gray-matter";
+function parseArticle(raw) {
+  const { data, content } = matter(raw);
+  const title = typeof data.title === "string" ? data.title : "";
+  const tags = Array.isArray(data.tags) ? data.tags.map((t) => String(t)) : [];
+  const created = typeof data.created === "string" ? data.created : void 0;
+  return { title, tags, created, body: content.replace(/^\n+/, "") };
+}
+function serializeArticle(article) {
+  const front = { title: article.title, tags: article.tags };
+  if (article.created) front.created = article.created;
+  if (article.updated) front.updated = article.updated;
+  return matter.stringify(article.body, front);
+}
+
+// src/articles.ts
+import fs4 from "fs/promises";
+import path2 from "path";
+function parseAddTarget(target) {
+  const idx = target.indexOf(":");
+  if (idx === -1) {
+    const title2 = target.trim();
+    if (!title2) throw new InvalidTargetError(target, 'expected "[collection:]title"');
+    return { title: title2 };
+  }
+  const collection = target.slice(0, idx).trim();
+  const title = target.slice(idx + 1).trim();
+  if (!title) throw new InvalidTargetError(target, 'expected "[collection:]title"');
+  return collection ? { collection, title } : { title };
+}
+function parsePathTarget(target) {
+  const idx = target.indexOf(":");
+  if (idx === -1) throw new InvalidTargetError(target, 'expected "collection:path"');
+  const collection = target.slice(0, idx).trim();
+  const file = target.slice(idx + 1).trim();
+  if (!collection || !file) throw new InvalidTargetError(target, 'expected "collection:path"');
+  return { collection, file };
+}
+async function resolveCollectionDir(name) {
+  let coll = name;
+  if (!coll) {
+    coll = (await readConfig()).defaultCollection;
+    if (!coll) throw new NoDefaultCollectionError();
+  }
+  const entry = await findCollection(coll);
+  if (!entry) throw new CollectionNotFoundError(coll);
+  return { name: coll, dir: entry.path };
+}
+function ensureMdPath(file) {
+  if (/\.mdx?$/.test(file)) return file;
+  const dir = path2.dirname(file);
+  const base = slugify(path2.basename(file));
+  const rel = dir === "." ? `${base}.md` : path2.join(dir, `${base}.md`);
+  return rel;
+}
+async function createArticle(opts) {
+  const { collection, title } = parseAddTarget(opts.target);
+  const { name, dir } = await resolveCollectionDir(collection);
+  const filePath = path2.join(dir, `${slugify(title)}.md`);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const body = opts.body ?? `# ${title}
+`;
+  await fs4.mkdir(dir, { recursive: true });
+  await fs4.writeFile(filePath, serializeArticle({ title, tags: opts.tags, created: now, updated: now, body }), "utf8");
+  return { title, tags: opts.tags, path: filePath, collection: name };
+}
+async function loadArticle(target) {
+  const { collection, file } = parsePathTarget(target);
+  const { dir } = await resolveCollectionDir(collection);
+  const filePath = path2.join(dir, ensureMdPath(file));
+  try {
+    return { filePath, raw: await fs4.readFile(filePath, "utf8"), collection };
+  } catch (err) {
+    if (err.code === "ENOENT") throw new ArticleNotFoundError(target);
+    throw err;
+  }
+}
+async function updateArticleBody(target, body) {
+  const { filePath, raw, collection } = await loadArticle(target);
+  const parsed = parseArticle(raw);
+  await fs4.writeFile(
+    filePath,
+    serializeArticle({
+      title: parsed.title,
+      tags: parsed.tags,
+      created: parsed.created,
+      updated: (/* @__PURE__ */ new Date()).toISOString(),
+      body
+    }),
+    "utf8"
+  );
+  return { title: parsed.title, tags: parsed.tags, path: filePath, collection };
+}
+async function mutateTags(target, fn) {
+  const { filePath, raw, collection } = await loadArticle(target);
+  const parsed = parseArticle(raw);
+  const tags = fn(parsed.tags);
+  await fs4.writeFile(
+    filePath,
+    serializeArticle({
+      title: parsed.title,
+      tags,
+      created: parsed.created,
+      updated: (/* @__PURE__ */ new Date()).toISOString(),
+      body: parsed.body
+    }),
+    "utf8"
+  );
+  return { title: parsed.title, tags, path: filePath, collection };
+}
+function addTags(target, tags) {
+  return mutateTags(target, (current) => Array.from(/* @__PURE__ */ new Set([...current, ...tags])));
+}
+function removeTags(target, tags) {
+  const drop = new Set(tags);
+  return mutateTags(target, (current) => current.filter((t) => !drop.has(t)));
+}
+function setTags(target, tags) {
+  return mutateTags(target, () => Array.from(new Set(tags)));
+}
+async function removeArticle(target) {
+  const { filePath } = await loadArticle(target);
+  await fs4.rm(filePath);
+  return filePath;
+}
+
+// src/repo.ts
+import fs5 from "fs/promises";
+import path3 from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var execFileAsync = promisify(execFile);
+var REPO_CONFIG_FILE = "diffwiki.yaml";
+async function detectRepoName(cwd) {
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd });
+    return path3.basename(stdout.trim());
+  } catch {
+    return path3.basename(path3.resolve(cwd));
+  }
+}
+async function readRepoConfig(cwd) {
+  try {
+    const raw = await fs5.readFile(path3.join(cwd, REPO_CONFIG_FILE), "utf8");
+    const parsed = parseYaml(raw) ?? {};
+    if (!parsed.path) return void 0;
+    return {
+      collection: parsed.collection ?? path3.basename(path3.resolve(cwd)),
+      path: parsed.path
+    };
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+}
+async function initRepoWiki(opts) {
+  const cwd = path3.resolve(opts.cwd);
+  const wikiPath = opts.wikiPath ?? "wiki";
+  const absWiki = path3.join(cwd, wikiPath);
+  let name = opts.collection ?? await detectRepoName(cwd);
+  const existing = await findCollection(name);
+  if (existing && existing.path !== absWiki) {
+    let n = 2;
+    for (; ; ) {
+      const candidate = `${name}-${n}`;
+      const clash = await findCollection(candidate);
+      if (!clash || clash.path === absWiki) {
+        name = candidate;
+        break;
+      }
+      n += 1;
+    }
+  }
+  await fs5.mkdir(absWiki, { recursive: true });
+  const config = { collection: name, path: wikiPath };
+  await fs5.writeFile(path3.join(cwd, REPO_CONFIG_FILE), stringifyYaml(config), "utf8");
+  const entry = {
+    name,
+    type: "repo",
+    path: absWiki,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await registerCollection(entry);
+  return entry;
+}
+
+// src/query.ts
+import fs6 from "fs/promises";
+import path4 from "path";
+async function query(term, collection) {
+  let targets;
+  if (collection) {
+    const one = await findCollection(collection);
+    if (!one) throw new CollectionNotFoundError(collection);
+    targets = [one];
+  } else {
+    targets = await listCollections();
+  }
+  const needle = term.toLowerCase();
+  const hits = [];
+  for (const entry of targets) {
+    let files;
+    try {
+      files = await fs6.readdir(entry.path);
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      if (!/\.mdx?$/.test(file)) continue;
+      const full = path4.join(entry.path, file);
+      const parsed = parseArticle(await fs6.readFile(full, "utf8"));
+      const haystack = [parsed.title, file, ...parsed.tags].join(" ").toLowerCase();
+      if (!needle || haystack.includes(needle)) {
+        hits.push({ collection: entry.name, path: full, title: parsed.title, tags: parsed.tags });
+      }
+    }
+  }
+  return hits;
+}
+
+// src/doctor.ts
+import fs7 from "fs/promises";
+async function exists(target) {
+  try {
+    await fs7.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function doctor() {
+  const out = [];
+  const home = resolveHome();
+  out.push(
+    await exists(home) ? { level: "ok", message: `home directory present: ${home}` } : { level: "warn", message: `home directory missing (created on first write): ${home}` }
+  );
+  out.push(
+    await exists(registryPath()) ? { level: "ok", message: `registry present: ${registryPath()}` } : { level: "warn", message: `registry missing: ${registryPath()}` }
+  );
+  const registry = await readRegistry();
+  for (const c of registry.collections) {
+    out.push(
+      await exists(c.path) ? { level: "ok", message: `collection "${c.name}" \u2192 ${c.path}` } : { level: "error", message: `collection "${c.name}" points to missing path: ${c.path}` }
+    );
+  }
+  const config = await readConfig();
+  if (config.defaultCollection) {
+    const found = registry.collections.some((c) => c.name === config.defaultCollection);
+    out.push(
+      found ? { level: "ok", message: `default collection: ${config.defaultCollection}` } : {
+        level: "error",
+        message: `default collection "${config.defaultCollection}" is not registered`
+      }
+    );
+  } else {
+    out.push({ level: "warn", message: "no default collection set" });
+  }
+  return out;
+}
+export {
+  ArticleNotFoundError,
+  CollectionExistsError,
+  CollectionNotFoundError,
+  DiffwikiError,
+  InvalidTargetError,
+  NoDefaultCollectionError,
+  REPO_CONFIG_FILE,
+  addTags,
+  collectionDir,
+  collectionsDir,
+  configPath,
+  createArticle,
+  createCollection,
+  doctor,
+  findCollection,
+  getConfigValue,
+  initRepoWiki,
+  listCollections,
+  parseAddTarget,
+  parseArticle,
+  parsePathTarget,
+  query,
+  readConfig,
+  readRegistry,
+  readRepoConfig,
+  registerCollection,
+  registryPath,
+  removeArticle,
+  removeCollection,
+  removeTags,
+  resolveHome,
+  serializeArticle,
+  setConfigValue,
+  setTags,
+  slugify,
+  unregisterCollection,
+  updateArticleBody,
+  writeConfig,
+  writeRegistry
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "diffwiki-core",
+  "version": "0.2.0-rc.202607210907.c99416d",
+  "description": "Core configuration, registry, and article management for diffwiki",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src tests --no-error-on-unmatched-pattern && tsc --noEmit",
+    "lint:fix": "eslint src tests --no-error-on-unmatched-pattern --fix"
+  }
+}