@nzpr/kb 0.1.0 → 0.1.2

package/README.md

@@ -1,38 +1,75 @@
 # Team Knowledge Base CLI
 
-`@nzpr/kb` is the npm package and CLI used by a separate knowledge-authority repository.
+`@nzpr/kb` is a package for managing a knowledge base that agents can read from and that humans can keep curated.
 
-Each KB instance is defined by:
+The core idea is simple:
 
-- `KB_DATABASE_URL`
-- `KB_GITHUB_REPO`
+- initialize a knowledge base
+- propose knowledge
+- publish approved knowledge
+- search the current knowledge
+- ask grounded questions against it
 
-This repository is for the tool itself.
+At the product level, a knowledge base is just a collection of documents, and each document should stay minimal:
 
-The actual knowledge base should live in a separate repository that owns:
+- `title`
+- `text`
 
-- `kb/docs/`
-- issue templates
-- review and approval workflow
-- CI that runs `kb publish`
+Everything else is implementation detail.
 
-Bootstrap that repo with:
+## Public API
+
+The public surface of `@nzpr/kb` is the `kb` CLI.
+
+- `kb init-repo`
+  Initialize a knowledge base workspace.
+  Use `kb init-repo --interactive` for a guided setup flow.
+
+- `kb create --title TEXT --text TEXT`
+  Propose a new knowledge document or a substantial update.
+
+- `kb publish`
+  Make the current approved documents become the live knowledge base.
+
+- `kb search "<query>"`
+  Return the closest matching knowledge documents.
+
+- `kb ask "<question>"`
+  Return a grounded answer from the closest matching knowledge.
+
+- `kb list`
+  List the current knowledge documents.
+
+- `kb catalog`
+  Return the current knowledge inventory in a machine-friendly form.
+
+- `kb doctor`
+  Check whether the knowledge base is healthy and queryable.
+
+## Lifecycle
+
+The intended workflow is:
+
+1. Initialize a knowledge base.
+2. Propose knowledge.
+3. Review and approve knowledge.
+4. Publish knowledge.
+5. Query knowledge.
+
+## Install
+
+From npm:
 
 ```bash
-kb init-repo --dir /path/to/knowledge-repo
+npm install -g @nzpr/kb
+kb --help
 ```
 
-Or bootstrap and configure it in one step:
+From source:
 
 ```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
+npm install
+npm link
 ```
 
 ## Commands
@@ -45,25 +82,40 @@ kb init-repo \
 - `kb create --title TEXT --text TEXT [--path RELATIVE_PATH]`
 - `kb publish --docs-root PATH`
 
-## Install
+## Knowledge Repo Workflow
 
-From npm:
+In practice, the live knowledge usually lives in a separate repository that owns:
+
+- `kb/docs/`
+- the review flow for proposed knowledge
+- the publish automation
+
+Bootstrap that repo with:
 
 ```bash
-npm install -g @nzpr/kb
-kb --help
+kb init-repo --dir /path/to/knowledge-repo
 ```
 
-From source:
+If you want the CLI to walk you through setup and tell you what to do next:
 
 ```bash
-npm install
-npm link
+kb init-repo --interactive
 ```
 
-## Knowledge Repo Workflow
+Or bootstrap and configure it in one step:
 
-In the separate knowledge-authority repo:
+```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
+```
+
+Inside that knowledge repo, the normal flow is:
 
 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.
@@ -77,6 +129,14 @@ In the separate knowledge-authority repo:
 - database preflight and schema initialization
 - GitHub repo labels, variables, and secrets
 
+In interactive mode it also:
+
+- asks which repo and directory you want to initialize
+- asks whether to wire GitHub setup now
+- asks whether to verify the database now
+- collects embedding settings if you want remote embeddings
+- prints the next actions after initialization
+
 If one remote step fails, the scaffold still stays in place and the command tells you what to rerun.
 
 ## Runtime
