Skip to content

Fix Windows Codex launcher + Node ESM compatibility #168

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
danshapiro wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Fix Windows Codex launcher + Node ESM compatibility #168

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion .codex/INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,4 +32,14 @@ Test the installation:
~/.codex/superpowers/.codex/superpowers-codex bootstrap
```

You should see skill listings and bootstrap instructions. The system is now ready for use.
On Windows, use one of these instead:

```bash
~/.codex/superpowers/.codex/superpowers-codex.cmd bootstrap
```

```bash
node ~/.codex/superpowers/.codex/superpowers-codex bootstrap
```

You should see skill listings and bootstrap instructions. The system is now ready for use.
2 changes: 2 additions & 0 deletions .codex/superpowers-bootstrap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ You have superpowers.

**Tool for running skills:**
- `~/.codex/superpowers/.codex/superpowers-codex use-skill <skill-name>`
- On Windows: `~/.codex/superpowers/.codex/superpowers-codex.cmd use-skill <skill-name>` (recommended)
- On any OS: `node ~/.codex/superpowers/.codex/superpowers-codex use-skill <skill-name>`

**Tool Mapping for Codex:**
When skills reference tools you don't have, substitute your equivalent tools:
Expand Down
68 changes: 41 additions & 27 deletions .codex/superpowers-codex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
const fs = require('fs');
const path = require('path');
const os = require('os');
const skillsCore = require('../lib/skills-core');
const { pathToFileURL } = require('url');

let skillsCore;

// Paths
const homeDir = os.homedir();
Expand Down Expand Up @@ -238,30 +240,42 @@ function runUseSkill(skillName) {

}

// Main CLI
const command = process.argv[2];
const arg = process.argv[3];

switch (command) {
case 'bootstrap':
runBootstrap();
break;
case 'use-skill':
runUseSkill(arg);
break;
case 'find-skills':
runFindSkills();
break;
default:
console.log('Superpowers for Codex');
console.log('Usage:');
console.log(' superpowers-codex bootstrap # Run complete bootstrap with all skills');
console.log(' superpowers-codex use-skill <skill-name> # Load a specific skill');
console.log(' superpowers-codex find-skills # List all available skills');
console.log('');
console.log('Examples:');
console.log(' superpowers-codex bootstrap');
console.log(' superpowers-codex use-skill superpowers:brainstorming');
console.log(' superpowers-codex use-skill my-custom-skill');
break;
async function main() {
// `lib/skills-core.mjs` is an ES module. This CLI is intentionally
// extensionless (for Unix shebang execution), so we keep it CommonJS and
// dynamically import the shared core for compatibility.
const skillsCoreUrl = pathToFileURL(path.join(__dirname, '..', 'lib', 'skills-core.mjs')).href;
skillsCore = await import(skillsCoreUrl);

const command = process.argv[2];
const arg = process.argv[3];

switch (command) {
case 'bootstrap':
runBootstrap();
break;
case 'use-skill':
runUseSkill(arg);
break;
case 'find-skills':
runFindSkills();
break;
default:
console.log('Superpowers for Codex');
console.log('Usage:');
console.log(' superpowers-codex bootstrap # Run complete bootstrap with all skills');
console.log(' superpowers-codex use-skill <skill-name> # Load a specific skill');
console.log(' superpowers-codex find-skills # List all available skills');
console.log('');
console.log('Examples:');
console.log(' superpowers-codex bootstrap');
console.log(' superpowers-codex use-skill superpowers:brainstorming');
console.log(' superpowers-codex use-skill my-custom-skill');
break;
}
}

main().catch((error) => {
console.error(error?.stack || String(error));
process.exitCode = 1;
});
12 changes: 12 additions & 0 deletions .codex/superpowers-codex.cmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
@echo off
setlocal

REM Windows shim for the extensionless Unix-style Node launcher (superpowers-codex).
REM This enables running:
REM C:\Users\dan\.codex\superpowers\.codex\superpowers-codex.cmd bootstrap
REM or (in many shells) just:
REM superpowers-codex bootstrap
REM when this directory is on PATH.

node "%~dp0superpowers-codex" %*

Comment on lines +1 to +12
Copy link

@coderabbitai coderabbitai bot Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Exit code is not propagated to the caller.

When node exits with a non-zero code (e.g., on error), the batch script doesn't forward it, which could mislead callers or CI scripts expecting accurate exit status.

Apply this diff to preserve the exit code:

 @echo off
 setlocal
 
 REM Windows shim for the extensionless Unix-style Node launcher (superpowers-codex).
 REM This enables running:
 REM   C:\Users\dan\.codex\superpowers\.codex\superpowers-codex.cmd bootstrap
 REM or (in many shells) just:
 REM   superpowers-codex bootstrap
 REM when this directory is on PATH.
 
-node "%~dp0superpowers-codex" %*
+node "%~dp0superpowers-codex" %*
+exit /b %errorlevel%
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
@echo off
setlocal
REM Windows shim for the extensionless Unix-style Node launcher (superpowers-codex).
REM This enables running:
REM C:\Users\dan\.codex\superpowers\.codex\superpowers-codex.cmd bootstrap
REM or (in many shells) just:
REM superpowers-codex bootstrap
REM when this directory is on PATH.
node "%~dp0superpowers-codex" %*
@echo off
setlocal
REM Windows shim for the extensionless Unix-style Node launcher (superpowers-codex).
REM This enables running:
REM C:\Users\dan\.codex\superpowers\.codex\superpowers-codex.cmd bootstrap
REM or (in many shells) just:
REM superpowers-codex bootstrap
REM when this directory is on PATH.
node "%~dp0superpowers-codex" %*
exit /b %errorlevel%
🤖 Prompt for AI Agents 
.codex/superpowers-codex.cmd lines 1-12: the batch shim runs node but does not
propagate node's exit code to the caller; after invoking node
"%~dp0superpowers-codex" %* capture and return node's exit code by exiting the
script with the current ERRORLEVEL (add a final line to exit /b %ERRORLEVEL% so
callers/CI receive the same exit status).

2 changes: 1 addition & 1 deletion .opencode/plugin/superpowers.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import fs from 'fs';
import os from 'os';
import { fileURLToPath } from 'url';
import { tool } from '@opencode-ai/plugin/tool';
import * as skillsCore from '../../lib/skills-core.js';
import * as skillsCore from '../../lib/skills-core.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

Expand Down
4 changes: 2 additions & 2 deletions RELEASE-NOTES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,13 @@
- Auto re-injection on session.compacted events
- Three-tier skill priority: project > personal > superpowers
- Project-local skills support (`.opencode/skills/`)
- Shared core module (`lib/skills-core.js`) for code reuse with Codex
- Shared core module (`lib/skills-core.mjs`) for code reuse with Codex
- Automated test suite with proper isolation (`tests/opencode/`)
- Platform-specific documentation (`docs/README.opencode.md`, `docs/README.codex.md`)

### Changed

- **Refactored Codex Implementation**: Now uses shared `lib/skills-core.js` ES module
- **Refactored Codex Implementation**: Now uses shared `lib/skills-core.mjs` ES module
- Eliminates code duplication between Codex and OpenCode
- Single source of truth for skill discovery and parsing
- Codex successfully loads ES modules via Node.js interop
Expand Down
12 changes: 11 additions & 1 deletion docs/README.codex.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,14 +91,18 @@ Personal skills override superpowers skills with the same name.

**Location:** `~/.codex/superpowers/.codex/superpowers-codex`

On Windows, prefer one of these:
- `~/.codex/superpowers/.codex/superpowers-codex.cmd <command>` (recommended)
- `node ~/.codex/superpowers/.codex/superpowers-codex <command>`

A Node.js CLI script that provides three commands:
- `bootstrap` - Load complete bootstrap with all skills
- `use-skill <name>` - Load a specific skill
- `find-skills` - List all available skills

### Shared Core Module

**Location:** `~/.codex/superpowers/lib/skills-core.js`
**Location:** `~/.codex/superpowers/lib/skills-core.mjs`

The Codex implementation uses the shared `skills-core` module (ES module format) for skill discovery and parsing. This is the same module used by the OpenCode plugin, ensuring consistent behavior across platforms.

Expand Down Expand Up @@ -132,6 +136,12 @@ git pull
chmod +x ~/.codex/superpowers/.codex/superpowers-codex
```

