@nzpr/kb 0.1.2 → 0.1.4

package/README.md

@@ -24,6 +24,7 @@ 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.
+  Use `--layout repo-root` when this repository is itself the KB.
 
 - `kb create --title TEXT --text TEXT`
   Propose a new knowledge document or a substantial update.
@@ -102,6 +103,13 @@ If you want the CLI to walk you through setup and tell you what to do next:
 kb init-repo --interactive
 ```
 
+Layout options:
+
+- `--layout repo-root` puts documents in `docs/`
+- `--layout nested-kb` puts documents in `kb/docs/`
+
+For a dedicated knowledge repository, prefer `--layout repo-root`.
+
 Or bootstrap and configure it in one step:
 
 ```bash
@@ -120,12 +128,13 @@ 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.
 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`.
+4. Materialize it into the configured docs directory.
+5. After merge, that repo's CI runs `kb publish` against that docs directory.
 
 `kb init-repo` is safe to rerun. It reports bootstrap status for:
 
 - local scaffold creation
+- knowledge document layout selection
 - database preflight and schema initialization
 - GitHub repo labels, variables, and secrets
 
@@ -185,7 +194,7 @@ 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 publish --docs-root ./docs
 kb catalog --json
 kb search "deployment rule"
 ```
@@ -215,13 +224,13 @@ The package is published as `@nzpr/kb`.
 
 ## 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:
+The knowledge-authority repo should install this package in CI and use it to sync its configured docs directory into the vector database. For a dedicated KB repo with `--layout repo-root`, that directory is `docs/`:
 
 ```bash
 npm install -g @nzpr/kb
 export KB_GITHUB_REPO=owner/repo
 export GITHUB_TOKEN=...
-kb publish --docs-root ./kb/docs
+kb publish --docs-root ./docs
 ```
 
 Or scaffold that repo first:

package/lib/cli.js

