@gitset-dev/cli 2.4.2 → 2.5.0

package/README.md

@@ -114,10 +114,21 @@ 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 under the repo's **Settings > Actions >
-General > Workflow permissions** — without it, the scheduled update still
-runs and commits safely, but the review-PR step fails, and the workflow run
-will show that failure clearly rather than hide it.
+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.
+
+Some organizations enforce that setting off with no repo-level override at
+all — the checkbox greys out even on the org's own settings page. For that
+case, add a repository secret named `GITSET_PR_TOKEN` with a personal
+access token (classic: `repo` scope; fine-grained: Pull requests write).
+It's not subject to that organization-wide Actions restriction, and the
+generated workflow picks it up automatically — no need to re-run `automate`
+or touch the workflow file.
 
 ## Templates
 

package/index.js

@@ -132,9 +132,11 @@ before anything reaches your AI provider.
   generate         full run (always shows the estimate and asks first)
   update           incremental: re-summarizes only changed modules
   automate         write a GitHub Actions workflow that runs update in CI
-                   and opens a PR when docs change (always asks first)
+                   (commits directly by default; --sync pr for review PRs,
+                   with the required access set up for you — always asks first)
   --since <ref>    update selector via git diff instead of content hashes
   --mode <m>       automate trigger: push | releases | weekly
