@nzpr/kb 0.1.0

package/.env.example

@@ -0,0 +1,5 @@
+KB_DATABASE_URL=postgresql://kb:kb@localhost:5432/kb
+KB_EMBEDDING_MODE=local-hash
+# KB_EMBEDDING_API_URL=http://127.0.0.1:8000/v1/embeddings
+# KB_EMBEDDING_MODEL=BAAI/bge-m3
+# KB_EMBEDDING_API_KEY=

package/LICENSE

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

package/README.md

@@ -0,0 +1,185 @@
+# Team Knowledge Base CLI
+
+`@nzpr/kb` is the npm package and CLI used by a separate knowledge-authority repository.
+
+Each KB instance is defined by:
+
+- `KB_DATABASE_URL`
+- `KB_GITHUB_REPO`
+
+This repository is for the tool itself.
+
+The actual knowledge base should live in a separate repository that owns:
+
+- `kb/docs/`
+- issue templates
+- review and approval workflow
+- CI that runs `kb publish`
+
+Bootstrap that repo with:
+
+```bash
+kb init-repo --dir /path/to/knowledge-repo
+```
+
+Or bootstrap and configure it in one step:
+
+```bash
+export GITHUB_TOKEN=...
+kb init-repo \
+  --dir /path/to/knowledge-repo \
+  --repo owner/knowledge-repo \
+  --database-url postgresql://kb:kb@host:5432/kb \
+  --embedding-mode bge-m3-openai \
+  --embedding-api-url https://embeddings.example.com/v1/embeddings \
+  --embedding-model BAAI/bge-m3
+```
+
+## Commands
+
+- `kb init-repo [--dir PATH] [--repo OWNER/REPO]`
+- `kb search "<terms>"`
+- `kb ask "<question>"`
+- `kb list`
+- `kb catalog [--json]`
+- `kb create --title TEXT --text TEXT [--path RELATIVE_PATH]`
+- `kb publish --docs-root PATH`
+
+## Install
+
+From npm:
+
+```bash
+npm install -g @nzpr/kb
+kb --help
+```
+
+From source:
+
+```bash
+npm install
+npm link
+```
+
+## Knowledge Repo Workflow
+
+In the separate knowledge-authority repo:
+
+1. Run `kb init-repo` once to scaffold the repo. If you provide `--repo`, `--database-url`, and `GITHUB_TOKEN`, it also configures the target repo and preflights the database.
+2. Open or update a knowledge proposal issue.
+3. Review and approve it there.
+4. Materialize it into `kb/docs/`.
+5. After merge, that repo's CI runs `kb publish --docs-root ./kb/docs`.
+
+`kb init-repo` is safe to rerun. It reports bootstrap status for:
+
+- local scaffold creation
+- database preflight and schema initialization
+- GitHub repo labels, variables, and secrets
+
+If one remote step fails, the scaffold still stays in place and the command tells you what to rerun.
+
+## Runtime
+
+Node.js 20+ is required.
+
+Query commands need:
+
+```bash
+export KB_DATABASE_URL=postgresql://kb:kb@localhost:5432/kb
+```
+
+Higher-quality embeddings with a self-hosted OpenAI-compatible `BAAI/bge-m3` server:
+
+```bash
+export KB_EMBEDDING_MODE=bge-m3-openai
+export KB_EMBEDDING_API_URL=https://embeddings.example.com/v1/embeddings
+export KB_EMBEDDING_MODEL=BAAI/bge-m3
+export KB_EMBEDDING_API_KEY=...
+```
+
+If `KB_EMBEDDING_MODE` is omitted, the CLI uses local hash embeddings for development.
+
+Publishing needs one more privileged environment variable:
+
+```bash
+export KB_GITHUB_REPO=owner/repo
+export GITHUB_TOKEN=...
+```
+
+Publishing is allowed when the provided `GITHUB_TOKEN` has write access to `KB_GITHUB_REPO`. Normal readers do not need GitHub credentials.
+
+When `kb init-repo` is given `--repo`, it uses the same token to:
+
+- enable issues in the target repo
+- create or update the `kb-entry` and `kb-approved` labels
+- write repository secrets and variables
+- verify and initialize the target database schema if `--database-url` is provided
+
+If you run `kb init-repo` without the repo or database inputs, it still scaffolds the knowledge repo and prints exactly which remote bootstrap inputs are still pending.
+
+## Quick Start
+
+```bash
+export KB_DATABASE_URL=postgresql://kb:kb@localhost:5432/kb
+export KB_GITHUB_REPO=owner/repo
+export GITHUB_TOKEN=...
+docker compose -f docker-compose.pgvector.yml up -d
+kb publish --docs-root ./kb/docs
+kb catalog --json
+kb search "deployment rule"
+```
+
+Each Markdown file is indexed as one document and one vector row. Keep documents simple: one title and one body.
+
+## Optional Split Mode
+
+If you later want separate entities, isolated databases, or a dedicated content repo, you can use `kb create` with:
+
+```bash
+export KB_GITHUB_REPO=org/knowledge-content
+export GITHUB_TOKEN=...
+```
+
+That path is optional. The default assumption is that you work in one repo.
+
+## npm Release
+
+The package is published as `@nzpr/kb`.
+
+- local validation: `npm test`
+- local package preview: `npm pack --dry-run`
+- GitHub Actions publish: push a tag like `v0.1.0` or run the `npm-publish` workflow manually
+- required repository secret: `NPM_TOKEN`
+
+## Using From A Knowledge Repo
+
+The knowledge-authority repo should install this package in CI and use it to sync `kb/docs/` into the vector database:
+
+```bash
+npm install -g @nzpr/kb
+export KB_GITHUB_REPO=owner/repo
+export GITHUB_TOKEN=...
+kb publish --docs-root ./kb/docs
+```
+
+Or scaffold that repo first:
+
+```bash
+kb init-repo --dir .
+```
+
+If you want init to configure the target repo too:
+
+```bash
+export GITHUB_TOKEN=...
+export KB_REPO_AUTOMATION_TOKEN=...
+kb init-repo \
+  --dir . \
+  --repo owner/knowledge-repo \
+  --database-url postgresql://kb:kb@host:5432/kb \
+  --embedding-mode bge-m3-openai \
+  --embedding-api-url https://embeddings.example.com/v1/embeddings \
+  --embedding-model BAAI/bge-m3 \
+  --embedding-api-key YOUR_KEY
+```

