toga-ai 1.0.45 → 1.0.46

package/knowledge.js

@@ -170,6 +170,82 @@ function cmdManifest() {
     console.log(JSON.stringify({ repos, clients }));
 }
 
+/* ------------------------------------------------------------------ */
+/* command: publish — capture's deterministic finish (validate, index, */
+/* optional mirror, commit knowledge/, rebase-before-push with retry). */
+/* Replaces ~80 lines of skill prose + 6 model-orchestrated git calls.  */
+/* Flags: --msg=<commit msg> --mirror=<project .claude dir> --branch=   */
+/* Prints one PUBLISH: <STATUS> line the skill can branch on.           */
+/* ------------------------------------------------------------------ */
+
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+        const s = path.join(src, e.name), d = path.join(dest, e.name);
+        if (e.isDirectory()) copyDir(s, d);
+        else fs.copyFileSync(s, d);
+    }
+}
+
+function cmdPublish(args) {
+    const cp = require('child_process');
+    const TEAM = __dirname;
+    const node = process.argv[0];
+    const self = __filename;
+    const branch = args.branch || '_main';
+    const run = (cmd) => cp.execSync(cmd, { cwd: TEAM, encoding: 'utf8', stdio: 'pipe' });
+
+    // 0. must be a git clone
+    try { run('git rev-parse --git-dir'); }
+    catch { console.log('PUBLISH: NOT_GIT — knowledge written locally only; run `npx toga-ai` to create a pushable clone'); return; }
+
+    // 1. validate (inherit output so any ERROR: lines are visible); abort on failure
+    try { cp.execSync(`"${node}" "${self}" validate`, { cwd: TEAM, stdio: 'inherit' }); }
+    catch { console.log('PUBLISH: VALIDATE_FAILED — fix the errors above; nothing pushed'); process.exitCode = 1; return; }
+
+    // 2. rebuild indexes
+    cp.execSync(`"${node}" "${self}" index`, { cwd: TEAM, stdio: 'inherit' });
+
+    // 3. optional mirror back to the project bundle (keeps local reads fresh)
+    if (args.mirror && typeof args.mirror === 'string') {
+        const dest = path.join(args.mirror, 'knowledge');
+        if (path.resolve(dest) !== path.resolve(ROOT)) { copyDir(ROOT, dest); console.log('PUBLISH: mirrored knowledge/ -> ' + dest); }
+    }
+
+    // 4. stage knowledge/ ONLY; bail if anything else slipped in
+    run('git add knowledge/');
+    const staged = run('git diff --cached --name-only').split('\n').map(s => s.trim()).filter(Boolean);
+    if (staged.length === 0) { console.log('PUBLISH: NO_CHANGES — nothing new to push'); return; }
+    const outside = staged.filter(f => !f.startsWith('knowledge/'));
+    if (outside.length) { run('git reset -q'); console.log('PUBLISH: ABORT_OUTSIDE_KNOWLEDGE — refusing to commit non-knowledge files: ' + outside.join(', ')); process.exitCode = 1; return; }
+
+    // 5. commit
+    const msg = String(args.msg || 'knowledge: capture session updates').replace(/["\\]/g, "'").slice(0, 200);
+    run(`git commit -m "${msg}"`);
+
+    // 6. rebase-before-push, retrying the CI version-bump race up to 3x
+    for (let attempt = 1; attempt <= 3; attempt++) {
+        try {
+            run('git fetch origin');
+            run(`git rebase origin/${branch}`);
+            run(`git push origin HEAD:${branch}`);
+            console.log(`PUBLISH: PUSHED to ${branch} — CI publishes a new npm version; teammates get it on \`npx toga-ai\``);
+            return;
+        } catch (e) {
+            let status = '';
+            try { status = run('git status --porcelain'); } catch { /* ignore */ }
+            if (/^(UU|AA|DD|AU|UA|DU|UD) /m.test(status)) {
+                try { run('git rebase --abort'); } catch { /* ignore */ }
+                console.log(`PUBLISH: CONFLICT — rebase onto origin/${branch} hit a real conflict; resolve manually, then re-run publish`);
+                process.exitCode = 1; return;
+            }
+            // else: almost certainly a fresh CI bump (non-fast-forward) — loop and retry
+        }
+    }
+    console.log(`PUBLISH: PUSH_FAILED after 3 attempts — run manually: git -C "${TEAM}" push origin HEAD:${branch}`);
+    process.exitCode = 1;
+}
+
 /* ------------------------------------------------------------------ */
 /* command: deps                                                       */
 /* ------------------------------------------------------------------ */
@@ -405,8 +481,9 @@ function main() {
         case 'deps': return cmdDeps(args);
         case 'validate': return cmdValidate();
         case 'manifest': return cmdManifest();
+        case 'publish': return cmdPublish(args);
         default:
-            console.log('Usage: node knowledge.js <search|index|deps|validate|manifest> [--flags]');
+            console.log('Usage: node knowledge.js <search|index|deps|validate|manifest|publish> [--flags]');
             process.exitCode = 1;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.45",
+  "version": "1.0.46",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",

package/skills/capture/SKILL.md

@@ -53,8 +53,8 @@ done
 **`~/toga-tech` must be probed first** — `npx toga-ai` runs `initLocalRepo` there, which
 creates a proper git repo seeded from the bundle even when the remote is private.
 
-**If `IS_GIT_CLONE` is false** (only `.claude/` bundle found): warn immediately and skip
-Steps 5–7 for git operations:
+**If `IS_GIT_CLONE` is false** (only `.claude/` bundle found): you can still write docs
+locally (Step 5), but the Step 6 publish will report `NOT_GIT` instead of pushing. Warn:
 > "⚠ No git clone found at standard paths. Docs will be written locally only.
 > Run `npx toga-ai` first (it creates `~/toga-tech` as a pushable git repo),
 > then re-run /capture to push to GitHub."
@@ -143,94 +143,34 @@ For a client `profile.md`, the `title:` **is** the client's formal name (e.g. "C
 there is no separate name field; `validate` requires `title`. See New-client onboarding.
 Add `related:` cross-links. Append new repos to `<TEAM_REPO>/knowledge/registry.json`.
 
-## Step 6 — Validate, index, mirror back (mandatory)
+## Step 6 — Publish (validate → index → mirror → rebase-push, one command)
 
-```bash
-node "<TEAM_REPO>/knowledge.js" validate
-node "<TEAM_REPO>/knowledge.js" index
-```
-
-If `validate` reports any ERROR — stop and fix before continuing.
-
-After both pass, **mirror back** to keep the project's local reads fresh:
-```bash
-# Only when TEAM_REPO != <project>/.claude
-cp -r "<TEAM_REPO>/knowledge/" "<project>/.claude/knowledge/"
-```
-Skip mirror-back if the paths are the same directory.
-
-## Step 7 — Push (only when IS_GIT_CLONE is true)
-
-**This push is pre-authorized and mandatory — never ask the developer to confirm it.**
-Running `/capture` IS the authorization to publish. After validate + index pass and the
-staged set is confined to `knowledge/`, commit and push automatically as the final step of
-every capture. Do not pause, do not present a "ready to push?" prompt, do not offer to "leave
-it staged locally." The only reasons to stop are the guardrails already listed below: nothing
-new to push (Check B empty), files staged outside `knowledge/`, or a push that errors.
-
-If `IS_GIT_CLONE` is false — skip this step entirely and show:
-> "⚠ Docs written to `.claude/knowledge/` only (no git clone). Run `npx toga-ai`
-> to create `~/toga-tech`, then re-run /capture to push."
-
-Otherwise:
-
-**Check A — origin URL correct?**
-```bash
-git -C "<TEAM_REPO>" remote get-url origin
-```
-If wrong or missing: `git -C "<TEAM_REPO>" remote set-url origin https://github.com/agilantsolutions/claude`
-
-**Check B — anything new to push?**
-```bash
-git -C "<TEAM_REPO>" status --short knowledge/
-```
-If empty — report "No new knowledge to push" and exit cleanly.
-
-**Commit:**
-```bash
-git -C "<TEAM_REPO>" add knowledge/
-git -C "<TEAM_REPO>" diff --cached --quiet || \
-  git -C "<TEAM_REPO>" commit -m "knowledge: <one-line summary>"
-```
-
-Never stage files outside `knowledge/`. If `git diff --cached` includes anything outside
-`knowledge/`, abort and warn before committing.
-
-**Sync, then push (rebase BEFORE pushing — this prevents the version-bump conflict):**
-
-Every push to this branch triggers a CI job that commits a `chore: bump version [skip ci]`
-back to the branch. So after *any* prior push (e.g. an earlier capture in the same session),
-your local branch is one commit behind the remote, and a naive push is rejected as a
-non-fast-forward. Rebase your fresh commit onto the remote **before** pushing — this pulls in
-commits that already exist (no waiting on CI), so the push fast-forwards cleanly:
+Finish every capture with the deterministic publisher — **do not** run validate/index/git
+by hand. The push is **pre-authorized and mandatory**: running `/capture` IS the
+authorization, so never ask "ready to push?".
 
 ```bash
-git -C "<TEAM_REPO>" fetch origin
-git -C "<TEAM_REPO>" rebase origin/_main
-git -C "<TEAM_REPO>" push origin HEAD:_main
+node "<TEAM_REPO>/knowledge.js" publish --msg="knowledge: <one-line summary>" --mirror="<project>/.claude"
 ```
 
-> **Do NOT "pull after push" instead** — the bump commit for *this* push is created
-> asynchronously by CI a few seconds later, so pulling immediately afterward races CI and
-> usually grabs nothing. Rebasing *before* the push is what reliably avoids the conflict,
-> with zero dependency on npm build/publish timing.
-
-**If the push is still rejected** (a bump commit landed in the brief window between your
-rebase and push), simply repeat `fetch` → `rebase` → `push`, up to 2 more times. This is an
-expected occasional race, not an error — do not report it as a failure unless all retries are
-exhausted.
-
-**If push succeeds:**
-> "✓ Pushed to `_main` — CI publishes new npm version. Teammates get it on `npx toga-ai`."
+This validates, rebuilds indexes, mirrors `knowledge/` back to the project bundle, then
+stages **only** `knowledge/`, commits, and rebase-pushes to `_main` (auto-retrying the CI
+version-bump race). Omit `--mirror` if TEAM_REPO already *is* the project bundle. Read the
+final `PUBLISH:` line and act on it:
 
-**If push fails** — show exact git error, then:
-> "⚠ Push failed: `<error>`. Run manually: `git -C <TEAM_REPO> push origin HEAD:_main`"
+- **`PUSHED`** — done. Report: "✓ Pushed to `_main` — teammates get it on `npx toga-ai`."
+- **`NO_CHANGES`** — report "No new knowledge to push" and finish.
+- **`VALIDATE_FAILED`** — fix the printed `ERROR:` lines, then re-run publish. Never push around it.
+- **`CONFLICT`** — a real rebase conflict; resolve manually, then re-run publish.
+- **`ABORT_OUTSIDE_KNOWLEDGE`** — non-`knowledge/` files were staged; investigate before retrying.
+- **`NOT_GIT`** — no git clone; docs are local only. Tell the dev to run `npx toga-ai` first.
+- **`PUSH_FAILED`** — show the printed manual-push command.
 
-## Step 8 — Report
+## Step 7 — Report
 
 List exactly what changed (clickable relative paths), and note any ⚠ ELEVATED docs the
 developer approved so they remember those touched senior-owned standards/architecture.
-If Step 7 pushed successfully, include the push confirmation in the report.
+If Step 6 published successfully (`PUSHED`), include the push confirmation in the report.
 
 ---
 
@@ -396,4 +336,4 @@ Suggest a slug from the work, e.g. `/session-save clickup-deploy-worker`.
 
 `.claude/settings.json` runs `node knowledge.js validate` after every write to `knowledge/`,
 so `ERROR:`/`OK` output appears inline as each doc is written — fix any error before writing
-the next. Step 6's explicit `validate` is still required as the final global-consistency gate.
+the next. Step 6's `publish` re-runs `validate` as the final global-consistency gate before pushing.