+  --sync <s>       automate apply style: commit (default) | pr
   --provider <p>   override the default provider for this run
   --model <m>      override the model
   --yes            skip confirmations (CI)`,

package/lib/knowledge/ci.js

@@ -8,6 +8,11 @@ const MODES = {
   weekly: 'weekly (Mondays 06:00 UTC)',
 };
 
+const SYNC_MODES = {
+  commit: 'commit updates directly to the default branch (zero setup, works everywhere)',
+  pr: 'open a review pull request for each update',
+};
+
 function buildTrigger(mode, defaultBranch) {
   if (mode === 'push') {
     return [
@@ -41,9 +46,97 @@ function buildTrigger(mode, defaultBranch) {
   throw new Error(`Unknown automation mode "${mode}". One of: ${Object.keys(MODES).join(', ')}`);
 }
 
-function buildKnowledgeWorkflow({ mode, provider, envKey, model, defaultBranch = 'main' }) {
+function commitModeLines(defaultBranch) {
+  return {
+    header: [
+      '#',
+      `# Updates are committed directly to ${defaultBranch} using the built-in`,
+      '# Actions token — no extra permissions, tokens, or settings needed.',
+      "# It cannot re-trigger itself: GitHub never runs workflows for pushes",
+      '# made with the built-in token, and the path filters ignore these',
+      '# files anyway.',
+    ],
+    permissions: [
+      'permissions:',
+      '  contents: write',
+    ],
+    checkoutWith: [
+      '        with:',
+      `          ref: ${defaultBranch}`,
+    ],
+    finalStep: [
+      '      - name: Commit the updated knowledge base',
+      '        run: |',
+      '          if git diff --quiet -- docs/gitset-knowledge AGENTS.md; then',
+      '            echo "Knowledge base already up to date."',
+      '            exit 0',
+      '          fi',
+      '          git config user.name "github-actions[bot]"',
+      '          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"',
+      '          git add docs/gitset-knowledge AGENTS.md',
+      '          git commit -m "docs: refresh knowledge base"',
+      `          git push origin ${defaultBranch} || (git pull --rebase origin ${defaultBranch} && git push origin ${defaultBranch})`,
+      `          echo "Knowledge base refreshed directly on ${defaultBranch}."`,
+    ],
+  };
+}
+
+function prModeLines() {
+  return {
+    header: [
+      '#',
+      '# PR mode needs ONE of the following (gitset knowledge automate sets',
+      '# this up for you):',
+      '#   a. "Allow GitHub Actions to create and approve pull requests"',
+      '#      enabled under Settings > Actions > General, OR',
+      '#   b. a repository secret GITSET_PR_TOKEN holding a GitHub token',
+      '#      that can open pull requests (used automatically when present;',
+      '#      not subject to organization-level Actions restrictions).',
+      '# Without either, the update still commits and pushes its branch',
+      '# safely — only opening the review PR fails, and this job reports',
+      '# that as a failure so it is never silently missed.',
+    ],
+    permissions: [
+      'permissions:',
+      '  contents: write',
+      '  pull-requests: write',
+    ],
+    checkoutWith: [],
+    finalStep: [
+      '      - name: Open a PR when the knowledge base changed',
+      '        env:',
+      '          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."',
+      '            exit 0',
+      '          fi',
+      '          git config user.name "github-actions[bot]"',
+      '          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"',
+      '          git switch -c gitset/knowledge-update',
+      '          git add docs/gitset-knowledge AGENTS.md',
+      '          git commit -m "docs: refresh knowledge base"',
+      '          git push -f origin gitset/knowledge-update',
+      '          echo "Committed and pushed gitset/knowledge-update — this work is now safe on GitHub regardless of the next step."',
+      '          if PR_OUTPUT=$(gh pr create --title "docs: refresh knowledge base" --body "Automated incremental update by [Gitset](https://gitset.dev) Knowledge Mapper. Only changed modules were re-analyzed; review like any other docs change." 2>&1); then',
+      '            echo "$PR_OUTPUT"',
+      '          elif echo "$PR_OUTPUT" | grep -qi "already exists"; then',
+      '            echo "A pull request for gitset/knowledge-update already exists — nothing further to do."',
+      '            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). Run \'gitset knowledge automate\' again and pick PR mode to set this up automatically, or add a repository secret GITSET_PR_TOKEN with a GitHub token that can open PRs, or open it yourself: https://github.com/${{ github.repository }}/pull/new/gitset/knowledge-update"',
+      '            exit 1',
+      '          fi',
+    ],
+  };
+}
+
+function buildKnowledgeWorkflow({ mode, syncMode = 'commit', provider, envKey, model, defaultBranch = 'main' }) {
   if (!provider || !envKey) throw new Error('provider and envKey are required');
+  if (!SYNC_MODES[syncMode]) throw new Error(`Unknown sync mode "${syncMode}". One of: ${Object.keys(SYNC_MODES).join(', ')}`);
   const updateCmd = `gitset knowledge update --yes --provider ${provider}${model ? ` --model ${model}` : ''}`;
+  const sync = syncMode === 'commit' ? commitModeLines(defaultBranch) : prModeLines();
 
   return [
     'name: Gitset Knowledge Mapper',
@@ -53,16 +146,9 @@ function buildKnowledgeWorkflow({ mode, provider, envKey, model, defaultBranch =
     '# provider — never to Gitset. Runs whose mapped source files are',
     '# unchanged exit without any AI call (content-hash diff), so harmless',
     '# triggers cost nothing beyond a few CI seconds.',
-    '#',
-    '# Also requires "Allow GitHub Actions to create and approve pull',
-    '# requests" to be enabled: Settings > Actions > General > Workflow',
-    '# 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.',
+    ...sync.header,
     ...buildTrigger(mode, defaultBranch),
-    'permissions:',
-    '  contents: write',
-    '  pull-requests: write',
+    ...sync.permissions,
     'concurrency:',
     '  group: gitset-knowledge',
     '  cancel-in-progress: false',
@@ -71,6 +157,7 @@ function buildKnowledgeWorkflow({ mode, provider, envKey, model, defaultBranch =
     '    runs-on: ubuntu-latest',
     '    steps:',
     '      - uses: actions/checkout@v4',
+    ...sync.checkoutWith,
     '      - uses: actions/setup-node@v4',
     '        with:',
     "          node-version: '20'",
@@ -79,31 +166,7 @@ function buildKnowledgeWorkflow({ mode, provider, envKey, model, defaultBranch =
     '        env:',
     `          ${envKey}: \${{ secrets.${envKey} }}`,
     `        run: ${updateCmd}`,
-    '      - name: Open a PR when the knowledge base changed',
-    '        env:',
-    '          GH_TOKEN: ${{ github.token }}',
-    '        run: |',
-    '          if git diff --quiet -- docs/gitset-knowledge AGENTS.md; then',
-    '            echo "Knowledge base already up to date."',
-    '            exit 0',
-    '          fi',
-    '          git config user.name "github-actions[bot]"',
-    '          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"',
-    '          git switch -c gitset/knowledge-update',
-    '          git add docs/gitset-knowledge AGENTS.md',
-    '          git commit -m "docs: refresh knowledge base"',
-    '          git push -f origin gitset/knowledge-update',
-    '          echo "Committed and pushed gitset/knowledge-update — this work is now safe on GitHub regardless of the next step."',
-    '          if PR_OUTPUT=$(gh pr create --title "docs: refresh knowledge base" --body "Automated incremental update by [Gitset](https://gitset.dev) Knowledge Mapper. Only changed modules were re-analyzed; review like any other docs change." 2>&1); then',
-    '            echo "$PR_OUTPUT"',
-    '          elif echo "$PR_OUTPUT" | grep -qi "already exists"; then',
-    '            echo "A pull request for gitset/knowledge-update already exists — nothing further to do."',
-    '            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"',
-    '            exit 1',
-    '          fi',
+    ...sync.finalStep,
     '',
   ].join('\n');
 }
@@ -111,5 +174,6 @@ function buildKnowledgeWorkflow({ mode, provider, envKey, model, defaultBranch =
 module.exports = {
   WORKFLOW_PATH,
   MODES,
+  SYNC_MODES,
   buildKnowledgeWorkflow,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitset-dev/cli",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "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

@@ -520,11 +520,66 @@ async function ensurePrPermission(repo, argv) {
     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 may lock this setting).', 'yellow');
+    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');
     return 'failed';
   }
 }
 
+async function provisionPrToken(repo, argv) {
+  if (!repo.includes('/')) return 'unavailable';
+
+  const existing = (() => {
+    try {
+      const out = execFileSync('gh', ['secret', 'list', '--repo', repo], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      return out.includes('GITSET_PR_TOKEN');
+    } catch {
+      return false;
+    }
+  })();
+  if (existing) {
+    log('The GITSET_PR_TOKEN secret already exists in this repository — PR mode is ready.', 'green');
+    return 'already-provisioned';
+  }
+
+  log('\nNo problem — this can be fixed right now, automatically:', 'cyan');
+  log('  Your repository (or its organization) blocks the built-in CI token from opening pull requests.', 'reset');
+  log('  The fix: store a token from YOUR current GitHub login (the same one the gh CLI already uses) as an encrypted secret named GITSET_PR_TOKEN in this repository.', 'reset');
+  log('  · You don\'t create anything manually — no settings pages, no token forms.', 'dim');
+  log('  · The token is stored encrypted by GitHub, in this repository only.', 'dim');
+  log('  · CI will open pull requests as you, which your organization does allow.', 'dim');
+  log('  · Undo anytime: delete the GITSET_PR_TOKEN secret and CI falls back to the built-in token.', 'dim');
+
+  const proceed = await confirmOrAbort('\nStore it now?', argv);
+  if (!proceed) return 'declined';
+
+  let token = '';
+  try {
+    token = execFileSync('gh', ['auth', 'token'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {  }
+  if (!token) {
+    log('Could not read a token from your gh login. Run "gh auth login" first, then re-run: gitset knowledge automate', 'red');
+    return 'failed';
+  }
+
+  try {
+    execFileSync('gh', ['secret', 'set', 'GITSET_PR_TOKEN', '--repo', repo], { input: token, stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch {
+    log('Could not store the secret (you may not have admin access on this repository).', 'red');
+    return 'failed';
+  }
+
+  try {
+    const out = execFileSync('gh', ['secret', 'list', '--repo', repo], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    if (!out.includes('GITSET_PR_TOKEN')) throw new Error('not visible');
+  } catch {
+    log('The secret was sent but could not be verified — check https://github.com/' + repo + '/settings/secrets/actions', 'yellow');
+    return 'unverified';
+  }
+
+  log('Done — GITSET_PR_TOKEN is stored. CI can now open pull requests, starting with the very next run.', 'green');
+  return 'provisioned';
+}
+
 async function runAutomate(rootDir, argv) {
   let cfg;
   try {
@@ -565,8 +620,44 @@ async function runAutomate(rootDir, argv) {
     return 1;
   }
 
+  const repo = repoLabel(rootDir);
+
+  let syncMode = flag(argv, '--sync');
+  if (!syncMode) {
+    if (!process.stdin.isTTY || argv.includes('--yes') || argv.includes('-y')) {
+      syncMode = 'commit';
+    } else {
+      syncMode = await selectOption('How should CI apply each update?', [
+        { label: `Commit directly to ${defaultBranch} (recommended — zero setup, works on every repo and org)`, value: 'commit' },
+        { label: 'Open a review pull request for each update (one extra one-time step — automated for you)', value: 'pr' },
+        { label: 'Cancel', value: 'cancel' },
+      ]);
+      if (syncMode === 'cancel') {
+        log('Nothing written.', 'yellow');
+        return 0;
+      }
+    }
+  }
+  if (!km.SYNC_MODES[syncMode]) {
+    log(`Unknown sync mode "${syncMode}". One of: ${Object.keys(km.SYNC_MODES).join(', ')}`, 'red');
+    return 1;
+  }
+
+  let prReady = null;
+  if (syncMode === 'pr') {
+    const prPermission = await ensurePrPermission(repo, argv);
+    if (prPermission === 'enabled' || prPermission === 'already-enabled') {
+      prReady = 'permission';
+    } else {
+      const patStatus = await provisionPrToken(repo, argv);
+      if (patStatus === 'provisioned' || patStatus === 'already-provisioned') prReady = 'token';
+      else if (patStatus === 'unverified') prReady = 'token-unverified';
+    }
+  }
+
   const yaml = km.buildKnowledgeWorkflow({
     mode,
+    syncMode,
     provider: cfg.provider,
     envKey,
     model: cfg.model || null,
@@ -590,9 +681,6 @@ async function runAutomate(rootDir, argv) {
   fs.writeFileSync(target, yaml);
   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('/')) {
@@ -600,20 +688,24 @@ async function runAutomate(rootDir, argv) {
   } else {
     log('     GitHub repo > Settings > Secrets and variables > 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');
+  log('  2. Make sure the knowledge base itself is committed (gitset knowledge generate, then commit docs/gitset-knowledge/ and AGENTS.md).', 'reset');
+  log('  3. Commit and push the workflow file.', 'reset');
+
+  if (syncMode === 'commit') {
+    log(`\nThat's it — CI will commit refreshed docs straight to ${defaultBranch} whenever mapped source changes. No permissions to touch, no tokens to create, and runs with no mapped changes make zero AI calls.`, 'dim');
+    log('Prefer reviewing each update as a pull request instead? Re-run: gitset knowledge automate --sync pr', 'dim');
   } else {
-    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 (prReady === 'permission') {
+      log('\nPR mode is ready: GitHub Actions is allowed to open pull requests in this repository.', 'dim');
+    } else if (prReady === 'token') {
+      log('\nPR mode is ready: CI will open pull requests using the GITSET_PR_TOKEN secret that was just stored.', 'dim');
+    } else if (prReady === 'token-unverified') {
+      log(`\nPR mode should be ready, but the stored secret could not be verified — double-check https://github.com/${repo}/settings/secrets/actions`, 'yellow');
     } else {
-      log('     GitHub repo > Settings > Actions > General > Workflow permissions', 'dim');
+      log('\nPR mode is NOT ready yet: CI cannot open pull requests in this repository until one of the fixes above is applied. Updates will still commit and push their branch safely — only the PR step will fail, visibly. Re-run "gitset knowledge automate" anytime to finish the setup, or switch to zero-setup direct commits with: gitset knowledge automate --sync commit', 'yellow');
     }
-    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('When 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');
   }
-  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');
   return 0;
 }
 
@@ -644,7 +736,8 @@ async function runKnowledgeCommand(argv = []) {
       log('  generate   build docs/gitset-knowledge/ from source code (asks before spending)', 'dim');
       log('  update     incremental refresh: only changed modules are re-summarized', 'dim');
       log('  automate   write a CI workflow that keeps it fresh (always asks first)', 'dim');
-      log('  flags      --provider <p> --model <m> --yes --since <ref> (update) --mode <push|releases|weekly> (automate)', 'dim');
+      log('  flags      --provider <p> --model <m> --yes --since <ref> (update)', 'dim');
+      log('             --mode <push|releases|weekly> --sync <commit|pr> (automate)', 'dim');
       return verb ? 1 : 0;
   }
 }