On Windows, use the shim instead:

```bash
~/.codex/superpowers/.codex/superpowers-codex.cmd find-skills
```

### Node.js errors

The CLI script requires Node.js. Verify:
Expand Down
4 changes: 2 additions & 2 deletions docs/README.opencode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,11 +157,11 @@ Skills written for Claude Code are automatically adapted for OpenCode. The plugi
- Two custom tools: `use_skill`, `find_skills`
- chat.message hook for initial context injection
- event handler for session.compacted re-injection
- Uses shared `lib/skills-core.js` module (also used by Codex)
- Uses shared `lib/skills-core.mjs` module (also used by Codex)

### Shared Core Module

**Location:** `~/.config/opencode/superpowers/lib/skills-core.js`
**Location:** `~/.config/opencode/superpowers/lib/skills-core.mjs`

**Functions:**
- `extractFrontmatter()` - Parse skill metadata
Expand Down
12 changes: 6 additions & 6 deletions docs/plans/2025-11-22-opencode-support-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ OpenCode.ai is a coding agent similar to Claude Code and Codex. Previous attempt

### High-Level Structure

1. **Shared Core Module** (`lib/skills-core.js`)
1. **Shared Core Module** (`lib/skills-core.mjs`)
- Common skill discovery and parsing logic
- Used by both Codex and OpenCode implementations

