@gitset-dev/cli 2.4.1 → 2.4.3

package/README.md

@@ -87,6 +87,41 @@ Local tools (no AI):
 Common flags: `--provider` `--model` `--yes` `--print` `--json`. Run
 `gitset help <command>` for everything else.
 
+## Knowledge Mapper
+
+`gitset knowledge` builds and maintains `docs/gitset-knowledge/` — a
+structured, always-current map of your codebase (architecture, module
+boundaries, commands, dependency graph) that both developers and AI coding
+agents can read before touching your code. It's generated from your source
+code, manifests, and CI configuration — never from your existing prose docs,
+so it can't inherit their drift.
+
+```sh
+gitset knowledge init       # scaffold optional .gitset-knowledge.json (include/exclude globs)
+gitset knowledge scan       # zero AI calls — discovers files, prints the plan + exact cost estimate
+gitset knowledge generate   # shows the estimate again, asks to confirm, then writes the knowledge base
+gitset knowledge update     # incremental — only changed modules (and their direct importers) are re-summarized
+gitset knowledge automate   # writes a GitHub Actions workflow that runs `update` in CI and opens a review PR
+```
+
+It's a six-stage local pipeline (Discover → Map → Summarize → Plan → Write →
+Validate): Discover and Map walk the repository and build an import graph
+with zero AI calls; only Summarize and Write touch your configured provider
+— there's no separate "default model" for this tool, it uses whatever you
+picked with `gitset config`; and a deterministic Validate pass checks every
+generated link, command, and script before anything is written to disk.
+Secrets are redacted locally before any file content is sent, and prose
+docs / test file bodies are listed structurally but never sent at all.
+
+`gitset knowledge automate` needs "Allow GitHub Actions to create and
+approve pull requests" enabled (**Settings > Actions > General > Workflow
+permissions**) for the update PR to open. It detects this automatically and
+offers to enable it via the GitHub API — asked first, like everything else
+in this command. If you decline, or the API call fails (no admin access, an
+org policy locking the setting), the scheduled update still runs and
+commits safely; only the review-PR step fails, and the workflow run shows
+that failure clearly rather than hide it.
+
 ## Templates
 
 Define your commit style, issue structure, PR format, README skeleton, or

package/lib/knowledge/ci.js

