@nzpr/kb 0.1.3 → 0.1.5

package/lib/cli.js

@@ -81,7 +81,7 @@ export async function main(argv) {
           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,
@@ -330,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) {
@@ -354,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);
 }
@@ -376,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(", ")}`);
@@ -410,7 +418,7 @@ 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, including ${result.docsRootRelative}/`);
   }
@@ -422,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,5 +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";
@@ -10,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");
@@ -21,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,
@@ -42,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(
@@ -95,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) {
@@ -106,10 +117,10 @@ export async function collectInitRepoInteractiveOptions({
       }
     }
 
-    stdout.write("\nplan:\n");
-    stdout.write(`  local scaffold: ${targetDir}\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(`  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`
@@ -124,6 +135,7 @@ export async function collectInitRepoInteractiveOptions({
       targetDir,
       layout,
       repo,
+      githubToken: defaults.githubToken || null,
       databaseUrl,
       embeddingMode,
       embeddingApiUrl,
@@ -142,6 +154,7 @@ export function buildInitRepoDefaults({ flags = {}, env = process.env, cwd = pro
     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 ?? "",
@@ -189,6 +202,9 @@ 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);
     },
@@ -232,6 +248,20 @@ 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";
 }
@@ -251,3 +281,109 @@ 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("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);
+  });
+}

package/lib/repo-init.js

@@ -112,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;
     }
@@ -226,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(
@@ -259,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 {

package/package.json

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