@@ -89,7 +149,7 @@ Query commands need:
 export KB_DATABASE_URL=postgresql://kb:kb@localhost:5432/kb
 ```
 
-Higher-quality embeddings with a self-hosted OpenAI-compatible `BAAI/bge-m3` server:
+Higher-quality retrieval can use a self-hosted embeddings service:
 
 ```bash
 export KB_EMBEDDING_MODE=bge-m3-openai
@@ -150,7 +210,8 @@ 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`
+- npm authentication: use npm trusted publishing with GitHub Actions OIDC, not a long-lived publish token
+- required npm setup: in npm package settings, configure trusted publishing for `nzpr/kb` and workflow file `.github/workflows/npm-publish.yml`
 
 ## Using From A Knowledge Repo
 

package/lib/cli-common.js

@@ -8,7 +8,7 @@ export function parseFlags(args) {
       continue;
     }
     const key = arg.slice(2);
-    if (key === "json" || key === "include-drafts") {
+    if (key === "json" || key === "include-drafts" || key === "interactive") {
       flags[key] = true;
       continue;
     }

package/lib/cli.js

@@ -9,6 +9,7 @@ import {
 } from "./config.js";
 import { connect, initDb } from "./db.js";
 import { ingestDocuments } from "./index.js";
+import { collectInitRepoInteractiveOptions } from "./init-repo-interactive.js";
 import { createGitHubIssueFromText } from "./kb-proposals.js";
 import { bootstrapKnowledgeRepo } from "./repo-init.js";
 import { askIndex, doctor, knowledgeCatalog, listDocuments, searchIndex, snippet } from "./search.js";
@@ -60,19 +61,32 @@ export async function main(argv) {
         return 0;
       }
       case "init-repo": {
+        const initRepoOptions = flags.interactive
+          ? await collectInitRepoInteractiveOptions({ flags })
+          : {
+              targetDir: flags.dir ?? process.cwd(),
+              repo: flags.repo ?? resolveGitHubRepository(),
+              databaseUrl: flags["database-url"] ?? process.env.KB_DATABASE_URL ?? null,
+              embeddingMode: flags["embedding-mode"] ?? process.env.KB_EMBEDDING_MODE ?? null,
+              embeddingApiUrl: flags["embedding-api-url"] ?? process.env.KB_EMBEDDING_API_URL ?? null,
+              embeddingModel: flags["embedding-model"] ?? process.env.KB_EMBEDDING_MODEL ?? null,
+              embeddingApiKey: flags["embedding-api-key"] ?? process.env.KB_EMBEDDING_API_KEY ?? null,
+              dbConnectTimeoutMs:
+                flags["db-connect-timeout-ms"] ?? process.env.KB_DB_CONNECT_TIMEOUT_MS ?? null,
+              repoAutomationToken:
+                flags["repo-automation-token"] ?? process.env.KB_REPO_AUTOMATION_TOKEN ?? null
+            };
         const result = await bootstrapKnowledgeRepo({
-          targetDir: flags.dir ?? process.cwd(),
-          repo: flags.repo ?? resolveGitHubRepository(),
+          targetDir: initRepoOptions.targetDir,
+          repo: initRepoOptions.repo,
           githubToken: process.env.GITHUB_TOKEN ?? null,
-          databaseUrl: flags["database-url"] ?? process.env.KB_DATABASE_URL ?? null,
-          embeddingMode: flags["embedding-mode"] ?? process.env.KB_EMBEDDING_MODE ?? null,
-          embeddingApiUrl: flags["embedding-api-url"] ?? process.env.KB_EMBEDDING_API_URL ?? null,
-          embeddingModel: flags["embedding-model"] ?? process.env.KB_EMBEDDING_MODEL ?? null,
-          embeddingApiKey: flags["embedding-api-key"] ?? process.env.KB_EMBEDDING_API_KEY ?? null,
-          dbConnectTimeoutMs:
-            flags["db-connect-timeout-ms"] ?? process.env.KB_DB_CONNECT_TIMEOUT_MS ?? null,
-          repoAutomationToken:
-            flags["repo-automation-token"] ?? process.env.KB_REPO_AUTOMATION_TOKEN ?? null
+          databaseUrl: initRepoOptions.databaseUrl,
+          embeddingMode: initRepoOptions.embeddingMode,
+          embeddingApiUrl: initRepoOptions.embeddingApiUrl,
+          embeddingModel: initRepoOptions.embeddingModel,
+          embeddingApiKey: initRepoOptions.embeddingApiKey,
+          dbConnectTimeoutMs: initRepoOptions.dbConnectTimeoutMs,
+          repoAutomationToken: initRepoOptions.repoAutomationToken
         });
         console.log(`initialized knowledge repo scaffold in ${result.root}`);
         for (const relativePath of result.created) {
@@ -87,6 +101,7 @@ export async function main(argv) {
         printInitRepoStatus(result);
         printRepoConfiguration(result.configuration);
         printInitRepoNextStep(result);
+        printInitRepoChecklist(result);
         return result.ok ? 0 : 1;
       }
       case "search": {
@@ -231,7 +246,7 @@ function printHelp() {
   console.log(`usage: kb <command> [options]
 
 commands:
