Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

feat(loop-worktree): npm publish + macOS gc path fix (#204)

Cobus Greylingd27e7a54c2e2
diff --git a/.github/workflows/release-loop-worktree.yml b/.github/workflows/release-loop-worktree.yml
new file mode 100644
index 0000000..b95c018
--- /dev/null
+++ b/.github/workflows/release-loop-worktree.yml
@@ -0,0 +1,63 @@
+name: Release loop-worktree
+
+on:
+ push:
+ tags:
+ - 'loop-worktree-v*'
+ workflow_dispatch:
+ inputs:
+ tag:
+ description: 'Tag to publish (e.g. loop-worktree-v1.0.0)'
+ required: true
+ type: string
+
+permissions:
+ contents: read
+ id-token: write
+
+jobs:
+ test-and-publish:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', github.event.inputs.tag) || github.ref }}
+
+ - uses: actions/setup-node@v6
+ with:
+ node-version: '22'
+ registry-url: 'https://registry.npmjs.org'
+ cache: 'npm'
+ cache-dependency-path: tools/loop-worktree/package-lock.json
+
+ - name: Ensure npm supports trusted publishing (OIDC)
+ run: npm install -g npm@latest
+
+ - name: Install, build, test
+ working-directory: tools/loop-worktree
+ run: |
+ npm ci
+ npm run build
+ npm test
+
+ - name: Skip if version already published
+ id: check
+ working-directory: tools/loop-worktree
+ run: |
+ VERSION=$(node -p "require('./package.json').version")
+ if npm view "@cobusgreyling/loop-worktree@${VERSION}" version 2>/dev/null; then
+ echo "Version ${VERSION} already on npm — skipping publish."
+ echo "skip=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "Publishing @cobusgreyling/loop-worktree@${VERSION}"
+ echo "skip=false" >> "$GITHUB_OUTPUT"
+ fi
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+ - name: Publish to npm
+ if: steps.check.outputs.skip != 'true'
+ working-directory: tools/loop-worktree
+ run: npm publish --access public --provenance
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
\ No newline at end of file
diff --git a/README.md b/README.md
index 328cafe..da72de6 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,8 @@
<a href="https://www.npmjs.com/package/@cobusgreyling/loop-cost"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-cost?label=loop-cost" alt="loop-cost npm"></a>
<a href="https://www.npmjs.com/package/@cobusgreyling/loop-sync"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-sync?label=loop-sync" alt="loop-sync npm"></a>
<a href="https://www.npmjs.com/package/@cobusgreyling/loop-context"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-context?label=loop-context" alt="loop-context npm"></a>
+ <a href="https://www.npmjs.com/package/@cobusgreyling/loop-mcp-server"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-mcp-server?label=loop-mcp-server" alt="loop-mcp-server npm"></a>
+ <a href="https://www.npmjs.com/package/@cobusgreyling/loop-worktree"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-worktree?label=loop-worktree" alt="loop-worktree npm"></a>
<a href="https://github.com/cobusgreyling/loop-engineering/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
<a href="https://cobusgreyling.github.io/loop-engineering/"><img src="https://img.shields.io/badge/GitHub_Pages-live%20%7C%20interactive-3ee8c5" alt="Pages"></a>
</p>
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index e6666b1..f9fb3cd 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -76,7 +76,13 @@ npx @cobusgreyling/loop-audit . --badge
Agents can query patterns, skills, and state on demand instead of stuffing docs into every prompt. Copy the config stub from [examples/mcp/loop-engineering.mcp.json](../examples/mcp/loop-engineering.mcp.json) into your MCP client settings.
-**npm publish is pending** — run the server from a cloned `loop-engineering` repo for now:
+Run the server from npm (no clone required):
+
+```bash
+LOOP_PROJECT_ROOT=. npx @cobusgreyling/loop-mcp-server
+```
+
+Or from a cloned `loop-engineering` repo for local development:
```bash
cd path/to/loop-engineering/tools/mcp-server && npm ci && npm run build
@@ -173,6 +179,9 @@ npx @cobusgreyling/loop-audit . --suggest
# Optional badge for your README
npx @cobusgreyling/loop-audit . --badge
+
+# Optional MCP runtime lookup (patterns, skills, state on demand)
+LOOP_PROJECT_ROOT=. npx @cobusgreyling/loop-mcp-server
```
## Learn the why (optional, 10 minutes)
diff --git a/tools/loop-worktree/dist/worktree.js b/tools/loop-worktree/dist/worktree.js
index b99428e..4294365 100644
--- a/tools/loop-worktree/dist/worktree.js
+++ b/tools/loop-worktree/dist/worktree.js
@@ -1,6 +1,6 @@
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
-import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, access, realpath } from 'node:fs/promises';
import path from 'node:path';
const run = promisify(execFile);
export const MANIFEST_DIR = '.loop-worktrees';
@@ -154,13 +154,15 @@ export async function cleanupWorktrees(input) {
}
/** Paths (repo-relative, posix) of every worktree git currently knows about. */
async function gitWorktreePaths(root) {
+ const rootReal = await realpath(root);
const out = await git(['worktree', 'list', '--porcelain'], root);
const paths = [];
for (const line of out.split('\n')) {
if (!line.startsWith('worktree '))
continue;
const abs = line.slice('worktree '.length).trim();
- const rel = path.relative(root, abs).split(path.sep).join('/');
+ const absReal = await realpath(abs);
+ const rel = path.relative(rootReal, absReal).split(path.sep).join('/');
paths.push(rel);
}
return paths;
diff --git a/tools/loop-worktree/src/worktree.ts b/tools/loop-worktree/src/worktree.ts
index 2fb8c05..cbd7bb5 100644
--- a/tools/loop-worktree/src/worktree.ts
+++ b/tools/loop-worktree/src/worktree.ts
@@ -1,6 +1,6 @@
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
-import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, access, realpath } from 'node:fs/promises';
import path from 'node:path';
const run = promisify(execFile);
@@ -215,12 +215,14 @@ export async function cleanupWorktrees(input: CleanupInput): Promise<CleanupResu
/** Paths (repo-relative, posix) of every worktree git currently knows about. */
async function gitWorktreePaths(root: string): Promise<string[]> {
+ const rootReal = await realpath(root);
const out = await git(['worktree', 'list', '--porcelain'], root);
const paths: string[] = [];
for (const line of out.split('\n')) {
if (!line.startsWith('worktree ')) continue;
const abs = line.slice('worktree '.length).trim();
- const rel = path.relative(root, abs).split(path.sep).join('/');
+ const absReal = await realpath(abs);
+ const rel = path.relative(rootReal, absReal).split(path.sep).join('/');
paths.push(rel);
}
return paths;