@softspark/ai-toolkit 3.1.0 → 3.1.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v3.1.1 — Windows install fix (2026-04-29)
+
+Patch release. `ai-toolkit install --local` crashed on Windows before doing any work because `scripts/install_steps/project_registry.py` imported `fcntl` (POSIX-only) at module load, raising `ModuleNotFoundError: No module named 'fcntl'`.
+
+### Fixed
+
+- **Windows install crash** — `project_registry` now imports `fcntl` and `msvcrt` defensively (try/except → `None`) and `_registry_lock()` selects between `fcntl.flock` (POSIX) and `msvcrt.locking` (Windows) at runtime. POSIX semantics unchanged; Windows acquires the lock with `LK_NBLCK` + 30 s deadline + 10 ms retry backoff.
+
+### Added
+
+- **Windows compat regression test** — `tests/test_windows_support.bats` now blocks `import fcntl` via a custom `meta_path` finder, stubs `msvcrt`, and forces the Windows branch of `_registry_lock` so future regressions are caught on the POSIX CI runners without needing a Windows machine.
+
 ## v3.1.0 — Global Editor Install Alignment (2026-04-28)
 
 Minor release aligning global and project-local editor configuration with the current documented surfaces for all supported editors.

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-112-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-973%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-974%20passing-success)](tests/)
 
 <p align="center">
   <img src="assets/ai-toolkit-readme-hero.png" alt="ai-toolkit 3 README hero showing one toolkit for 12 AI editors" width="900">
@@ -14,33 +14,12 @@
 
 ---
 
-## What's New in v3.1.0
+## What's New in v3.1.1
 
-**3.1.0 aligns global and project-local editor installs** with the current documented config surfaces for all 12 supported tools.
+Patch release fixing the Windows install crash introduced when project registration started using a POSIX-only file lock.
 
-- `ai-toolkit install --editors cline` now writes documented global rules under `~/Documents/Cline/Rules/`.
-- `ai-toolkit install --editors roo` now writes documented global rules under `~/.roo/rules/`.
-- `ai-toolkit install --editors aider` safely creates `~/.aider.conf.yml` only when absent and refreshes `~/.aider-ai-toolkit-CONVENTIONS.md`.
-- Roo Code now has project MCP sync via `.roo/mcp.json` from the canonical `.mcp.json`.
-- Cursor rules are explicitly project-local; Cursor MCP remains supported at project/global scope through `.cursor/mcp.json`.
-
-### Carried from v3.0.0 (feature release)
-
-- **Deep coverage: every editor at 100% of its native surface.** New generators emit hooks, sub-agents, custom commands, and skill pointers per editor: `generate_cursor_agents.py`, `generate_cursor_hooks.py`, `generate_windsurf_hooks.py`, `generate_gemini_commands.py`, `generate_gemini_hooks.py`, `generate_gemini_skills.py`, `generate_augment_agents.py`, `generate_augment_commands.py`, `generate_augment_hooks.py`, `generate_augment_skills.py`, `generate_codex_skills.py`.
-- **`--profile full`** turns on every native surface across all supported editors in one flag. `minimal` / `standard` / `strict` retain prior semantics but `standard` now also wires Gemini hooks and the Copilot directory layout (see Breaking Changes).
-- **Codex skill mirroring** uses Codex's native `.agents/skills/` discovery path. `--editors codex` installs translated skills there; `--codex-skills` explicitly refreshes the same catalog.
-- **58 new bats tests** covering native surface generators plus per-editor suites for aider, antigravity, augment, claude-code, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf.
-- **Skill quality pass** (folded in from the 2.12 work that is now skipped): 62 skills upgraded to 4-5 / 5 on the meta-architect audit; `add_gotcha` added as a fifth mutation strategy.
-
-### Breaking changes (from 3.0.0)
-
-- `--profile standard` now installs **Gemini hooks** automatically. To opt out, use `--profile minimal` or pass `--skip gemini-hooks`.
-- Copilot now uses the **directory layout** (`.github/copilot/`) instead of a single monolithic file. Existing single-file installs are preserved but new installs emit the directory form.
-- `2.13.0` is skipped. Upgrade path is `2.12.x` → `3.0.0`.
-
-### Non-breaking additions (opt-in)
-
-- `.windsurf/hooks.json`, `.cursor/hooks.json`, `.cursor/agents/`, `.augment/agents/`, `.augment/commands/`, and `.gemini/commands/` are **only emitted when you opt in** via `--profile full`. Codex skills are emitted under `.agents/skills/` whenever the Codex editor target is selected, matching Codex's native discovery path.
+- **Windows install no longer crashes** — `ai-toolkit install --local` on Windows hit `ModuleNotFoundError: No module named 'fcntl'` before doing any work. The project registry now selects `fcntl` (POSIX) or `msvcrt.locking` (Windows) at runtime; POSIX semantics are unchanged.
+- **Regression test on POSIX CI** — `tests/test_windows_support.bats` simulates the missing-`fcntl` scenario and exercises the Windows lock branch via a stubbed `msvcrt`, so this regression is caught without a Windows runner.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -173,7 +152,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (973 tests)
+├── tests/               # Bats test suite (974 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.1.0",
+  "version": "3.1.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "AI coding toolkit: 112 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/install_steps/project_registry.py

@@ -9,7 +9,6 @@ Stdlib-only — no external dependencies.
 from __future__ import annotations
 
 import contextlib
-import fcntl
 import json
 import os
 import sys
@@ -19,6 +18,16 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Generator
 
+try:
+    import fcntl  # POSIX-only
+except ImportError:
+    fcntl = None  # type: ignore[assignment]
+
+try:
+    import msvcrt  # Windows-only
+except ImportError:
+    msvcrt = None  # type: ignore[assignment]
+
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 from paths import PROJECTS_FILE
 
@@ -26,24 +35,48 @@ from paths import PROJECTS_FILE
 _LOAD_RETRIES = 3
 _LOAD_RETRY_DELAY = 0.05  # 50ms
 
+# Registry lock acquisition timeout (seconds)
+_LOCK_TIMEOUT = 30.0
+_LOCK_RETRY_DELAY = 0.01
+
 
 @contextlib.contextmanager
 def _registry_lock() -> Generator[None, None, None]:
     """Exclusive file lock for read-modify-write on projects.json.
 
     Prevents concurrent processes from interleaving loads and saves,
-    which can silently drop entries.
+    which can silently drop entries. Cross-platform: POSIX uses
+    fcntl.flock, Windows uses msvcrt.locking.
     """
     path = _registry_path()
     path.parent.mkdir(parents=True, exist_ok=True)
     lock_path = path.with_suffix(".lock")
     fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR)
     try:
-        fcntl.flock(fd, fcntl.LOCK_EX)
+        if os.name == "nt":
+            deadline = time.monotonic() + _LOCK_TIMEOUT
+            while True:
+                try:
+                    msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                    break
+                except OSError:
+                    if time.monotonic() > deadline:
+                        raise
+                    time.sleep(_LOCK_RETRY_DELAY)
+        else:
+            fcntl.flock(fd, fcntl.LOCK_EX)
         yield
     finally:
-        fcntl.flock(fd, fcntl.LOCK_UN)
-        os.close(fd)
+        try:
+            if os.name == "nt":
+                with contextlib.suppress(OSError):
+                    os.lseek(fd, 0, 0)
+                with contextlib.suppress(OSError):
+                    msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+            else:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+        finally:
+            os.close(fd)
 
 
 def _registry_path() -> Path: