@nzpr/kb 0.1.5 → 0.1.6

package/README.md

@@ -66,6 +66,14 @@ npm install -g @nzpr/kb
 kb --help
 ```
 
+Environment-driven setup:
+
+```bash
+cp .env.example .env
+```
+
+The CLI automatically reads `.env` from the current repository, so `kb init-repo`, `kb create`, `kb publish`, `kb search`, and `kb ask` can all use the values defined there.
+
 From source:
 
 ```bash
@@ -103,6 +111,8 @@ If you want the CLI to walk you through setup and tell you what to do next:
 kb init-repo --interactive
 ```
 
+The interactive flow checks the environment it can see, reports what is possible, and tells you which values are still missing from `.env`.
+
 Layout options:
 
 - `--layout repo-root` puts documents in `docs/`
@@ -141,9 +151,9 @@ Inside that knowledge repo, the normal flow is:
 In interactive mode it also:
 
 - asks which repo and directory you want to initialize
+- checks the environment values already available
 - 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.

package/lib/admin-cli.js

@@ -7,12 +7,14 @@ import {
   tryResolveKnowledgeRoot
 } from "./config.js";
 import { connect, initDb, schemaStatus } from "./db.js";
+import { loadDotEnv } from "./dotenv.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 {
+    loadDotEnv();
     const [command, ...rest] = argv;
     if (!command || command === "--help" || command === "-h") {
       printHelp();

package/lib/cli.js

@@ -8,6 +8,7 @@ import {
   tryResolveKnowledgeRoot
 } from "./config.js";
 import { connect, initDb } from "./db.js";
+import { loadDotEnv } from "./dotenv.js";
 import { ingestDocuments } from "./index.js";
 import { collectInitRepoInteractiveOptions } from "./init-repo-interactive.js";
 import { createGitHubIssueFromText } from "./kb-proposals.js";
@@ -24,6 +25,7 @@ import {
 
 export async function main(argv) {
   try {
+    loadDotEnv();
     const [command, ...rest] = argv;
     if (!command || command === "--help" || command === "-h") {
       printHelp();

package/lib/dotenv.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function loadDotEnv({ cwd = process.cwd(), env = process.env } = {}) {
+  const envPath = findDotEnv(cwd);
+  if (!envPath) {
+    return { path: null, loaded: [] };
+  }
+
+  const parsed = parseDotEnv(fs.readFileSync(envPath, "utf8"));
+  const loaded = [];
+  for (const [key, value] of Object.entries(parsed)) {
+    if (env[key] === undefined || env[key] === "") {
+      env[key] = value;
+      loaded.push(key);
+    }
+  }
+
+  return { path: envPath, loaded };
+}
+
+export function parseDotEnv(content) {
+  const values = {};
+  for (const rawLine of String(content ?? "").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!match) {
+      continue;
+    }
+    const [, key, rawValue] = match;
+    values[key] = normalizeEnvValue(rawValue);
+  }
+  return values;
+}
+
+function findDotEnv(start) {
+  let current = path.resolve(start);
+  while (true) {
+    const candidate = path.join(current, ".env");
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+function normalizeEnvValue(rawValue) {
+  const trimmed = rawValue.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  const commentIndex = trimmed.indexOf(" #");
+  if (commentIndex >= 0) {
+    return trimmed.slice(0, commentIndex).trim();
+  }
+  return trimmed;
+}

package/lib/init-repo-interactive.js

@@ -1,6 +1,5 @@
 import path from "node:path";
 import fs from "node:fs";
-import { execFileSync } from "node:child_process";
 import readline from "node:readline/promises";
 import { stdin as defaultStdin, stdout as defaultStdout } from "node:process";
 import { resolveGitHubRepository } from "./config.js";
@@ -11,8 +10,7 @@ export async function collectInitRepoInteractiveOptions({
   cwd = process.cwd(),
   stdin = defaultStdin,
   stdout = defaultStdout,
-  prompter = null,
-  auth = defaultInteractiveGitHubAuth
+  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");
@@ -33,6 +31,7 @@ export async function collectInitRepoInteractiveOptions({
       })
     );
     const layout = await askKnowledgeLayout(prompt, targetDir, defaults.layout);
+    printEnvCapabilities(stdout, defaults);
 
     const configureRepo = await prompt.askConfirm(
       "configure the GitHub repo now",
@@ -45,13 +44,8 @@ export async function collectInitRepoInteractiveOptions({
         validate: requireValue
       });
       if (!defaults.githubToken) {
-        const authorized = await ensureInteractiveGitHubAccess({ prompt, stdout, auth });
-        if (authorized) {
-          defaults.githubToken = authorized;
-        } else {
-          stdout.write("skipping GitHub repo setup for now because GitHub auth is not ready.\n");
-          repo = null;
-        }
+        stdout.write("skipping GitHub repo setup for now because GITHUB_TOKEN is not set. Put it in .env and rerun.\n");
+        repo = null;
       }
     }
 
@@ -60,62 +54,21 @@ export async function collectInitRepoInteractiveOptions({
       Boolean(defaults.databaseUrl)
     );
 
-    let databaseUrl = null;
-    if (verifyDatabase) {
-      databaseUrl = await prompt.askText("database URL", defaults.databaseUrl, {
-        validate: requireValue
-      });
+    let databaseUrl = verifyDatabase ? defaults.databaseUrl : null;
+    if (verifyDatabase && !databaseUrl) {
+      stdout.write("skipping database preflight for now because KB_DATABASE_URL is not set. Put it in .env and rerun.\n");
     }
 
-    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 }
-        );
-      }
+    if (!databaseUrl) {
+      databaseUrl = null;
     }
 
-    let repoAutomationToken = null;
-    if (configureRepo) {
-      const useAutomationToken = await prompt.askConfirm(
-        "use a custom automation token instead of the default GitHub Actions token",
-        Boolean(defaults.repoAutomationToken)
-      );
-      if (useAutomationToken) {
-        repoAutomationToken = await prompt.askText(
-          "repo automation token",
-          defaults.repoAutomationToken
-        );
-      }
-    }
+    const embeddingMode = defaults.embeddingMode || null;
+    const embeddingApiUrl = defaults.embeddingApiUrl || null;
+    const embeddingModel = defaults.embeddingModel || null;
+    const embeddingApiKey = defaults.embeddingApiKey || null;
+    const dbConnectTimeoutMs = defaults.dbConnectTimeoutMs || null;
+    const repoAutomationToken = defaults.repoAutomationToken || null;
 
     stdout.write("\nPlan\n");
     stdout.write(`  target directory: ${targetDir}\n`);
@@ -202,9 +155,6 @@ function createReadlinePrompter({ stdin, stdout }) {
     askText(label, defaultValue = "", options = {}) {
       return askText(rl, label, defaultValue, options);
     },
-    askSecret(label, options = {}) {
-      return askSecret({ stdin, stdout, label, ...options });
-    },
     askConfirm(label, defaultValue = false) {
       return askConfirm(rl, label, defaultValue);
     },
@@ -248,20 +198,6 @@ async function askConfirm(rl, label, defaultValue = false) {
   }
 }
 
-async function askSecret({ stdin, stdout, label, validate = null }) {
-  while (true) {
-    const value = await readHiddenInput({ stdin, stdout, prompt: `${label}: ` });
-    if (!validate) {
-      return value;
-    }
-    const error = validate(value);
-    if (!error) {
-      return value;
-    }
-    stdout.write(`${error}\n`);
-  }
-}
-
 function requireValue(value) {
   return String(value ?? "").trim() ? null : "a value is required";
 }
@@ -282,108 +218,12 @@ function emptyToNull(value) {
   return normalized ? normalized : null;
 }
 
-async function ensureInteractiveGitHubAccess({ prompt, stdout, auth }) {
-  const existingToken = auth.getToken();
-  if (existingToken) {
-    stdout.write("using existing GitHub CLI authentication for repo setup.\n");
-    return existingToken;
-  }
-
-  stdout.write("\nGitHub repo setup needs GitHub authentication.\n");
-  stdout.write("You can paste a GitHub token now, use GitHub CLI browser login, or skip repo setup for now.\n");
-
-  while (true) {
-    const method = (
-      await prompt.askText("authentication method (token/login/skip)", "token", {
-        validate: validateAuthMethod
-      })
-    ).toLowerCase();
-    if (method === "skip") {
-      return null;
-    }
-    if (method === "token") {
-      const token = await prompt.askSecret("GITHUB_TOKEN", {
-        validate: requireValue
-      });
-      if (token) {
-        stdout.write("using the provided GitHub token for repo setup.\n");
-        return token;
-      }
-      continue;
-    }
-    auth.login();
-    const token = auth.getToken();
-    if (token) {
-      stdout.write("GitHub CLI authentication is ready.\n");
-      return token;
-    }
-    stdout.write("GitHub CLI login did not yield a usable token.\n");
-  }
-}
-
-const defaultInteractiveGitHubAuth = {
-  getToken() {
-    try {
-      return execFileSync("gh", ["auth", "token"], {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"]
-      }).trim();
-    } catch {
-      return null;
-    }
-  },
-  login() {
-    execFileSync("gh", ["auth", "login", "--web", "--git-protocol", "https"], {
-      stdio: "inherit"
-    });
-  }
-};
-
-function validateAuthMethod(value) {
-  if (["token", "login", "skip"].includes(String(value ?? "").trim().toLowerCase())) {
-    return null;
-  }
-  return "enter token, login, or skip";
-}
-
-function readHiddenInput({ stdin, stdout, prompt }) {
-  return new Promise((resolve, reject) => {
-    stdout.write(prompt);
-    let value = "";
-    const wasRaw = Boolean(stdin.isRaw);
-
-    const cleanup = () => {
-      stdin.off("data", onData);
-      if (typeof stdin.setRawMode === "function") {
-        stdin.setRawMode(wasRaw);
-      }
-      stdout.write("\n");
-    };
-
-    const onData = (chunk) => {
-      const text = chunk.toString("utf8");
-      for (const char of text) {
-        if (char === "\u0003") {
-          cleanup();
-          reject(new Error("interactive init-repo cancelled"));
-          return;
-        }
-        if (char === "\r" || char === "\n") {
-          cleanup();
-          resolve(value.trim());
-          return;
-        }
-        if (char === "\u007f") {
-          value = value.slice(0, -1);
-          continue;
-        }
-        value += char;
-      }
-    };
-
-    if (typeof stdin.setRawMode === "function") {
-      stdin.setRawMode(true);
-    }
-    stdin.on("data", onData);
-  });
+function printEnvCapabilities(stdout, defaults) {
+  stdout.write("Environment check\n");
+  stdout.write(`  .env GitHub token: ${defaults.githubToken ? "found" : "missing"}\n`);
+  stdout.write(`  .env target repo: ${defaults.repo ? defaults.repo : "missing"}\n`);
+  stdout.write(`  .env database URL: ${defaults.databaseUrl ? "found" : "missing"}\n`);
+  stdout.write(
+    `  .env embeddings: ${defaults.embeddingMode ? defaults.embeddingMode : "not configured"}\n\n`
+  );
 }

package/lib/repo-init.js

@@ -28,6 +28,7 @@ export function initializeKnowledgeRepo({
   const normalizedLayout = normalizeKnowledgeLayout(layout);
   const docsRootRelative = docsRootForLayout(normalizedLayout);
   const files = new Map([
+    [".env.example", renderDotEnvExample()],
     [".github/ISSUE_TEMPLATE/config.yml", renderIssueConfig()],
     [".github/ISSUE_TEMPLATE/knowledge-document.md", renderIssueTemplate({ docsRootRelative })],
     [".github/workflows/kb-issue-to-pr.yml", renderIssueToPrWorkflow({ docsRootRelative })],
@@ -360,6 +361,21 @@ function renderIssueConfig() {
   return ["blank_issues_enabled: false", ""].join("\n");
 }
 
+function renderDotEnvExample() {
+  return [
+    "# Copy this file to .env and fill in the values you want to use locally.",
+    "KB_GITHUB_REPO=owner/repo",
+    "GITHUB_TOKEN=",
+    "KB_DATABASE_URL=postgresql://kb:kb@localhost:5432/kb",
+    "KB_EMBEDDING_MODE=local-hash",
+    "# KB_EMBEDDING_API_URL=https://your-embeddings-host/v1/embeddings",
+    "# KB_EMBEDDING_MODEL=BAAI/bge-m3",
+    "# KB_EMBEDDING_API_KEY=",
+    "# KB_DB_CONNECT_TIMEOUT_MS=20000",
+    "# KB_REPO_AUTOMATION_TOKEN="
+  ].join("\n");
+}
+
 function renderIssueTemplate({ docsRootRelative }) {
   return [
     "---",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nzpr/kb",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Knowledge base CLI for proposing, publishing, and querying curated agent knowledge.",
   "repository": {
     "type": "git",