aiblueprint-cli 1.4.45 → 1.4.48

package/{claude-code-config → ai-config}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aibp-base",
   "version": "1.0.1",
-  "description": "AIBlueprint base configuration with custom agents, slash commands, hooks, and productivity workflows for Claude Code",
+  "description": "AIBlueprint base configuration with custom agents, slash commands, skills, and productivity workflows for Claude Code",
   "author": {
     "name": "Melvyn",
     "url": "https://github.com/melvynx"
@@ -15,7 +15,7 @@
     "productivity",
     "agents",
     "commands",
-    "hooks",
+    "skills",
     "workflows",
     "statusline"
   ],

package/ai-config/scripts/CLAUDE.md

@@ -0,0 +1,31 @@
+# Scripts - Project Memory
+
+Houses the statusline script for Claude Code.
+
+## Structure
+
+```
+scripts/
+├── statusline/           # Custom statusline for Claude Code
+└── package.json          # Root package
+```
+
+## Commands
+
+```bash
+bun run test              # Run statusline tests
+bun run lint              # Lint
+```
+
+### Per-Package Commands
+
+| Package | Test | Start |
+|---------|------|-------|
+| statusline | `bun run statusline:test` | `bun run statusline:start` |
+
+## Cross-Platform Support
+
+The statusline supports macOS, Linux, and Windows (via WSL):
+- Use `path.join()` instead of string concatenation
+- Use `os.homedir()` instead of `process.env.HOME`
+- Use `path.sep` or regex `[/\\]` for path splitting

package/{claude-code-config → ai-config}/scripts/package.json

@@ -2,14 +2,7 @@
   "name": "scripts",
   "type": "module",
   "scripts": {
-    "test": "bun test auto-rename-session claude-code-ai statusline command-validator",
-    "auto-rename:start": "bun auto-rename-session/src/index.ts",
-    "auto-rename:rename-all": "bun auto-rename-session/src/rename-all.ts",
-    "auto-rename:test": "bun test auto-rename-session",
-    "validator:cli": "bun command-validator/src/cli.ts",
-    "validator:test": "bun test command-validator",
-    "validator:lint": "biome check --write command-validator",
-    "ai:test": "bun test claude-code-ai",
+    "test": "bun test statusline",
     "statusline:start": "bun statusline/src/index.ts",
     "statusline:test-fixtures": "bun statusline/test-with-fixtures.ts",
     "statusline:test": "bun test statusline",

package/ai-config/skills/codex-environment/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: codex-environment
+description: Create, inspect, or repair Codex app Local Environment configuration for worktrees, including .codex/environments/environment.toml, setup and cleanup scripts, worktree up/down scripts, copied env files, isolated databases, and reusable app actions.
+---
+
+# Codex Environment
+
+Use this skill when the user asks about Codex Local Environments, worktree setup scripts, cleanup scripts, Codex actions, `.codex/environments/environment.toml`, `CODEX_WORKTREE_PATH`, `CODEX_SOURCE_TREE_PATH`, or making a worktree ready to run.
+
+## What We Learned
+
+- Codex app Local Environments are project config, not one-off terminal commands.
+- The shareable config lives at `.codex/environments/environment.toml` at the project root.
+- Setup scripts run when Codex creates a new worktree for a new thread.
+- Cleanup scripts run before Codex cleans up the worktree.
+- Actions appear in the Codex app top bar and run in the integrated terminal.
+- Worktrees only contain checked-in files, so ignored files like `.env` must be copied or recreated by setup.
+- Prefer short setup/cleanup entries that call versioned project scripts instead of long inline shell.
+- Keep executable entrypoints in `scripts/`, for example `scripts/worktree-up` and `scripts/worktree-down`.
+- Keep `.codex` focused on Codex config; keep operational logic in `scripts/`.
+- Do not commit secrets. It is fine for setup to copy ignored env files locally.
+- For projects with local databases, setup should create a worktree-specific DB name and rewrite the copied `.env` to point to it.
+- Cleanup should drop only the worktree-specific databases and remove copied local env files.
+- Use `CODEX_SOURCE_TREE_PATH` for the original project checkout and `CODEX_WORKTREE_PATH` for the new worktree when available.
+
+## Preferred Shape
+
+Create or update:
+
+```text
+.codex/
+└── environments/
+    └── environment.toml
+scripts/
+├── worktree-up
+├── worktree-down
+├── codex-dev.sh
+└── project-specific helpers...
+```
+
+Use this `environment.toml` pattern:
+
+```toml
+# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
+version = 1
+name = "Project Worktree"
+
+[setup]
+script = "cd \"$CODEX_WORKTREE_PATH\"\nscripts/worktree-up"
+
+[cleanup]
+script = "cd \"$CODEX_WORKTREE_PATH\"\nscripts/worktree-down"
+
+[[actions]]
+name = "Dev"
+icon = "tool"
+command = "scripts/codex-dev.sh"
+
+[[actions]]
+name = "Typecheck"
+icon = "tool"
+command = "pnpm ts"
+
+[[actions]]
+name = "Unit tests"
+icon = "tool"
+command = "pnpm test:ci"
+
+[[actions]]
+name = "Lint"
+icon = "tool"
+command = "pnpm lint:ci"
+```
+
+Keep setup script content small:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "${CODEX_WORKTREE_PATH:-$(pwd)}"
+scripts/make-worktree-ready.sh
+```
+
+Keep cleanup script content small:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "${CODEX_WORKTREE_PATH:-$(pwd)}"
+scripts/worktree-db-down.sh
+```
+
+## Setup Script Rules
+
+When writing `scripts/worktree-up` or its helper:
+
+- Start with `set -euo pipefail`.
+- `cd "${CODEX_WORKTREE_PATH:-$(pwd)}"` before touching files.
+- Locate the source checkout with `CODEX_SOURCE_TREE_PATH`, then a project-specific fallback like `$HOME/Developer/saas/<repo>`.
+- Copy ignored env files from source to worktree, usually `.env`, `.env.local`, and `.env.development.local`.
+- Prefer project package manager conventions, for example `pnpm install`, never `npm install` in a pnpm repo.
+- Create a deterministic worktree DB name from the branch or target worktree, replacing `/` with `-`.
+- Rewrite only DB-related env values in the copied `.env`.
+- Run project generation steps needed after env setup, for example `pnpm prisma:generate`.
+- Make reruns idempotent. If the DB already exists, skip import unless a reset env var is set.
+- Add an explicit reset escape hatch such as `LUMAIL_RESET_DB=1`.
+
+## Cleanup Script Rules
+
+When writing `scripts/worktree-down` or its helper:
+
+- Read DB names from the worktree `.env`, not from guessed branch names.
+- Drop only the DBs referenced by the worktree env.
+- Use `dropdb --if-exists` and a maintenance database.
+- Remove copied local env files from the worktree after DB cleanup.
+- If env files or PostgreSQL tools are missing, exit cleanly with a short message.
+
+## Actions
+
+Use actions for commands the user will run often:
+
+- `Dev`: start the app, ideally via a script that finds a free port.
+- `Typecheck`: `pnpm ts`, `npm run typecheck`, or equivalent.
+- `Unit tests`: the project unit test command.
+- `Lint`: the CI lint command.
+- `E2E`: optional, only if it is not too expensive/noisy for a quick action.
+
+For dev servers, prefer a script like:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "${CODEX_WORKTREE_PATH:-$(pwd)}"
+
+port="${CODEX_DEV_PORT_START:-3910}"
+while lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; do
+  port=$((port + 1))
+done
+
+echo "Starting app on http://localhost:$port"
+exec pnpm dev -p "$port"
+```
+
+## Verification
+
+After editing a Codex environment:
+
+```bash
+bash -n scripts/worktree-up scripts/worktree-down
+sed -n '1,220p' .codex/environments/environment.toml
+git status --short
+```
+
+If Python 3.11+ is available, validate TOML:
+
+```bash
+python3 - <<'PY'
+import tomllib
+with open(".codex/environments/environment.toml", "rb") as f:
+    tomllib.load(f)
+PY
+```
+
+## Guardrails
+
+- Do not read or write `.conductor` directories.
+- Do not print full env values or secrets in logs; print only DB names or redacted hosts.
+- Do not create duplicate environments when the user already has one; update the existing `.codex/environments/environment.toml`.
+- Do not put large fragile shell programs directly in TOML strings.
+- Do not hardcode a dev port unless the user asks; pick a free port or allow `PORT`.
+- Do not drop databases unless their names come from the worktree env or from an explicit user-provided target.
+- If the environment is meant for future worktrees, ensure the `.codex` config and scripts are present in the source checkout/main branch, not only the current Codex worktree.
+
+## Online References
+
+- OpenAI Codex Local Environments: https://developers.openai.com/codex/app/local-environments
+- OpenAI Codex Worktrees: https://developers.openai.com/codex/app/worktrees
+- `CODEX_SOURCE_TREE_PATH` / `CODEX_WORKTREE_PATH` community note: https://zenn.dev/route06/articles/c1f686b4479957
+- Codex app environment TOML practice note: https://zenn.dev/devneko/articles/8a5f6f44adf606