-  init-repo [--dir PATH] [--repo OWNER/REPO]
+  init-repo [--interactive] [--dir PATH] [--repo OWNER/REPO]
   create --title TEXT --text TEXT [--path RELATIVE_PATH]
   search <query>
   ask <question>
@@ -256,7 +271,7 @@ search options:
 function printCommandHelp(command) {
   const commandHelp = {
     "init-repo":
-      "usage: kb init-repo [--dir PATH] [--repo OWNER/REPO] [--database-url URL] [--embedding-mode MODE] [--embedding-api-url URL] [--embedding-model NAME] [--embedding-api-key KEY] [--db-connect-timeout-ms N] [--repo-automation-token TOKEN]\n\nScaffold a knowledge-authority repository, optionally configure its GitHub settings, and preflight the target database.",
+      "usage: kb init-repo [--interactive] [--dir PATH] [--repo OWNER/REPO] [--database-url URL] [--embedding-mode MODE] [--embedding-api-url URL] [--embedding-model NAME] [--embedding-api-key KEY] [--db-connect-timeout-ms N] [--repo-automation-token TOKEN]\n\nScaffold a knowledge-authority repository, optionally configure its GitHub settings, and preflight the target database. Use --interactive for a guided terminal walkthrough.",
     create: `usage: kb create --title TEXT --text TEXT [--path RELATIVE_PATH] [--repo OWNER/REPO]\n\n${githubCreationHelp()}`,
     search: `usage: kb search <query> [options]\n\n${databaseHelp()}\n  --limit N`,
     ask: `usage: kb ask <question> [options]\n\n${databaseHelp()}\n  --limit N`,
@@ -389,3 +404,19 @@ function printInitRepoNextStep(result) {
     "next: rerun kb init-repo with the missing repo or database inputs when you are ready, or commit the scaffold now and finish remote setup later"
   );
 }
+
+function printInitRepoChecklist(result) {
+  console.log("");
+  console.log("what to do next:");
+  if (result.created.length || result.skipped.length) {
+    console.log("  1. commit and push the scaffolded knowledge repo files");
+  }
+  if (result.github.status !== "configured") {
+    console.log("  2. make sure the target repo exists and rerun with --repo once GitHub setup is ready");
+  }
+  if (result.database.status !== "verified") {
+    console.log("  3. rerun with --database-url once the target database is ready");
+  }
+  console.log("  4. use kb create to open a proposal issue for the first knowledge entry");
+  console.log("  5. review the issue, add kb-approved, merge the generated PR, and let publish sync the live KB");
+}

package/lib/init-repo-interactive.js

@@ -0,0 +1,222 @@
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as defaultStdin, stdout as defaultStdout } from "node:process";
+import { resolveGitHubRepository } from "./config.js";
+
+export async function collectInitRepoInteractiveOptions({
+  flags,
+  env = process.env,
+  cwd = process.cwd(),
+  stdin = defaultStdin,
+  stdout = defaultStdout,
+  prompter = null
+}) {
+  if (!prompter && (!stdin.isTTY || !stdout.isTTY)) {
+    throw new Error("interactive init-repo requires a TTY; rerun in a terminal or pass flags directly");
+  }
+
+  const prompt = prompter ?? createReadlinePrompter({ stdin, stdout });
+
+  try {
+    const defaults = buildInitRepoDefaults({ flags, env, cwd });
+
+    stdout.write("interactive kb init-repo\n");
+    stdout.write("this wizard scaffolds the knowledge repo and can also wire remote setup now.\n\n");
+
+    const targetDir = path.resolve(
+      cwd,
+      await prompt.askText("knowledge repo directory", defaults.targetDir, {
+        validate: requireValue
+      })
+    );
+
+    const configureRepo = await prompt.askConfirm(
+      "configure the GitHub repo now",
+      Boolean(defaults.repo || env.GITHUB_TOKEN)
+    );
+
+    let repo = null;
+    if (configureRepo) {
+      repo = await prompt.askText("target GitHub repo (OWNER/REPO)", defaults.repo, {
+        validate: requireValue
+      });
+    }
+
+    const verifyDatabase = await prompt.askConfirm(
+      "verify the database and initialize schema now",
+      Boolean(defaults.databaseUrl)
+    );
+
+    let databaseUrl = null;
+    if (verifyDatabase) {
+      databaseUrl = await prompt.askText("database URL", defaults.databaseUrl, {
+        validate: requireValue
+      });
+    }
+
+    let embeddingMode = null;
+    let embeddingApiUrl = null;
+    let embeddingModel = null;
+    let embeddingApiKey = null;
+    let dbConnectTimeoutMs = null;
+
+    if (verifyDatabase) {
+      const useRemoteEmbeddings = await prompt.askConfirm(
+        "configure remote embeddings now",
+        defaults.embeddingMode === "bge-m3-openai"
+      );
+
+      if (useRemoteEmbeddings) {
+        embeddingMode = "bge-m3-openai";
+        embeddingApiUrl = await prompt.askText(
+          "embedding API URL",
+          defaults.embeddingApiUrl || "https://your-embeddings-host/v1/embeddings",
+          { validate: requireValue }
+        );
+        embeddingModel = await prompt.askText(
+          "embedding model",
+          defaults.embeddingModel || "BAAI/bge-m3",
+          { validate: requireValue }
+        );
+        embeddingApiKey = await prompt.askText(
+          "embedding API key (optional)",
+          defaults.embeddingApiKey
+        );
+        dbConnectTimeoutMs = await prompt.askText(
+          "database connect timeout ms",
+          defaults.dbConnectTimeoutMs || "20000",
+          { validate: requirePositiveNumber }
+        );
+      }
+    }
+
+    let repoAutomationToken = null;
+    if (configureRepo) {
+      const useAutomationToken = await prompt.askConfirm(
+        "set a dedicated repo automation token secret",
+        Boolean(defaults.repoAutomationToken)
+      );
+      if (useAutomationToken) {
+        repoAutomationToken = await prompt.askText(
+          "repo automation token",
+          defaults.repoAutomationToken
+        );
+      }
+    }
+
+    stdout.write("\nplan:\n");
+    stdout.write(`  local scaffold: ${targetDir}\n`);
+    stdout.write(`  github repo setup: ${repo ? repo : "skip for now"}\n`);
+    stdout.write(`  database preflight: ${databaseUrl ? "yes" : "skip for now"}\n`);
+    stdout.write(
+      `  embeddings config: ${embeddingMode === "bge-m3-openai" ? `${embeddingMode}/${embeddingModel}` : "skip for now"}\n`
+    );
+
+    const proceed = await prompt.askConfirm("run init-repo with this plan", true);
+    if (!proceed) {
+      throw new Error("interactive init-repo cancelled");
+    }
+
+    return {
+      targetDir,
+      repo,
+      databaseUrl,
+      embeddingMode,
+      embeddingApiUrl,
+      embeddingModel,
+      embeddingApiKey: emptyToNull(embeddingApiKey),
+      dbConnectTimeoutMs: emptyToNull(dbConnectTimeoutMs),
+      repoAutomationToken: emptyToNull(repoAutomationToken)
+    };
+  } finally {
+    await prompt.close();
+  }
+}
+
+export function buildInitRepoDefaults({ flags = {}, env = process.env, cwd = process.cwd() }) {
+  return {
+    targetDir: flags.dir ?? cwd,
+    repo: flags.repo ?? resolveGitHubRepository(env) ?? "",
+    databaseUrl: flags["database-url"] ?? env.KB_DATABASE_URL ?? "",
+    embeddingMode: flags["embedding-mode"] ?? env.KB_EMBEDDING_MODE ?? "",
+    embeddingApiUrl: flags["embedding-api-url"] ?? env.KB_EMBEDDING_API_URL ?? "",
+    embeddingModel: flags["embedding-model"] ?? env.KB_EMBEDDING_MODEL ?? "",
+    embeddingApiKey: flags["embedding-api-key"] ?? env.KB_EMBEDDING_API_KEY ?? "",
+    dbConnectTimeoutMs:
+      flags["db-connect-timeout-ms"] ?? env.KB_DB_CONNECT_TIMEOUT_MS ?? "",
+    repoAutomationToken:
+      flags["repo-automation-token"] ?? env.KB_REPO_AUTOMATION_TOKEN ?? ""
+  };
+}
+
+function createReadlinePrompter({ stdin, stdout }) {
+  const rl = readline.createInterface({
+    input: stdin,
+    output: stdout
+  });
+  return {
+    askText(label, defaultValue = "", options = {}) {
+      return askText(rl, label, defaultValue, options);
+    },
+    askConfirm(label, defaultValue = false) {
+      return askConfirm(rl, label, defaultValue);
+    },
+    async close() {
+      rl.close();
+    }
+  };
+}
+
+async function askText(rl, label, defaultValue = "", { validate = null } = {}) {
+  while (true) {
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
+    const answer = (await rl.question(`${label}${suffix}: `)).trim();
+    const value = answer || String(defaultValue ?? "").trim();
+
+    if (!validate) {
+      return value;
+    }
+    const error = validate(value);
+    if (!error) {
+      return value;
+    }
+    rl.output.write(`${error}\n`);
+  }
+}
+
+async function askConfirm(rl, label, defaultValue = false) {
+  const hint = defaultValue ? "Y/n" : "y/N";
+  while (true) {
+    const answer = (await rl.question(`${label}? [${hint}]: `)).trim().toLowerCase();
+    if (!answer) {
+      return defaultValue;
+    }
+    if (["y", "yes"].includes(answer)) {
+      return true;
+    }
+    if (["n", "no"].includes(answer)) {
+      return false;
+    }
+    rl.output.write("please answer yes or no\n");
+  }
+}
+
+function requireValue(value) {
+  return String(value ?? "").trim() ? null : "a value is required";
+}
+
+function requirePositiveNumber(value) {
+  if (!String(value ?? "").trim()) {
+    return "a value is required";
+  }
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) {
+    return "enter a positive number";
+  }
+  return null;
+}
+
+function emptyToNull(value) {
+  const normalized = String(value ?? "").trim();
+  return normalized ? normalized : null;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nzpr/kb",
-  "version": "0.1.0",
-  "description": "Postgres/pgvector-backed knowledge base CLI for LLM agents and engineering teams.",
+  "version": "0.1.2",
+  "description": "Knowledge base CLI for proposing, publishing, and querying curated agent knowledge.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nzpr/kb.git"