Expand All @@ -46,7 +46,7 @@ OpenCode.ai is a coding agent similar to Claude Code and Codex. Previous attempt
Extract common functionality from `.codex/superpowers-codex` into shared module:

```javascript
// lib/skills-core.js
// lib/skills-core.mjs
module.exports = {
extractFrontmatter(filePath), // Parse name + description from YAML
findSkillsInDir(dir, maxDepth), // Recursive SKILL.md discovery
Expand Down Expand Up @@ -200,7 +200,7 @@ export const SuperpowersPlugin = async ({ client, directory, $ }) => {
```
superpowers/
├── lib/
│ └── skills-core.js # NEW: Shared skill logic
│ └── skills-core.mjs # NEW: Shared skill logic
├── .codex/
│ ├── superpowers-codex # UPDATED: Use skills-core
│ ├── superpowers-bootstrap.md
Expand All @@ -216,14 +216,14 @@ superpowers/

### Phase 1: Refactor Shared Core

1. Create `lib/skills-core.js`
1. Create `lib/skills-core.mjs`
- Extract frontmatter parsing from `.codex/superpowers-codex`
- Extract skill discovery logic
- Extract path resolution (with shadowing)
- Update to use only `name` and `description` (no `when_to_use`)

2. Update `.codex/superpowers-codex` to use shared core
- Import from `../lib/skills-core.js`
- Import from `../lib/skills-core.mjs`
- Remove duplicated code
- Keep CLI wrapper logic

Expand All @@ -235,7 +235,7 @@ superpowers/
### Phase 2: Build OpenCode Plugin

1. Create `.opencode/plugin/superpowers.js`
- Import shared core from `../../lib/skills-core.js`
- Import shared core from `../../lib/skills-core.mjs`
- Implement plugin function
- Define custom tools (use_skill, find_skills)
- Implement session.started hook
Expand Down
Loading