@@ -65,6 +65,7 @@ export async function main(argv) {
           ? await collectInitRepoInteractiveOptions({ flags })
           : {
               targetDir: flags.dir ?? process.cwd(),
+              layout: flags.layout ?? "nested-kb",
               repo: flags.repo ?? resolveGitHubRepository(),
               databaseUrl: flags["database-url"] ?? process.env.KB_DATABASE_URL ?? null,
               embeddingMode: flags["embedding-mode"] ?? process.env.KB_EMBEDDING_MODE ?? null,
@@ -78,8 +79,9 @@ export async function main(argv) {
             };
         const result = await bootstrapKnowledgeRepo({
           targetDir: initRepoOptions.targetDir,
+          layout: initRepoOptions.layout,
           repo: initRepoOptions.repo,
-          githubToken: process.env.GITHUB_TOKEN ?? null,
+          githubToken: initRepoOptions.githubToken ?? process.env.GITHUB_TOKEN ?? null,
           databaseUrl: initRepoOptions.databaseUrl,
           embeddingMode: initRepoOptions.embeddingMode,
           embeddingApiUrl: initRepoOptions.embeddingApiUrl,
@@ -89,6 +91,7 @@ export async function main(argv) {
           repoAutomationToken: initRepoOptions.repoAutomationToken
         });
         console.log(`initialized knowledge repo scaffold in ${result.root}`);
+        console.log(`knowledge documents will live in ${result.docsRootRelative}/`);
         for (const relativePath of result.created) {
           console.log(`created ${relativePath}`);
         }
@@ -246,7 +249,7 @@ function printHelp() {
   console.log(`usage: kb <command> [options]
 
 commands:
-  init-repo [--interactive] [--dir PATH] [--repo OWNER/REPO]
+  init-repo [--interactive] [--layout repo-root|nested-kb] [--dir PATH] [--repo OWNER/REPO]
   create --title TEXT --text TEXT [--path RELATIVE_PATH]
   search <query>
   ask <question>
@@ -271,7 +274,7 @@ search options:
 function printCommandHelp(command) {
   const commandHelp = {
     "init-repo":
-      "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.",
+      "usage: kb init-repo [--interactive] [--layout repo-root|nested-kb] [--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`,
@@ -327,7 +330,7 @@ async function requirePublishAccess({ repo, token, apiBaseUrl }) {
 
 function printRepoConfiguration(configuration) {
   console.log("");
-  console.log("configure the knowledge repo with these GitHub settings:");
+  console.log("configuration reference:");
   console.log("");
   console.log("required secrets:");
   for (const entry of configuration.requiredSecrets) {
@@ -351,7 +354,10 @@ function printRepoConfiguration(configuration) {
 
 function printInitRepoStatus(result) {
   console.log("");
-  console.log("bootstrap status:");
+  console.log("summary:");
+  console.log(`  docs layout: ${result.docsRootRelative}/`);
+  console.log(`  files created: ${result.created.length}`);
+  console.log(`  files kept: ${result.skipped.length}`);
   printInitRepoDatabaseStatus(result.database);
   printInitRepoGitHubStatus(result.github);
 }
@@ -373,6 +379,11 @@ function printInitRepoDatabaseStatus(database) {
 function printInitRepoGitHubStatus(github) {
   if (github.status === "configured") {
     console.log(`  github: configured ${github.repo}`);
+    if (github.actions) {
+      console.log(
+        `  actions: enabled=${github.actions.enabled} workflow_permissions=${github.actions.defaultWorkflowPermissions} pr_creation=${github.actions.canApprovePullRequestReviews}`
+      );
+    }
     console.log(`  labels: ${github.labels.join(", ")}`);
     if (github.secrets.length) {
       console.log(`  secrets: ${github.secrets.join(", ")}`);
@@ -407,9 +418,9 @@ function printInitRepoNextStep(result) {
 
 function printInitRepoChecklist(result) {
   console.log("");
-  console.log("what to do next:");
+  console.log("next steps:");
   if (result.created.length || result.skipped.length) {
-    console.log("  1. commit and push the scaffolded knowledge repo files");
+    console.log(`  1. commit and push the scaffolded knowledge repo files, including ${result.docsRootRelative}/`);
   }
   if (result.github.status !== "configured") {
     console.log("  2. make sure the target repo exists and rerun with --repo once GitHub setup is ready");
@@ -419,4 +430,14 @@ function printInitRepoChecklist(result) {
   }
   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");
+  console.log("");
+  console.log("done in this run:");
+  if (result.created.length) {
+    console.log(`  created: ${result.created.join(", ")}`);
+  } else {
+    console.log("  created: no new files");
+  }
+  if (result.skipped.length) {
+    console.log(`  kept: ${result.skipped.join(", ")}`);
+  }
 }

package/lib/init-repo-interactive.js

@@ -1,4 +1,6 @@
 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";
@@ -9,7 +11,8 @@ export async function collectInitRepoInteractiveOptions({
   cwd = process.cwd(),
   stdin = defaultStdin,
   stdout = defaultStdout,
-  prompter = null
+  prompter = null,
+  auth = defaultInteractiveGitHubAuth
 }) {
   if (!prompter && (!stdin.isTTY || !stdout.isTTY)) {
     throw new Error("interactive init-repo requires a TTY; rerun in a terminal or pass flags directly");
@@ -20,8 +23,8 @@ export async function collectInitRepoInteractiveOptions({
   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");
+    stdout.write("KB Init Wizard\n");
+    stdout.write("This walkthrough prepares the knowledge repo and can wire GitHub and database setup now.\n\n");
 
     const targetDir = path.resolve(
       cwd,
@@ -29,6 +32,7 @@ export async function collectInitRepoInteractiveOptions({
         validate: requireValue
       })
     );
+    const layout = await askKnowledgeLayout(prompt, targetDir, defaults.layout);
 
     const configureRepo = await prompt.askConfirm(
       "configure the GitHub repo now",
@@ -40,6 +44,15 @@ export async function collectInitRepoInteractiveOptions({
       repo = await prompt.askText("target GitHub repo (OWNER/REPO)", defaults.repo, {
         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;
+        }
+      }
     }
 
     const verifyDatabase = await prompt.askConfirm(
@@ -93,7 +106,7 @@ export async function collectInitRepoInteractiveOptions({
     let repoAutomationToken = null;
     if (configureRepo) {
       const useAutomationToken = await prompt.askConfirm(
-        "set a dedicated repo automation token secret",
+        "use a custom automation token instead of the default GitHub Actions token",
         Boolean(defaults.repoAutomationToken)
       );
       if (useAutomationToken) {
@@ -104,9 +117,10 @@ export async function collectInitRepoInteractiveOptions({
       }
     }
 
-    stdout.write("\nplan:\n");
-    stdout.write(`  local scaffold: ${targetDir}\n`);
-    stdout.write(`  github repo setup: ${repo ? repo : "skip for now"}\n`);
+    stdout.write("\nPlan\n");
+    stdout.write(`  target directory: ${targetDir}\n`);
+    stdout.write(`  document layout: ${layout === "repo-root" ? "docs/" : "kb/docs/"}\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`
@@ -119,7 +133,9 @@ export async function collectInitRepoInteractiveOptions({
 
     return {
       targetDir,
+      layout,
       repo,
+      githubToken: defaults.githubToken || null,
       databaseUrl,
       embeddingMode,
       embeddingApiUrl,
@@ -136,6 +152,9 @@ export async function collectInitRepoInteractiveOptions({
 export function buildInitRepoDefaults({ flags = {}, env = process.env, cwd = process.cwd() }) {
   return {
     targetDir: flags.dir ?? cwd,
+    layout:
+      flags.layout ?? inferDefaultKnowledgeLayout(flags.dir ? path.resolve(cwd, flags.dir) : cwd),
+    githubToken: env.GITHUB_TOKEN ?? "",
     repo: flags.repo ?? resolveGitHubRepository(env) ?? "",
     databaseUrl: flags["database-url"] ?? env.KB_DATABASE_URL ?? "",
     embeddingMode: flags["embedding-mode"] ?? env.KB_EMBEDDING_MODE ?? "",
@@ -149,6 +168,31 @@ export function buildInitRepoDefaults({ flags = {}, env = process.env, cwd = pro
   };
 }
 
+async function askKnowledgeLayout(prompt, targetDir, defaultLayout) {
+  const useRepoRoot = await prompt.askConfirm(
+    "store documents at repo root docs/ (recommended when this repo is the knowledge base)",
+    defaultLayout === "repo-root"
+  );
+  if (useRepoRoot) {
+    return "repo-root";
+  }
+  if (!fs.existsSync(targetDir) || fs.readdirSync(targetDir).length === 0) {
+    return "nested-kb";
+  }
+  return "nested-kb";
+}
+
+function inferDefaultKnowledgeLayout(targetDir) {
+  const root = path.resolve(targetDir);
+  if (fs.existsSync(path.join(root, "docs"))) {
+    return "repo-root";
+  }
+  if (fs.existsSync(path.join(root, "kb", "docs"))) {
+    return "nested-kb";
+  }
+  return "repo-root";
+}
+
 function createReadlinePrompter({ stdin, stdout }) {
   const rl = readline.createInterface({
     input: stdin,
@@ -220,3 +264,45 @@ function emptyToNull(value) {
   const normalized = String(value ?? "").trim();
   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("The wizard can open GitHub CLI login in your browser and then continue.\n");
+  const loginNow = await prompt.askConfirm("authorize GitHub CLI now", true);
+  if (!loginNow) {
+    return null;
+  }
+
+  auth.login();
+  const token = auth.getToken();
+  if (token) {
+    stdout.write("GitHub CLI authentication is ready.\n");
+    return token;
+  }
+
+  throw new Error("GitHub authentication did not complete; rerun gh auth login or set GITHUB_TOKEN");
+}
+
+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"
+    });
+  }
+};

package/lib/repo-init.js

@@ -5,6 +5,8 @@ import { connect, initDb } from "./db.js";
 import { maskConnection } from "./cli-common.js";
 
 const PACKAGE_NAME = "@nzpr/kb";
+const REPO_ROOT_LAYOUT = "repo-root";
+const NESTED_KB_LAYOUT = "nested-kb";
 const LABELS = Object.freeze([
   {
     name: "kb-entry",
@@ -18,14 +20,19 @@ const LABELS = Object.freeze([
   }
 ]);
 
-export function initializeKnowledgeRepo({ targetDir = process.cwd() } = {}) {
+export function initializeKnowledgeRepo({
+  targetDir = process.cwd(),
+  layout = NESTED_KB_LAYOUT
+} = {}) {
   const root = path.resolve(targetDir);
+  const normalizedLayout = normalizeKnowledgeLayout(layout);
+  const docsRootRelative = docsRootForLayout(normalizedLayout);
   const files = new Map([
     [".github/ISSUE_TEMPLATE/config.yml", renderIssueConfig()],
-    [".github/ISSUE_TEMPLATE/knowledge-document.md", renderIssueTemplate()],
-    [".github/workflows/kb-issue-to-pr.yml", renderIssueToPrWorkflow()],
-    [".github/workflows/kb-publish.yml", renderPublishWorkflow()],
-    ["kb/docs/.gitkeep", ""]
+    [".github/ISSUE_TEMPLATE/knowledge-document.md", renderIssueTemplate({ docsRootRelative })],
+    [".github/workflows/kb-issue-to-pr.yml", renderIssueToPrWorkflow({ docsRootRelative })],
+    [".github/workflows/kb-publish.yml", renderPublishWorkflow({ docsRootRelative })],
+    [`${docsRootRelative}/.gitkeep`, ""]
   ]);
 
   const created = [];
@@ -44,6 +51,8 @@ export function initializeKnowledgeRepo({ targetDir = process.cwd() } = {}) {
 
   return {
     root,
+    layout: normalizedLayout,
+    docsRootRelative,
     created,
     skipped,
     configuration: buildConfigurationGuide()
@@ -52,6 +61,7 @@ export function initializeKnowledgeRepo({ targetDir = process.cwd() } = {}) {
 
 export async function bootstrapKnowledgeRepo({
   targetDir = process.cwd(),
+  layout = NESTED_KB_LAYOUT,
   repo = null,
   githubToken = null,
   databaseUrl = null,
@@ -64,7 +74,7 @@ export async function bootstrapKnowledgeRepo({
   runGitHubCommand = defaultRunGitHubCommand,
   verifyDatabaseReady = defaultVerifyDatabaseReady
 } = {}) {
-  const scaffold = initializeKnowledgeRepo({ targetDir });
+  const scaffold = initializeKnowledgeRepo({ targetDir, layout });
   const result = {
     ...scaffold,
     ok: true,
@@ -102,7 +112,8 @@ export async function bootstrapKnowledgeRepo({
       result.github = {
         status: "failed",
         repo,
-        error: "GITHUB_TOKEN is required when configuring a knowledge repo"
+        error:
+          "GITHUB_TOKEN is required when configuring a knowledge repo; set GITHUB_TOKEN or run gh auth login before rerunning"
       };
       return result;
     }
@@ -216,6 +227,11 @@ async function configureKnowledgeRepo({
   runGitHubCommand
 }) {
   await runGitHubCommand(["repo", "edit", repo, "--enable-issues"], { githubToken });
+  const actions = await ensureGitHubActionsPermissions({
+    repo,
+    githubToken,
+    runGitHubCommand
+  });
 
   for (const label of LABELS) {
     await runGitHubCommand(
@@ -249,12 +265,72 @@ async function configureKnowledgeRepo({
 
   return {
     repo,
+    actions,
     labels: LABELS.map((label) => label.name),
     secrets: [...secrets.keys()],
     variables: [...variables.keys()]
   };
 }
 
+async function ensureGitHubActionsPermissions({ repo, githubToken, runGitHubCommand }) {
+  const actionsPermissions = await runGitHubJson(
+    ["api", `repos/${repo}/actions/permissions`],
+    { githubToken, runGitHubCommand }
+  );
+
+  if (actionsPermissions.enabled === false) {
+    await runGitHubCommand(
+      [
+        "api",
+        "--method",
+        "PUT",
+        `repos/${repo}/actions/permissions`,
+        "-F",
+        "enabled=true",
+        "-f",
+        `allowed_actions=${actionsPermissions.allowed_actions ?? "all"}`
+      ],
+      { githubToken }
+    );
+  }
+
+  const workflowPermissions = await runGitHubJson(
+    ["api", `repos/${repo}/actions/permissions/workflow`],
+    { githubToken, runGitHubCommand }
+  );
+
+  if (
+    workflowPermissions.default_workflow_permissions !== "write" ||
+    workflowPermissions.can_approve_pull_request_reviews !== true
+  ) {
+    await runGitHubCommand(
+      [
+        "api",
+        "--method",
+        "PUT",
+        `repos/${repo}/actions/permissions/workflow`,
+        "-f",
+        "default_workflow_permissions=write",
+        "-F",
+        "can_approve_pull_request_reviews=true"
+      ],
+      { githubToken }
+    );
+  }
+
+  return {
+    enabled: true,
+    allowedActions: actionsPermissions.allowed_actions ?? "all",
+    defaultWorkflowPermissions: "write",
+    canApprovePullRequestReviews: true
+  };
+}
+
+async function runGitHubJson(args, { githubToken, runGitHubCommand }) {
+  const output = await runGitHubCommand(args, { githubToken });
+  return JSON.parse(output);
+}
+
 async function defaultVerifyDatabaseReady({ databaseUrl }) {
   const client = await connect(databaseUrl);
   try {
@@ -284,7 +360,7 @@ function renderIssueConfig() {
   return ["blank_issues_enabled: false", ""].join("\n");
 }
 
-function renderIssueTemplate() {
+function renderIssueTemplate({ docsRootRelative }) {
   return [
     "---",
     "name: Knowledge Base Document",
@@ -313,12 +389,12 @@ function renderIssueTemplate() {
     "",
     "1. Open the issue with this template.",
     "2. Review and edit the issue until the title and text are ready.",
-    "3. Add the `kb-approved` label to generate a PR that writes the Markdown file into `kb/docs/`.",
+    `3. Add the \`kb-approved\` label to generate a PR that writes the Markdown file into \`${docsRootRelative}/\`.`,
     ""
   ].join("\n");
 }
 
-function renderIssueToPrWorkflow() {
+function renderIssueToPrWorkflow({ docsRootRelative }) {
   return [
     "name: kb-issue-to-pr",
     "",
@@ -353,7 +429,7 @@ function renderIssueToPrWorkflow() {
     "",
     "      - name: Materialize approved issue",
     "        id: materialize",
-    '        run: kb-admin issue-to-doc --issue-event "$GITHUB_EVENT_PATH" --docs-root ./kb/docs',
+    `        run: kb-admin issue-to-doc --issue-event "$GITHUB_EVENT_PATH" --docs-root ./${docsRootRelative}`,
     "",
     "      - name: Create pull request",
     "        id: cpr",
@@ -382,7 +458,7 @@ function renderIssueToPrWorkflow() {
   ].join("\n");
 }
 
-function renderPublishWorkflow() {
+function renderPublishWorkflow({ docsRootRelative }) {
   return [
     "name: kb-publish",
     "",
@@ -391,7 +467,7 @@ function renderPublishWorkflow() {
     "    branches:",
     "      - main",
     "    paths:",
-    '      - "kb/docs/**"',
+    `      - "${docsRootRelative}/**"`,
     '      - ".github/workflows/**"',
     "  workflow_dispatch:",
     "",
@@ -432,7 +508,18 @@ function renderPublishWorkflow() {
     `        run: npm install -g ${PACKAGE_NAME}`,
     "",
     "      - name: Publish knowledge",
-    "        run: kb publish --docs-root ./kb/docs",
+    `        run: kb publish --docs-root ./${docsRootRelative}`,
     ""
   ].join("\n");
 }
+
+function normalizeKnowledgeLayout(layout) {
+  if (layout === REPO_ROOT_LAYOUT || layout === NESTED_KB_LAYOUT) {
+    return layout;
+  }
+  throw new Error(`unsupported init-repo layout: ${layout}`);
+}
+
+function docsRootForLayout(layout) {
+  return layout === REPO_ROOT_LAYOUT ? "docs" : "kb/docs";
+}

package/package.json

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