package/bin/kb-admin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../lib/admin-cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/bin/kb.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../lib/cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/docker-compose.pgvector.yml

@@ -0,0 +1,19 @@
+services:
+  postgres:
+    image: pgvector/pgvector:pg16
+    environment:
+      POSTGRES_DB: kb
+      POSTGRES_USER: kb
+      POSTGRES_PASSWORD: kb
+    ports:
+      - "5432:5432"
+    volumes:
+      - kb_pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U kb -d kb"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  kb_pgdata:

package/lib/admin-cli.js

@@ -0,0 +1,203 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  resolveDatabaseUrl,
+  resolveDocsRoot,
+  resolveEmbeddingProfile,
+  tryResolveKnowledgeRoot
+} from "./config.js";
+import { connect, initDb, schemaStatus } from "./db.js";
+import { ingestDocuments } from "./index.js";
+import { writeProposalDocument } from "./kb-proposals.js";
+import { databaseHelp, formatCliError, maskConnection, parseFlags } from "./cli-common.js";
+
+export async function main(argv) {
+  try {
+    const [command, ...rest] = argv;
+    if (!command || command === "--help" || command === "-h") {
+      printHelp();
+      return 0;
+    }
+    if (rest.includes("--help") || rest.includes("-h")) {
+      printCommandHelp(command);
+      return 0;
+    }
+
+    const { flags } = parseFlags(rest);
+    switch (command) {
+      case "migrate": {
+        const databaseUrl = requireDatabaseUrl();
+        const client = await connect(databaseUrl);
+        try {
+          const result = await initDb(client);
+          console.log(
+            `migrated knowledge database: ${maskConnection(databaseUrl)} current=${result.currentVersion} applied=${result.appliedCount}`
+          );
+        } finally {
+          await client.end();
+        }
+        return 0;
+      }
+      case "init-db": {
+        const databaseUrl = requireDatabaseUrl();
+        const client = await connect(databaseUrl);
+        try {
+          const result = await initDb(client);
+          console.log(
+            `initialized knowledge database: ${maskConnection(databaseUrl)} current=${result.currentVersion} applied=${result.appliedCount}`
+          );
+        } finally {
+          await client.end();
+        }
+        return 0;
+      }
+      case "status": {
+        const databaseUrl = requireDatabaseUrl();
+        const client = await connect(databaseUrl);
+        try {
+          const status = await schemaStatus(client);
+          console.log(`database: ${maskConnection(databaseUrl)}`);
+          console.log(`schema current: ${status.currentVersion}`);
+          console.log(`schema latest: ${status.latestVersion}`);
+          console.log(`schema pending: ${status.pendingCount}`);
+        } finally {
+          await client.end();
+        }
+        return 0;
+      }
+      case "ingest": {
+        const databaseUrl = requireDatabaseUrl();
+        const embeddingProfile = resolveEmbeddingProfile();
+        const knowledgeRoot = flags["knowledge-root"]
+          ? path.resolve(flags["knowledge-root"])
+          : tryResolveKnowledgeRoot();
+        const docsRoot = resolveDocsRoot({
+          docsRoot: flags["docs-root"] ?? null,
+          knowledgeRoot
+        });
+        if (!docsRoot) {
+          console.error("--docs-root PATH is required when no local docs directory is present");
+          return 2;
+        }
+        if (!fs.existsSync(docsRoot)) {
+          console.error(`docs root does not exist: ${docsRoot}`);
+          return 2;
+        }
+        const result = await ingestDocuments({ databaseUrl, docsRoot, embeddingProfile });
+        console.log(
+          `indexed ${result.documents} documents, wrote ${result.vectors} vectors using ${result.embeddingMode}${result.embeddingModel ? `/${result.embeddingModel}` : ""} embeddings`
+        );
+        return 0;
+      }
+      case "issue-to-doc": {
+        const knowledgeRoot = flags["knowledge-root"]
+          ? path.resolve(flags["knowledge-root"])
+          : tryResolveKnowledgeRoot();
+        const docsRoot = resolveDocsRoot({
+          docsRoot: flags["docs-root"] ?? null,
+          knowledgeRoot
+        });
+        if (!docsRoot) {
+          console.error("--docs-root PATH is required when no local docs directory is present");
+          return 2;
+        }
+        const issueEventPath = flags["issue-event"] ? path.resolve(flags["issue-event"]) : null;
+        if (!issueEventPath) {
+          console.error("--issue-event PATH is required");
+          return 2;
+        }
+        if (!fs.existsSync(issueEventPath)) {
+          console.error(`issue event payload does not exist: ${issueEventPath}`);
+          return 2;
+        }
+        const event = JSON.parse(fs.readFileSync(issueEventPath, "utf8"));
+        const issue = event.issue;
+        if (!issue?.body) {
+          throw new Error("issue event payload did not include an issue body");
+        }
+        const result = writeProposalDocument({
+          issueNumber: issue.number,
+          issueTitle: issue.title,
+          issueBody: issue.body,
+          docsRoot
+        });
+        writeGitHubOutput({
+          doc_id: result.proposal.docId,
+          doc_path: path.relative(process.cwd(), result.absolutePath).replace(/\\/g, "/"),
+          branch: result.branch,
+          commit_message: result.commitMessage,
+          pr_title: result.prTitle,
+          pr_body: result.prBody
+        });
+        console.log(`materialized issue #${issue.number} into ${result.relativePath}`);
+        return 0;
+      }
+      default:
+        console.error(`unknown command: ${command}`);
+        return 2;
+    }
+  } catch (error) {
+    console.error(formatCliError(error));
+    return 1;
+  }
+}
+
+function printHelp() {
+  console.log(`usage: kb-admin <command> [options]
+
+internal automation only; normal users should use kb
+
+commands:
+  migrate
+  init-db
+  status
+  ingest
+  issue-to-doc
+
+${databaseHelp()}
+
+ingest options:
+  --docs-root PATH
+
+issue-to-doc options:
+  --issue-event PATH
+  --docs-root PATH
+
+optional path hint:
+  --knowledge-root PATH
+`);
+}
+
+function printCommandHelp(command) {
+  const commandHelp = {
+    migrate: `usage: kb-admin migrate\n\n${databaseHelp()}`,
+    "init-db": `usage: kb-admin init-db\n\n${databaseHelp()}\n\ninit-db is a bootstrap alias for migrate.`,
+    status: `usage: kb-admin status\n\n${databaseHelp()}`,
+    ingest: `usage: kb-admin ingest [--docs-root PATH] [--knowledge-root PATH]\n\n${databaseHelp()}`,
+    "issue-to-doc": `usage: kb-admin issue-to-doc --issue-event PATH [--docs-root PATH]\n\nInternal automation for approved KB issues.`
+  };
+  console.log(commandHelp[command] ?? `unknown command: ${command}`);
+}
+
+function requireDatabaseUrl() {
+  const databaseUrl = resolveDatabaseUrl();
+  if (!databaseUrl) {
+    throw new Error("KB_DATABASE_URL is not set");
+  }
+  return databaseUrl;
+}
+
+function writeGitHubOutput(entries) {
+  const outputPath = process.env.GITHUB_OUTPUT ?? null;
+  if (!outputPath) {
+    return;
+  }
+  for (const [key, value] of Object.entries(entries)) {
+    const normalized = String(value);
+    if (normalized.includes("\n")) {
+      fs.appendFileSync(outputPath, `${key}<<__KB_EOF__\n${normalized}\n__KB_EOF__\n`, "utf8");
+      continue;
+    }
+    fs.appendFileSync(outputPath, `${key}=${normalized}\n`, "utf8");
+  }
+}

