@nzpr/kb 0.1.8 → 0.1.10

package/README.md

@@ -176,15 +176,18 @@ 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.
+Publishing is allowed when the provided `GITHUB_TOKEN` can read `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
+- set GitHub Actions workflow permissions to write and allow Actions to create PRs
 - 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
 
+For the GitHub setup step, that token must have repository admin access. A plain write token is not enough for Actions settings and repo secrets.
+
 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

package/lib/cli.js

@@ -322,10 +322,10 @@ async function requirePublishAccess({ repo, token, apiBaseUrl }) {
   if (!permissions) {
     return;
   }
-  if (permissions.admin || permissions.maintain || permissions.push) {
+  if (permissions.admin || permissions.maintain || permissions.push || permissions.triage || permissions.pull) {
     return;
   }
-  throw new Error(`GITHUB_TOKEN does not have write access to ${repo}`);
+  throw new Error(`GITHUB_TOKEN does not have repository access to ${repo}`);
 }
 
 function printRepoConfiguration(configuration) {
@@ -349,19 +349,31 @@ function printRepoConfiguration(configuration) {
   console.log("");
   console.log("publish workflow auth:");
   console.log("  KB_GITHUB_REPO is set automatically to github.repository in the scaffolded workflow");
-  console.log("  GITHUB_TOKEN is provided automatically by GitHub Actions and must have contents:write")
+  console.log("  GITHUB_TOKEN is provided automatically by GitHub Actions and only needs repository read access for publish");
+  console.log("  the token used for kb init-repo itself must have admin access if you want the CLI to configure repo Actions settings")
 }
 
 function printInitRepoStatus(result) {
   console.log("");
-  console.log("summary:");
-  console.log(`  docs layout: ${result.docsRootRelative}/`);
-  console.log(`  files created: ${result.created.length}`);
-  console.log(`  files kept: ${result.skipped.length}`);
+  console.log("what happened:");
+  printInitRepoScaffoldStatus(result);
   printInitRepoDatabaseStatus(result.database);
   printInitRepoGitHubStatus(result.github);
 }
 
+function printInitRepoScaffoldStatus(result) {
+  const reusedOnly = !result.created.length && result.skipped.length > 0;
+  if (reusedOnly) {
+    console.log(`  scaffold: reused the existing knowledge repo files in ${result.root}`);
+  } else if (result.created.length) {
+    console.log(`  scaffold: created or updated the knowledge repo scaffold in ${result.root}`);
+  } else {
+    console.log(`  scaffold: nothing changed in ${result.root}`);
+  }
+  console.log(`  docs: documents live in ${result.docsRootRelative}/`);
+  console.log(`  files: created=${result.created.length} kept=${result.skipped.length}`);
+}
+
 function printInitRepoDatabaseStatus(database) {
   if (database.status === "verified") {
     console.log(
@@ -370,10 +382,16 @@ function printInitRepoDatabaseStatus(database) {
     return;
   }
   if (database.status === "failed") {
-    console.log(`  database: failed - ${formatCliError(new Error(database.error))}`);
+    const target = database.target ? ` ${database.target}` : "";
+    console.log(`  database: attempted verification${target}`);
+    console.log(`  database result: failed - ${formatCliError(new Error(database.error))}`);
+    console.log("  database effect: no schema changes were confirmed");
     return;
   }
-  console.log(`  database: pending - ${database.message}`);
+  if (database.target) {
+    console.log(`  database: pending verification for ${database.target}`);
+  }
+  console.log(`  database result: pending - ${database.message}`);
 }
 
 function printInitRepoGitHubStatus(github) {
@@ -381,36 +399,52 @@ function printInitRepoGitHubStatus(github) {
     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}`
+        `  github actions: enabled=${github.actions.enabled} workflow_permissions=${github.actions.defaultWorkflowPermissions} pr_creation=${github.actions.canApprovePullRequestReviews}`
       );
     }
