@codersbrew/pi-tools 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,10 @@
 # @codersbrew/pi-tools
 
-A publishable [pi](https://github.com/badlogic/pi-mono) package that bundles CodersBrew's custom pi extensions.
+A publishable [pi](https://github.com/badlogic/pi-mono) package that bundles CodersBrew's custom pi extensions and skills.
 
-## Included extensions
+## Included resources
+
+### Extensions
 
 ### `security`
 Protects common dangerous tool operations by:
@@ -16,6 +18,17 @@ Adds an interactive TUI for analyzing pi session history from `~/.pi/agent/sessi
 - model, cwd, day-of-week, and time-of-day breakdowns
 - contribution-style heatmap visualizations
 
+### Skill: `github-workflow`
+An opinionated GitHub workflow skill for branch creation, commits, pushes, PR creation, review, and merge work.
+
+It prefers `gh` for GitHub-aware actions and uses plain `git` where local source-control operations are the better tool.
+
+Invoke it in pi with:
+
+```bash
+/skill:github-workflow
+```
+
 ## Install
 
 Global install:
@@ -43,13 +56,15 @@ You can also add it manually to pi settings:
 This package uses pi's standard package manifest:
 - `extensions/security.ts`
 - `extensions/session-breakdown.ts`
+- `skills/github-workflow/SKILL.md`
 
 The root `package.json` exposes them through:
 
 ```json
 {
   "pi": {
-    "extensions": ["./extensions"]
+    "extensions": ["./extensions"],
+    "skills": ["./skills"]
   }
 }
 ```
@@ -86,8 +101,8 @@ Bootstrap steps for `@codersbrew/pi-tools`:
 
 1. Create an npm access token with publish rights
 2. Add it to the GitHub repo as `NPM_TOKEN`
-3. Confirm `package.json` has the intended version, currently `0.1.0`
-4. Push a version tag such as `v0.1.0`
+3. Confirm `package.json` has the intended version
+4. Push a matching version tag such as `v0.2.0`
 5. GitHub Actions will verify the package, publish it, and create a GitHub release
 
 ### Switch to trusted publishing after first release
@@ -106,7 +121,7 @@ After trusted publishing is configured, remove the `NPM_TOKEN` secret if you wan
 
 1. Update the package version in `package.json`
 2. Commit and push the change
-3. Create and push a matching version tag such as `v0.1.1`
+3. Create and push a matching version tag such as `v0.2.0`
 4. GitHub Actions will run verification, publish to npm, and create a GitHub release
 
 The workflow uses Node 24 so the npm CLI is new enough for trusted publishing and provenance support.

package/extensions/session-breakdown.ts

@@ -25,7 +25,6 @@ import {
 	truncateToWidth,
 	visibleWidth,
 } from "@mariozechner/pi-tui";
-import { sliceByColumn } from "@mariozechner/pi-tui/dist/utils.js";
 import os from "node:os";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -48,6 +47,78 @@ const TOD_BUCKETS: { key: TodKey; label: string; from: number; to: number }[] =
 	{ key: "night", label: "Night (22–23)", from: 22, to: 23 },
 ];
 
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+function extractAnsiCode(str: string, pos: number): { code: string; length: number } | null {
+	if (pos >= str.length || str[pos] !== "\x1b") return null;
+	const next = str[pos + 1];
+
+	if (next === "[") {
+		let j = pos + 2;
+		while (j < str.length && !/[mGKHJ]/.test(str[j])) j++;
+		if (j < str.length) return { code: str.substring(pos, j + 1), length: j + 1 - pos };
+		return null;
+	}
+
+	if (next === "]" || next === "_") {
+		let j = pos + 2;
+		while (j < str.length) {
+			if (str[j] === "\x07") return { code: str.substring(pos, j + 1), length: j + 1 - pos };
+			if (str[j] === "\x1b" && str[j + 1] === "\\") return { code: str.substring(pos, j + 2), length: j + 2 - pos };
+			j++;
+		}
+		return null;
+	}
+
+	return null;
+}
+
+// pi's extension loader aliases @mariozechner/pi-tui to its dist/index.js entry.
+// Importing deep internals like @mariozechner/pi-tui/dist/utils.js therefore resolves
+// incorrectly under jiti (…/dist/index.js/dist/utils.js), so keep this local helper.
+function sliceByColumn(line: string, startCol: number, length: number, strict = false): string {
+	if (length <= 0) return "";
+
+	const endCol = startCol + length;
+	let result = "";
+	let currentCol = 0;
+	let i = 0;
+	let pendingAnsi = "";
+
+	while (i < line.length) {
+		const ansi = extractAnsiCode(line, i);
+		if (ansi) {
+			if (currentCol >= startCol && currentCol < endCol) result += ansi.code;
+			else if (currentCol < startCol) pendingAnsi += ansi.code;
+			i += ansi.length;
+			continue;
+		}
+
+		let textEnd = i;
+		while (textEnd < line.length && !extractAnsiCode(line, textEnd)) textEnd++;
+
+		for (const { segment } of graphemeSegmenter.segment(line.slice(i, textEnd))) {
+			const w = visibleWidth(segment);
+			const inRange = currentCol >= startCol && currentCol < endCol;
+			const fits = !strict || currentCol + w <= endCol;
+			if (inRange && fits) {
+				if (pendingAnsi) {
+					result += pendingAnsi;
+					pendingAnsi = "";
+				}
+				result += segment;
+			}
+			currentCol += w;
+			if (currentCol >= endCol) break;
+		}
+
+		i = textEnd;
+		if (currentCol >= endCol) break;
+	}
+
+	return result;
+}
+
 function todBucketForHour(hour: number): TodKey {
 	for (const b of TOD_BUCKETS) {
 		if (hour >= b.from && hour <= b.to) return b.key;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codersbrew/pi-tools",
-  "version": "0.1.0",
-  "description": "A pi package bundling CodersBrew pi extensions.",
+  "version": "0.2.0",
+  "description": "A pi package bundling CodersBrew pi extensions and skills.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -22,6 +22,7 @@
   },
   "files": [
     "extensions",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -29,9 +30,10 @@
     "node": ">=20.6.0"
   },
   "scripts": {
+    "test": "node --test test/*.test.mjs",
     "typecheck": "tsc --noEmit",
     "pack:check": "npm pack --dry-run",
-    "check": "npm run typecheck && npm run pack:check"
+    "check": "npm run test && npm run typecheck && npm run pack:check"
   },
   "publishConfig": {
     "access": "public"
@@ -49,6 +51,9 @@
   "pi": {
     "extensions": [
       "./extensions"
+    ],
+    "skills": [
+      "./skills"
     ]
   }
 }

package/skills/github-workflow/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: github-workflow
+description: Use when working in a git repository hosted on GitHub and handling branch creation, commits, pushes, pull requests, reviews, or merges with gh CLI available.
+---
+
+# GitHub Workflow
+
+## Overview
+
+Use a hybrid workflow: prefer `gh` for GitHub-aware tasks, and use `git` for local history editing, staging, and branch mechanics.
+
+**Opinionated defaults:**
+- inspect repo state before making changes
+- keep branches focused and short-lived
+- use conventional-commit-style messages when possible
+- open PRs with clear titles and summaries
+- merge with explicit intent, not guesswork
+
+## Quick Start Checks
+
+Run these before branching or opening a PR:
+
+```bash
+gh auth status
+git remote -v
+gh repo view --json nameWithOwner,defaultBranchRef
+```
+
+Confirm:
+- `gh` is authenticated
+- the repo remote points to the expected GitHub repository
+- you know the default branch, usually `main` or `master`
+
+If `gh repo view` fails because the current repo is not connected to GitHub, fall back to plain `git` and ask before attempting GitHub-specific actions.
+
+## Tool Choice Rules
+
+| Use `gh` for | Use `git` for |
+|---|---|
+| auth and repo checks | staging files |
+| PR create/view/checkout/review/merge | commit creation/amend/rebase |
+| PR status and checks | switching branches |
+| opening web pages for repo or PR context | inspecting local diffs and history |
+
+**Fallback rule:** if `gh` has a clean command for the task, prefer it. If the task is fundamentally local source control, use `git`.
+
+## Branch Workflow
+
+1. Sync and inspect the default branch.
+2. Create a focused branch from the default branch.
+3. Keep the branch name descriptive.
+
+Example:
+
+```bash
+git switch main
+git pull --ff-only
+git switch -c feat/add-github-workflow-skill
+```
+
+Recommended prefixes:
+- `feat/`
+- `fix/`
+- `docs/`
+- `chore/`
+- `refactor/`
+- `test/`
+
+Avoid vague names like `updates`, `stuff`, or `misc-fixes`.
+
+## Commit Workflow
+
+Use `git` for staging and committing. Keep commits small and readable.
+
+```bash
+git status
+git add <paths>
+git commit -m "feat: add github workflow skill"
+```
+
+Prefer conventional-commit-style summaries:
+- `feat: add github workflow skill`
+- `fix: correct PR base branch detection`
+- `docs: document packaged skills`
+- `chore: clean up release notes`
+
+Before pushing, review what changed:
+
+```bash
+git diff --staged
+```
+
+If a commit needs cleanup, use `git commit --amend` or interactive rebase deliberately. Do not use `gh` for local history surgery.
+
+## Push and PR Workflow
+
+Push with `git`, then use `gh` to work with the PR.
+
+```bash
+git push -u origin HEAD
+gh pr create --fill --base main
+```
+
+Useful `gh` commands:
+
+```bash
+gh pr status
+gh pr view --web
+gh pr checks
+gh pr create --fill --base <default-branch>
+gh pr checkout <number>
+```
+
+PR hygiene:
+- make sure the base branch is correct
+- use a title that matches the change
+- include a short summary of what changed and any risk areas
+- mention tests run when relevant
+
+If `--fill` produces a weak title/body, replace it instead of accepting low-quality PR text.
+
+## Review Workflow
+
+Use `gh` to inspect and respond to review state.
+
+```bash
+gh pr view <number>
+gh pr diff <number>
+gh pr checks <number>
+gh pr review <number> --comment -b "Looks good overall; left one suggestion."
+gh pr review <number> --approve
+gh pr review <number> --request-changes -b "Please address the failing tests and rename the branch."
+```
+
+When reviewing your own work, check:
+- PR targets the correct base branch
+- branch is up to date enough for the repo's workflow
+- checks are green or known failures are explained
+- description matches the actual diff
+
+## Merge Workflow
+
+Prefer `gh pr merge` so the merge action is tied to GitHub PR state.
+
+```bash
+gh pr merge <number> --squash --delete-branch
+```
+
+Common variants:
+- `--squash` for small or iterative branches
+- `--merge` when the repo prefers merge commits
+- `--rebase` when the repo explicitly prefers rebased history
+
+Before merging, confirm:
+- approvals or review requirements are satisfied
+- required checks passed
+- the chosen merge strategy matches repo norms
+
+After merge, sync local state:
+
+```bash
+git switch main
+git pull --ff-only
+```
+
+## Common Mistakes
+
+- using `gh` for tasks that are really local `git` operations
+- forgetting to verify the default branch before creating the PR
+- pushing a branch without `-u` and then losing the upstream link
+- opening a PR with an unhelpful auto-filled title/body
+- merging without checking CI or review status
+- mixing unrelated changes into one branch or one commit
+
+## Red Flags
+
+Stop and re-check before acting if you see any of these:
+- `gh auth status` is not healthy
+- the remote is not the repo you expected
+- you do not know the correct base branch
+- the branch name does not describe the change
+- the PR title says one thing but the diff shows another
+- checks are failing and no reason is documented
+
+When unsure, inspect first, then act.