@@ -59,6 +59,16 @@ function buildKnowledgeWorkflow({ mode, provider, envKey, model, defaultBranch =
     '# permissions. Without it, the update still commits and pushes',
     '# safely, but opening the review PR fails and this job reports it',
     '# as a failure so it is never silently missed.',
+    '#',
+    '# If your organization enforces that setting off and it cannot be',
+    '# changed (the checkbox is greyed out even at the org level), add an',
+    '# optional repository secret GITSET_PR_TOKEN — a personal access',
+    '# token (classic: repo scope; fine-grained: Pull requests write) —',
+    '# and this workflow uses it instead of the default token, which is',
+    "# the standard workaround: an organization's PR-creation restriction",
+    '# applies to the auto-generated Actions token, not to a real PAT.',
+    '# No workflow changes needed after adding it — the next run picks it',
+    '# up automatically.',
     ...buildTrigger(mode, defaultBranch),
     'permissions:',
     '  contents: write',
@@ -81,7 +91,7 @@ function buildKnowledgeWorkflow({ mode, provider, envKey, model, defaultBranch =
     `        run: ${updateCmd}`,
     '      - name: Open a PR when the knowledge base changed',
     '        env:',
-    '          GH_TOKEN: ${{ github.token }}',
+    '          GH_TOKEN: ${{ secrets.GITSET_PR_TOKEN || github.token }}',
     '        run: |',
     '          if git diff --quiet -- docs/gitset-knowledge AGENTS.md; then',
     '            echo "Knowledge base already up to date."',
@@ -101,7 +111,7 @@ function buildKnowledgeWorkflow({ mode, provider, envKey, model, defaultBranch =
     '            echo "$PR_OUTPUT"',
     '          else',
     '            echo "$PR_OUTPUT"',
-    '            echo "::error::Could not open the pull request automatically (the branch and commit ARE safely pushed — no work was lost). This is usually because \'Allow GitHub Actions to create and approve pull requests\' is disabled for this repository: enable it under Settings > Actions > General > Workflow permissions, then either re-run this workflow or open the PR yourself: https://github.com/${{ github.repository }}/pull/new/gitset/knowledge-update"',
+    '            echo "::error::Could not open the pull request automatically (the branch and commit ARE safely pushed — no work was lost). Try, in order: (1) enable \'Allow GitHub Actions to create and approve pull requests\' under Settings > Actions > General > Workflow permissions; (2) if that checkbox is greyed out, your organization enforces it off — add a repository secret named GITSET_PR_TOKEN with a personal access token (repo scope) and re-run, no workflow change needed; (3) open the PR yourself: https://github.com/${{ github.repository }}/pull/new/gitset/knowledge-update"',
     '            exit 1',
     '          fi',
     '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitset-dev/cli",
-  "version": "2.4.1",
+  "version": "2.4.3",
   "description": "Gitset CLI — drafts commits, PRs, issues, READMEs and release notes with your own AI key. Fully local: your code and keys never touch a Gitset server. Draft. Refine. Ship.",
   "type": "commonjs",
   "bin": {

package/src/commands/knowledge.js

@@ -492,6 +492,40 @@ async function runUpdate(rootDir, argv) {
   }
 }
 
+function ghApiJson(args) {
+  try {
+    const out = execFileSync('gh', ['api', ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return JSON.parse(out);
+  } catch {
+    return null;
+  }
+}
+
+async function ensurePrPermission(repo, argv) {
+  if (!repo.includes('/')) return 'unknown';
+  const current = ghApiJson([`/repos/${repo}/actions/permissions/workflow`]);
+  if (!current) return 'unknown';
+  if (current.can_approve_pull_request_reviews) return 'already-enabled';
+
+  log('\n"Allow GitHub Actions to create and approve pull requests" is currently OFF for this repository. The update step will still run and commit safely without it — only opening the review PR will fail.', 'yellow');
+  const proceed = await confirmOrAbort('Enable it now via the GitHub API? (only this one setting changes)', argv);
+  if (!proceed) return 'declined';
+
+  try {
+    execFileSync('gh', [
+      'api', '--method', 'PUT', `/repos/${repo}/actions/permissions/workflow`,
+      '-f', `default_workflow_permissions=${current.default_workflow_permissions}`,
+      '-F', 'can_approve_pull_request_reviews=true',
+    ], { stdio: 'pipe' });
+    log('Enabled — CI will be able to open the review PR.', 'green');
+    return 'enabled';
+  } catch {
+    log('Could not change it automatically — you may not have admin access on this repo, or an organization policy locks this setting (if it appears greyed out in the GitHub UI at both the repo and org level, that\'s a hard enforcement you cannot toggle either way).', 'yellow');
+    log('Workaround: add a repository secret named GITSET_PR_TOKEN with a personal access token (repo scope). It is not subject to the organization\'s Actions PR-creation restriction, and the workflow picks it up automatically — no need to re-run automate.', 'dim');
+    return 'failed';
+  }
+}
+
 async function runAutomate(rootDir, argv) {
   let cfg;
   try {
@@ -558,6 +592,8 @@ async function runAutomate(rootDir, argv) {
   log(`\nWrote ${km.WORKFLOW_PATH}.`, 'green');
 
   const repo = repoLabel(rootDir);
+  const prPermission = await ensurePrPermission(repo, argv);
+
   log('\nNext steps:', 'cyan');
   log(`  1. Add the repository secret ${envKey} with your ${cfg.provider} API key:`, 'reset');
   if (repo.includes('/')) {
@@ -565,13 +601,20 @@ async function runAutomate(rootDir, argv) {
   } else {
     log('     GitHub repo > Settings > Secrets and variables > Actions', 'dim');
   }
-  log('  2. Enable "Allow GitHub Actions to create and approve pull requests" (required for the update PR):', 'reset');
-  if (repo.includes('/')) {
-    log(`     https://github.com/${repo}/settings/actions`, 'dim');
+  if (prPermission === 'enabled' || prPermission === 'already-enabled') {
+    log('  2. "Allow GitHub Actions to create and approve pull requests" is already on — the update PR step is ready.', 'reset');
   } else {
-    log('     GitHub repo > Settings > Actions > General > Workflow permissions', 'dim');
+    log('  2. Enable "Allow GitHub Actions to create and approve pull requests" (required for the update PR):', 'reset');
+    if (repo.includes('/')) {
+      log(`     https://github.com/${repo}/settings/actions`, 'dim');
+    } else {
+      log('     GitHub repo > Settings > Actions > General > Workflow permissions', 'dim');
+    }
+    log('     Without this, the update still runs and commits safely — only opening the review PR fails, and the workflow run will show that failure clearly rather than hide it.', 'dim');
+    if (prPermission === 'failed') {
+      log('     If that checkbox is greyed out even at the organization level, it is enforced off and cannot be toggled: add a repository secret named GITSET_PR_TOKEN with a personal access token (repo scope) instead — the workflow uses it automatically, no changes needed.', 'dim');
+    }
   }
-  log('     Without this, the update still runs and commits safely — only opening the review PR fails, and the workflow run will show that failure clearly rather than hide it.', 'dim');
   log('  3. Make sure the knowledge base itself is committed (gitset knowledge generate, then commit docs/gitset-knowledge/ and AGENTS.md).', 'reset');
   log('  4. Commit and push the workflow file.', 'reset');
   log('\nWhen mapped source changes land, CI opens a PR on branch gitset/knowledge-update — you review it like any docs change. Runs with no mapped changes make zero AI calls.', 'dim');