-    console.log(`  labels: ${github.labels.join(", ")}`);
+    console.log(`  github labels: ${github.labels.join(", ")}`);
     if (github.secrets.length) {
-      console.log(`  secrets: ${github.secrets.join(", ")}`);
+      console.log(`  github secrets: ${github.secrets.join(", ")}`);
     }
     if (github.variables.length) {
-      console.log(`  variables: ${github.variables.join(", ")}`);
+      console.log(`  github variables: ${github.variables.join(", ")}`);
     }
     return;
   }
   if (github.status === "failed") {
-    console.log(`  github: failed - ${github.error}`);
+    const repo = github.repo ? ` ${github.repo}` : "";
+    console.log(`  github: attempted repo bootstrap${repo}`);
+    console.log(`  github result: failed - ${github.error}`);
     return;
   }
-  console.log(`  github: ${github.status} - ${github.message}`);
+  if (github.repo) {
+    console.log(`  github: pending bootstrap for ${github.repo}`);
+  }
+  console.log(`  github result: ${github.status} - ${github.message}`);
 }
 
 function printInitRepoNextStep(result) {
+  const failures = [];
+  if (result.database.status === "failed") {
+    failures.push("database verification failed");
+  }
+  if (result.github.status === "failed") {
+    failures.push("GitHub bootstrap failed");
+  }
+
   if (!result.ok) {
+    console.log("");
     console.log(
-      "next: fix the failed bootstrap step and rerun kb init-repo; rerunning is safe because the scaffold is idempotent"
+      `next: fix ${failures.join(" and ")} and rerun kb init-repo; rerunning is safe because the scaffold is idempotent`
     );
     return;
   }
   if (result.database.status === "verified" && result.github.status === "configured") {
+    console.log("");
     console.log("next: commit the scaffold in the knowledge repo, push it, and let that repo own KB publishing");
     return;
   }
+  console.log("");
   console.log(
     "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"
   );
@@ -419,25 +453,29 @@ function printInitRepoNextStep(result) {
 function printInitRepoChecklist(result) {
   console.log("");
   console.log("next steps:");
+  const steps = [];
   if (result.created.length || result.skipped.length) {
-    console.log(`  1. commit and push the scaffolded knowledge repo files, including ${result.docsRootRelative}/`);
+    steps.push(`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");
+    steps.push("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");
+    steps.push("rerun with --database-url once the target database is reachable");
   }
-  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");
+  steps.push("use kb create to open a proposal issue for the first knowledge entry");
+  steps.push("review the issue, add kb-approved, merge the generated PR, and let publish sync the live KB");
+  steps.forEach((step, index) => {
+    console.log(`  ${index + 1}. ${step}`);
+  });
   console.log("");
-  console.log("done in this run:");
+  console.log("changes in this run:");
   if (result.created.length) {
-    console.log(`  created: ${result.created.join(", ")}`);
+    console.log(`  created files: ${result.created.join(", ")}`);
   } else {
-    console.log("  created: no new files");
+    console.log("  created files: none");
   }
   if (result.skipped.length) {
-    console.log(`  kept: ${result.skipped.join(", ")}`);
+    console.log(`  kept existing files: ${result.skipped.join(", ")}`);
   }
 }

package/lib/init-repo-interactive.js

@@ -126,7 +126,7 @@ export async function collectInitRepoInteractiveOptions({
       `  embeddings config: ${embeddingMode === "bge-m3-openai" ? `${embeddingMode}/${embeddingModel}` : "skip for now"}\n`
     );
 
-    const proceed = await prompt.askConfirm("run init-repo with this plan", true);
+    const proceed = await prompt.askConfirm("proceed with initialization", true);
     if (!proceed) {
       throw new Error("interactive init-repo cancelled");
     }

package/lib/repo-init.js

@@ -79,11 +79,13 @@ export async function bootstrapKnowledgeRepo({
     ...scaffold,
     ok: true,
     database: {
+      target: databaseUrl ? maskConnection(databaseUrl) : null,
       status: "pending",
       message:
         "rerun with --database-url URL or KB_DATABASE_URL to verify the target database and initialize the schema"
     },
     github: {
+      repo,
       status: "pending",
       message:
         "rerun with --repo OWNER/REPO and GITHUB_TOKEN to configure labels, repo settings, and GitHub secrets or variables"
@@ -94,12 +96,14 @@ export async function bootstrapKnowledgeRepo({
     try {
       const database = await verifyDatabaseReady({ databaseUrl });
       result.database = {
+        target: maskConnection(databaseUrl),
         status: "verified",
         ...database
       };
     } catch (error) {
       result.ok = false;
       result.database = {
+        target: maskConnection(databaseUrl),
         status: "failed",
         error: String(error?.message ?? error)
       };
@@ -117,15 +121,6 @@ export async function bootstrapKnowledgeRepo({
       };
       return result;
     }
-
-    if (result.database.status === "failed") {
-      result.github = {
-        status: "skipped",
-        repo,
-        message: "database preflight failed, so repo secrets and variables were not changed"
-      };
-      return result;
-    }
     const secrets = new Map();
     const variables = new Map();
 
@@ -226,6 +221,19 @@ async function configureKnowledgeRepo({
   variables,
   runGitHubCommand
 }) {
+  const repository = await fetchGitHubRepositoryMetadata({
+    repo,
+    githubToken,
+    runGitHubCommand
+  });
+  const permissions = repository.permissions ?? null;
+
+  if (!permissions?.admin) {
+    throw new Error(
+      `GITHUB_TOKEN must have admin access to ${repo} so init-repo can configure Actions workflow permissions, PR creation, labels, and repo secrets`
+    );
+  }
+
   await runGitHubCommand(["repo", "edit", repo, "--enable-issues"], { githubToken });
   const actions = await ensureGitHubActionsPermissions({
     repo,
@@ -275,7 +283,11 @@ async function configureKnowledgeRepo({
 async function ensureGitHubActionsPermissions({ repo, githubToken, runGitHubCommand }) {
   const actionsPermissions = await runGitHubJson(
     ["api", `repos/${repo}/actions/permissions`],
-    { githubToken, runGitHubCommand }
+    {
+      githubToken,
+      runGitHubCommand,
+      notFoundMessage: buildActionsAdminError(repo)
+    }
   );
 
   if (actionsPermissions.enabled === false) {
@@ -296,7 +308,11 @@ async function ensureGitHubActionsPermissions({ repo, githubToken, runGitHubComm
 
   const workflowPermissions = await runGitHubJson(
     ["api", `repos/${repo}/actions/permissions/workflow`],
-    { githubToken, runGitHubCommand }
+    {
+      githubToken,
+      runGitHubCommand,
+      notFoundMessage: buildActionsAdminError(repo)
+    }
   );
 
   if (
@@ -326,9 +342,28 @@ async function ensureGitHubActionsPermissions({ repo, githubToken, runGitHubComm
   };
 }
 
-async function runGitHubJson(args, { githubToken, runGitHubCommand }) {
-  const output = await runGitHubCommand(args, { githubToken });
-  return JSON.parse(output);
+async function fetchGitHubRepositoryMetadata({ repo, githubToken, runGitHubCommand }) {
+  return runGitHubJson(["api", `repos/${repo}`], {
+    githubToken,
+    runGitHubCommand
+  });
+}
+
+function buildActionsAdminError(repo) {
+  return `GitHub token could not read or update Actions settings for ${repo}; use a token with repository admin access and rerun init-repo`;
+}
+
+async function runGitHubJson(args, { githubToken, runGitHubCommand, notFoundMessage = null }) {
+  try {
+    const output = await runGitHubCommand(args, { githubToken });
+    return JSON.parse(output);
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    if (notFoundMessage && /404|Not Found/i.test(message)) {
+      throw new Error(notFoundMessage);
+    }
+    throw error;
+  }
 }
 
 async function defaultVerifyDatabaseReady({ databaseUrl }) {
@@ -475,7 +510,7 @@ function renderPublishWorkflow({ docsRootRelative }) {
     "  publish:",
     "    runs-on: ubuntu-latest",
     "    permissions:",
-    "      contents: write",
+    "      contents: read",
     "    concurrency:",
     "      group: kb-publish",
     "      cancel-in-progress: false",

package/package.json

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