@gitset-dev/cli 2.4.0 → 2.4.2

package/README.md

@@ -87,6 +87,38 @@ 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 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.
+
 ## Templates
 
 Define your commit style, issue structure, PR format, README skeleton, or

package/lib/knowledge/ci.js

@@ -53,6 +53,12 @@ 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.',
     ...buildTrigger(mode, defaultBranch),
     'permissions:',
     '  contents: write',
@@ -87,7 +93,17 @@ function buildKnowledgeWorkflow({ mode, provider, envKey, model, defaultBranch =
     '          git add docs/gitset-knowledge AGENTS.md',
     '          git commit -m "docs: refresh knowledge base"',
     '          git push -f origin gitset/knowledge-update',
-    '          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." || true',
+    '          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',
     '',
   ].join('\n');
 }

package/lib/prompts/defaults.js

@@ -151,10 +151,14 @@ const knowledgeSummarize = {
         'exposes — module.exports, export statements, __all__; an executable or ' +
         'script with no exports gets [], never its internal functions; max 12), ' +
         '"dependencies": string[] (notable internal files or external ' +
-        'packages this file relies on, max 10), "notes": string (<= 160 chars — ' +
-        'gotchas, side effects, or "" if none)}]. One entry per FILE block in the ' +
-        'input, using the exact path given. For a dispatcher/entry-point file, ' +
-        'note in "notes" the exact command or route names it registers.',
+        'packages this file relies on, max 10 — each entry must be a distinct, ' +
+        'real import copied from the file\'s own import/require statements; if ' +
+        'you are not certain of one, omit it rather than guessing, and never ' +
+        'repeat or extend a name into a longer variant), "notes": string ' +
+        '(<= 160 chars — gotchas, side effects, or "" if none)}]. One entry per ' +
+        'FILE block in the input, using the exact path given. For a dispatcher/' +
+        'entry-point file, note in "notes" the exact command or route names it ' +
+        'registers.',
       user: [
         repo && `Repository: ${clip(repo, 200)}`,
         module && `Module: ${clip(module, 200)}`,

package/package.json

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

@@ -125,6 +125,12 @@ async function confirmOrAbort(question, argv) {
   return answer === 'y' || answer === 'yes';
 }
 
+function appendModuleEntries(moduleSummaries, moduleName, entries) {
+  const prev = moduleSummaries[moduleName];
+  const prevArray = Array.isArray(prev) ? prev : [];
+  moduleSummaries[moduleName] = [...prevArray, ...entries];
+}
+
 async function summarizeBatches({ batches, repo, argv, cachedSummaries = {}, usage }) {
   const moduleSummaries = { ...cachedSummaries };
   let providerUsed = null;
@@ -133,7 +139,7 @@ async function summarizeBatches({ batches, repo, argv, cachedSummaries = {}, usa
   for (const batch of batches) {
     done += 1;
     log(`  [${done}/${batches.length}] Summarizing ${batch.module}${batch.part > 1 ? ` (part ${batch.part})` : ''}…`, 'dim');
-    const result = await genLocal.generate({
+    const summarizeBatch = (temperature) => genLocal.generate({
       tool: 'knowledgeSummarize',
       ctx: {
         repo,
@@ -143,19 +149,37 @@ async function summarizeBatches({ batches, repo, argv, cachedSummaries = {}, usa
       provider: flag(argv, '--provider'),
       model: flag(argv, '--model'),
       maxTokens: km.DEFAULTS.summarizeMaxTokens,
-      temperature: 0.2,
+      temperature,
       interactive: true,
     });
+
+    let result = await summarizeBatch(0.2);
+    trackUsage(usage, result);
     providerUsed = result.provider;
     modelUsed = result.model;
-    trackUsage(usage, result);
-    const entries = km.parseSummarizeResponse(result.raw);
-    const prev = moduleSummaries[batch.module];
+    let entries = km.parseSummarizeResponse(result.raw);
+
+    if (!entries) {
+      log(`    Structured parse failed for ${batch.module}${batch.part > 1 ? ` (part ${batch.part})` : ''}; retrying once…`, 'yellow');
+      result = await summarizeBatch(0.5);
+      trackUsage(usage, result);
+      providerUsed = result.provider;
+      modelUsed = result.model;
+      entries = km.parseSummarizeResponse(result.raw);
+    }
+
     if (entries) {
-      moduleSummaries[batch.module] = Array.isArray(prev) ? [...prev, ...entries] : entries;
+      appendModuleEntries(moduleSummaries, batch.module, entries);
     } else {
-      log(`    Structured parse failed for ${batch.module}; keeping raw summary text.`, 'yellow');
-      moduleSummaries[batch.module] = typeof prev === 'string' ? `${prev}\n${result.text}` : result.text;
+      log(`    Still unparseable after retry; recording ${batch.files.length} file(s) as summary-unavailable (no data lost for the rest of the module).`, 'yellow');
+      const placeholders = batch.files.map((f) => ({
+        path: f.path,
+        purpose: '(AI summary unavailable — the model\'s response for this batch could not be parsed after a retry)',
+        exports: [],
+        dependencies: [],
+        notes: '',
+      }));
+      appendModuleEntries(moduleSummaries, batch.module, placeholders);
     }
   }
   return { moduleSummaries, providerUsed, modelUsed };
@@ -468,6 +492,39 @@ 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 may lock this setting).', 'yellow');
+    return 'failed';
+  }
+}
+
 async function runAutomate(rootDir, argv) {
   let cfg;
   try {
@@ -534,6 +591,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('/')) {
@@ -541,8 +600,19 @@ async function runAutomate(rootDir, argv) {
   } else {
     log('     GitHub repo > Settings > Secrets and variables > Actions', 'dim');
   }
-  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 (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('  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');
+  }
+  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;
 }