package/lib/chunking.js

@@ -0,0 +1,16 @@
+export function chunkMarkdown(meta, body) {
+  const content = String(body ?? "").trim();
+  if (!content) {
+    return [];
+  }
+  return [
+    {
+      chunkId: `${meta.docId}#0`,
+      docId: meta.docId,
+      title: meta.title,
+      heading: meta.title,
+      content,
+      path: meta.path,
+    }
+  ];
+}

package/lib/cli-common.js

@@ -0,0 +1,73 @@
+export function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    if (key === "json" || key === "include-drafts") {
+      flags[key] = true;
+      continue;
+    }
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+      throw new Error(`missing value for --${key}`);
+    }
+    flags[key] = value;
+    index += 1;
+  }
+  return { flags, positional };
+}
+
+export function maskConnection(connectionString) {
+  try {
+    const url = new URL(connectionString);
+    if (url.password) {
+      url.password = "****";
+    }
+    return url.toString();
+  } catch {
+    return connectionString;
+  }
+}
+
+export function formatCliError(error) {
+  const message = String(error?.message ?? error);
+  if (
+    /ECONNREFUSED|connect ECONNREFUSED|ENOTFOUND|timeout expired|Connection terminated unexpectedly/i.test(
+      message
+    )
+  ) {
+    return `database connection failed: ${message}`;
+  }
+  return message;
+}
+
+export function databaseHelp() {
+  return `required runtime:
+  KB_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB
+
+optional embeddings:
+  KB_EMBEDDING_MODE=local-hash|bge-m3-openai
+  KB_EMBEDDING_API_URL=http://HOST:8000/v1/embeddings
+  KB_EMBEDDING_MODEL=BAAI/bge-m3
+  KB_EMBEDDING_API_KEY=...`;
+}
+
+export function githubCreationHelp() {
+  return `required GitHub issue creation runtime:
+  KB_GITHUB_REPO=OWNER/REPO
+  GITHUB_TOKEN=...
+
+optional GitHub API override:
+  GITHUB_API_URL=https://api.github.com`;
+}
+
+export function publishHelp() {
+  return `required publish authorization:
+  KB_GITHUB_REPO=OWNER/REPO
+  GITHUB_TOKEN=...`;
+}