@jefferylau/euphony-skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# Euphony Skills
+
+[English](README.md) | [简体中文](README_CN.md)
+
+Install local Euphony viewer skills for Codex and CodeBuddy.
+
+This repository contains two independent skills with one npm-based installer:
+
+- `skills/codex-euphony`: opens local Codex session JSONL logs in OpenAI Euphony.
+- `skills/codebuddy-euphony`: converts local CodeBuddy session JSONL logs into an Euphony-compatible shape and opens them in OpenAI Euphony.
+
+Each skill directory is self-contained, so it can still be installed by path. The npm CLI is the recommended install path because it handles both host applications consistently.
+
+## Requirements
+
+- Node.js 18 or newer.
+- `git`, used when a skill needs to clone the Euphony runtime checkout.
+- `pnpm` or `corepack`, used to install and run Euphony.
+- macOS, Linux, or Windows with a local browser opener.
+
+The installer itself does not install Euphony dependencies. The selected skill does that lazily the first time it starts Euphony.
+At runtime the skill prefers an installed `pnpm`; when only Corepack is available, it uses `corepack pnpm` and sets `COREPACK_INTEGRITY_KEYS=0` for that subprocess to avoid known Corepack pnpm signature bootstrap failures.
+
+## Quick Install
+
+Install from npm after the package is published:
+
+```bash
+npx @jefferylau/euphony-skills install codex
+npx @jefferylau/euphony-skills install codebuddy
+npx @jefferylau/euphony-skills install all
+```
+
+Replace an existing install:
+
+```bash
+npx @jefferylau/euphony-skills install all --force
+```
+
+Remove installed skills:
+
+```bash
+npx @jefferylau/euphony-skills uninstall all
+```
+
+Check local state:
+
+```bash
+npx @jefferylau/euphony-skills doctor
+```
+
+Restart Codex or CodeBuddy after installing so the host application reloads skills.
+
+## Local Checkout Install
+
+From a cloned repository:
+
+```bash
+git clone https://github.com/liiujinfu/euphony-skills.git
+cd euphony-skills
+node bin/euphony-skills.mjs install all --force
+```
+
+For local development, install with symlinks so edits in this repository are picked up immediately:
+
+```bash
+node bin/euphony-skills.mjs install all --force --link
+```
+
+For normal end users, prefer copy install without `--link`.
+
+## Install Targets
+
+Codex installs to:
+
+```text
+${CODEX_HOME:-~/.codex}/skills/codex-euphony
+```
+
+CodeBuddy installs to:
+
+```text
+${CODEBUDDY_HOME:-~/.codebuddy}/skills/codebuddy-euphony
+```
+
+Override host homes when needed:
+
+```bash
+CODEX_HOME=/custom/.codex npx @jefferylau/euphony-skills install codex
+CODEBUDDY_HOME=/custom/.codebuddy npx @jefferylau/euphony-skills install codebuddy
+```
+
+## CLI Reference
+
+```bash
+euphony-skills install codex [--force] [--link]
+euphony-skills install codebuddy [--force] [--link]
+euphony-skills install all [--force] [--link]
+euphony-skills uninstall codex
+euphony-skills uninstall codebuddy
+euphony-skills uninstall all
+euphony-skills doctor
+```
+
+Options:
+
+- `--force`: replace an existing install.
+- `--link`: create a symlink from the host skill directory to this checkout. Use this for development only.
+
+## Using The Skills
+
+After installing and restarting the host app, ask the assistant to open the latest session with Euphony.
+
+Codex examples:
+
+```text
+Use codex-euphony to open the latest Codex session.
+Open this Codex conversation in Euphony.
+```
+
+CodeBuddy examples:
+
+```text
+Use codebuddy-euphony to open the latest CodeBuddy session.
+Open this CodeBuddy conversation in Euphony.
+```
+
+You can also run the scripts directly.
+
+Codex:
+
+```bash
+node ~/.codex/skills/codex-euphony/scripts/codex-euphony.mjs open
+node ~/.codex/skills/codex-euphony/scripts/codex-euphony.mjs status
+node ~/.codex/skills/codex-euphony/scripts/codex-euphony.mjs stop
+```
+
+CodeBuddy:
+
+```bash
+~/.codebuddy/skills/codebuddy-euphony/scripts/codebuddy-euphony.mjs open
+~/.codebuddy/skills/codebuddy-euphony/scripts/codebuddy-euphony.mjs status
+~/.codebuddy/skills/codebuddy-euphony/scripts/codebuddy-euphony.mjs stop
+```
+
+## Runtime Behavior
+
+The installer only copies or links skill folders. It does not copy session logs, generated JSONL files, local caches, or Euphony checkouts.
+
+At runtime:
+
+- Codex uses `${CODEX_HOME:-~/.codex}/cache/euphony`.
+- CodeBuddy uses `${CODEBUDDY_HOME:-~/.codebuddy}/cache/euphony`.
+- If the cache is deleted, the skill recreates it on the next command that needs Euphony.
+- The local Euphony server binds to `127.0.0.1`.
+- The default port is `3000`.
+- Codex staging uses a symlink on macOS/Linux and a copy on Windows by default. Set `EUPHONY_STAGE_MODE=copy` to force snapshot staging everywhere.
+- Background servers are tracked with a pid file under the Euphony cache, so `stop` only controls servers started by the same skill script.
+
+If port `3000` is already occupied, use another port:
+
+```bash
+EUPHONY_PORT=3001 node ~/.codex/skills/codex-euphony/scripts/codex-euphony.mjs open
+EUPHONY_PORT=3001 ~/.codebuddy/skills/codebuddy-euphony/scripts/codebuddy-euphony.mjs open
+```
+
+Windows PowerShell example:
+
+```powershell
+$env:EUPHONY_PORT = "3001"
+node "$env:USERPROFILE\.codex\skills\codex-euphony\scripts\codex-euphony.mjs" open
+```
+
+## Privacy
+
+Session JSONL files can contain prompts, paths, tool output, and secrets that appeared in conversations. The skills serve staged session data only from a local `127.0.0.1` Euphony instance.
+
+Do not commit generated session files, staged JSONL output, `.env` files, or Euphony cache directories. This repository's package contents are limited to the CLI, README files, LICENSE, and skill source files.
+
+## Troubleshooting
+
+If a host app does not see the skill, restart Codex or CodeBuddy after installation.
+
+If installation says the skill already exists, rerun with `--force`:
+
+```bash
+npx @jefferylau/euphony-skills install codebuddy --force
+```
+
+If Euphony fails to start, check prerequisites:
+
+```bash
+npx @jefferylau/euphony-skills doctor
+```
+
+If `npm` reports cache permission errors, use a temporary cache or repair the npm cache ownership:
+
+```bash
+npm_config_cache=/tmp/euphony-skills-npm-cache npx @jefferylau/euphony-skills doctor
+```
+
+If multiple Euphony servers are running, stop the relevant one or choose a different port:
+
+```bash
+node ~/.codex/skills/codex-euphony/scripts/codex-euphony.mjs stop
+~/.codebuddy/skills/codebuddy-euphony/scripts/codebuddy-euphony.mjs stop
+```
+
+## Development
+
+Run checks:
+
+```bash
+npm run check
+```
+
+Test install behavior without touching real homes:
+
+```bash
+CODEX_HOME=/tmp/euphony-test-codex \
+CODEBUDDY_HOME=/tmp/euphony-test-codebuddy \
+node bin/euphony-skills.mjs install all --force
+```
+
+Test symlink install behavior:
+
+```bash
+CODEX_HOME=/tmp/euphony-test-codex \
+CODEBUDDY_HOME=/tmp/euphony-test-codebuddy \
+node bin/euphony-skills.mjs install all --force --link
+```

package/README_CN.md

@@ -0,0 +1,231 @@
+# Euphony Skills
+
+[English](README.md) | [简体中文](README_CN.md)
+
+为 Codex 和 CodeBuddy 安装本地 Euphony 会话查看 skill。
+
+这个仓库包含两个独立 skill，并提供一个 npm 安装器：
+
+- `skills/codex-euphony`：用 OpenAI Euphony 打开本地 Codex 会话 JSONL。
+- `skills/codebuddy-euphony`：把本地 CodeBuddy 会话 JSONL 转成 Euphony 兼容格式后打开。
+
+每个 skill 目录都是自包含的，也可以按路径单独安装。推荐使用 npm CLI，因为它能统一处理 Codex 和 CodeBuddy 两种宿主。
+
+## 环境要求
+
+- Node.js 18 或更高版本。
+- `git`，skill 首次拉取 Euphony 运行时 checkout 时使用。
+- `pnpm` 或 `corepack`，用于安装和运行 Euphony。
+- macOS、Linux 或 Windows，并支持本地浏览器打开命令。
+
+安装器本身不会安装 Euphony 依赖；对应 skill 会在第一次启动 Euphony 时按需安装。
+运行时会优先使用已安装的 `pnpm`；如果只有 Corepack，则使用 `corepack pnpm`，并仅对该子进程设置 `COREPACK_INTEGRITY_KEYS=0`，避开常见的 Corepack pnpm 签名 bootstrap 失败。
+
+## 快速安装
+
+发布到 npm 后，可以这样安装：
+
+```bash
+npx @jefferylau/euphony-skills install codex
+npx @jefferylau/euphony-skills install codebuddy
+npx @jefferylau/euphony-skills install all
+```
+
+替换已有安装：
+
+```bash
+npx @jefferylau/euphony-skills install all --force
+```
+
+卸载已安装的 skill：
+
+```bash
+npx @jefferylau/euphony-skills uninstall all
+```
+
+检查本机状态：
+
+```bash
+npx @jefferylau/euphony-skills doctor
+```
+
+安装后需要重启 Codex 或 CodeBuddy，让宿主重新加载 skill。
+
+## 本地 Checkout 安装
+
+从本地 clone 安装：
+
+```bash
+git clone https://github.com/liiujinfu/euphony-skills.git
+cd euphony-skills
+node bin/euphony-skills.mjs install all --force
+```
+
+本地开发时可以使用软链接安装，这样修改仓库里的代码会立即生效：
+
+```bash
+node bin/euphony-skills.mjs install all --force --link
+```
+
+普通用户建议使用默认复制安装，不要加 `--link`。
+
+## 安装位置
+
+Codex 安装到：
+
+```text
+${CODEX_HOME:-~/.codex}/skills/codex-euphony
+```
+
+CodeBuddy 安装到：
+
+```text
+${CODEBUDDY_HOME:-~/.codebuddy}/skills/codebuddy-euphony
+```
+
+需要时可以覆盖宿主 home 目录：
+
+```bash
+CODEX_HOME=/custom/.codex npx @jefferylau/euphony-skills install codex
+CODEBUDDY_HOME=/custom/.codebuddy npx @jefferylau/euphony-skills install codebuddy
+```
+
+## CLI 参考
+
+```bash
+euphony-skills install codex [--force] [--link]
+euphony-skills install codebuddy [--force] [--link]
+euphony-skills install all [--force] [--link]
+euphony-skills uninstall codex
+euphony-skills uninstall codebuddy
+euphony-skills uninstall all
+euphony-skills doctor
+```
+
+参数：
+
+- `--force`：替换已有安装。
+- `--link`：从宿主 skill 目录创建到当前 checkout 的软链接，只建议开发时使用。
+
+## 使用方式
+
+安装并重启宿主后，可以直接让助手用 Euphony 打开最新会话。
+
+Codex 示例：
+
+```text
+Use codex-euphony to open the latest Codex session.
+Open this Codex conversation in Euphony.
+```
+
+CodeBuddy 示例：
+
+```text
+Use codebuddy-euphony to open the latest CodeBuddy session.
+Open this CodeBuddy conversation in Euphony.
+```
+
+也可以直接运行脚本。
+
+Codex：
+
+```bash
+node ~/.codex/skills/codex-euphony/scripts/codex-euphony.mjs open
+node ~/.codex/skills/codex-euphony/scripts/codex-euphony.mjs status
+node ~/.codex/skills/codex-euphony/scripts/codex-euphony.mjs stop
+```
+
+CodeBuddy：
+
+```bash
+~/.codebuddy/skills/codebuddy-euphony/scripts/codebuddy-euphony.mjs open
+~/.codebuddy/skills/codebuddy-euphony/scripts/codebuddy-euphony.mjs status
+~/.codebuddy/skills/codebuddy-euphony/scripts/codebuddy-euphony.mjs stop
+```
+
+## 运行时行为
+
+安装器只复制或链接 skill 目录，不会复制会话日志、生成的 JSONL、本地缓存或 Euphony checkout。
+
+运行时：
+
+- Codex 使用 `${CODEX_HOME:-~/.codex}/cache/euphony`。
+- CodeBuddy 使用 `${CODEBUDDY_HOME:-~/.codebuddy}/cache/euphony`。
+- 如果缓存被删除，下一次需要 Euphony 时会自动重建。
+- 本地 Euphony 服务绑定到 `127.0.0.1`。
+- 默认端口是 `3000`。
+- Codex staging 在 macOS/Linux 默认使用软链接，在 Windows 默认复制文件。设置 `EUPHONY_STAGE_MODE=copy` 可以在所有平台强制使用快照复制。
+- 后台服务通过 Euphony cache 下的 pid 文件跟踪，所以 `stop` 只会停止同一个 skill 脚本启动的服务。
+
+如果 `3000` 端口已被占用，可以换端口：
+
+```bash
+EUPHONY_PORT=3001 node ~/.codex/skills/codex-euphony/scripts/codex-euphony.mjs open
+EUPHONY_PORT=3001 ~/.codebuddy/skills/codebuddy-euphony/scripts/codebuddy-euphony.mjs open
+```
+
+Windows PowerShell 示例：
+
+```powershell
+$env:EUPHONY_PORT = "3001"
+node "$env:USERPROFILE\.codex\skills\codex-euphony\scripts\codex-euphony.mjs" open
+```
+
+## 隐私
+
+会话 JSONL 可能包含提示词、路径、工具输出，以及对话中出现过的敏感信息。skill 只会通过本地 `127.0.0.1` Euphony 实例提供临时 staged 数据。
+
+不要提交生成的会话文件、staged JSONL 输出、`.env` 文件或 Euphony 缓存目录。这个仓库的 npm 包内容只包含 CLI、README、LICENSE 和 skill 源码。
+
+## 排错
+
+如果宿主没有识别到 skill，安装后先重启 Codex 或 CodeBuddy。
+
+如果安装提示 skill 已存在，使用 `--force`：
+
+```bash
+npx @jefferylau/euphony-skills install codebuddy --force
+```
+
+如果 Euphony 启动失败，先检查依赖和安装状态：
+
+```bash
+npx @jefferylau/euphony-skills doctor
+```
+
+如果 `npm` 报 cache 权限错误，可以使用临时 cache，或修复 npm cache 目录权限：
+
+```bash
+npm_config_cache=/tmp/euphony-skills-npm-cache npx @jefferylau/euphony-skills doctor
+```
+
+如果有多个 Euphony 服务在跑，停止对应服务或换端口：
+
+```bash
+node ~/.codex/skills/codex-euphony/scripts/codex-euphony.mjs stop
+~/.codebuddy/skills/codebuddy-euphony/scripts/codebuddy-euphony.mjs stop
+```
+
+## 开发
+
+运行检查：
+
+```bash
+npm run check
+```
+
+不影响真实 home 目录的安装测试：
+
+```bash
+CODEX_HOME=/tmp/euphony-test-codex \
+CODEBUDDY_HOME=/tmp/euphony-test-codebuddy \
+node bin/euphony-skills.mjs install all --force
+```
+
+测试软链接安装：
+
+```bash
+CODEX_HOME=/tmp/euphony-test-codex \
+CODEBUDDY_HOME=/tmp/euphony-test-codebuddy \
+node bin/euphony-skills.mjs install all --force --link
+```

package/bin/euphony-skills.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const home = os.homedir();
+const isWindows = process.platform === 'win32';
+
+const targets = {
+  codex: {
+    label: 'Codex',
+    homeEnv: 'CODEX_HOME',
+    defaultHome: path.join(home, '.codex'),
+    skillName: 'codex-euphony',
+    executables: ['scripts/codex-euphony.mjs', 'scripts/codex-euphony.sh']
+  },
+  codebuddy: {
+    label: 'CodeBuddy',
+    homeEnv: 'CODEBUDDY_HOME',
+    defaultHome: path.join(home, '.codebuddy'),
+    skillName: 'codebuddy-euphony',
+    executables: ['scripts/codebuddy-euphony.mjs']
+  }
+};
+
+function usage() {
+  console.log(`Usage: euphony-skills <command> [target] [options]
+
+Commands:
+  install codex|codebuddy|all      Install skill(s).
+  uninstall codex|codebuddy|all    Remove installed skill(s).
+  doctor                           Check local install prerequisites and state.
+  help                             Show this help.
+
+Options:
+  --force    Replace an existing install.
+  --link     Symlink from this checkout instead of copying.
+
+Environment:
+  CODEX_HOME      Override Codex home. Default: ~/.codex
+  CODEBUDDY_HOME  Override CodeBuddy home. Default: ~/.codebuddy`);
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function commandExists(command) {
+  try {
+    if (isWindows) {
+      execFileSync('where', [command], { stdio: 'ignore', shell: true });
+    } else {
+      execFileSync('which', [command], { stdio: 'ignore' });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const flags = new Set(args.filter(arg => arg.startsWith('--')));
+  const positional = args.filter(arg => !arg.startsWith('--'));
+  return {
+    command: positional[0] || 'help',
+    target: positional[1],
+    force: flags.has('--force'),
+    link: flags.has('--link')
+  };
+}
+
+function expandTargets(target) {
+  if (target === 'all') return Object.keys(targets);
+  if (target && targets[target]) return [target];
+  fail(`Unknown target: ${target || '(missing)'}
+
+Expected one of: codex, codebuddy, all`);
+}
+
+function sourceDirFor(targetKey) {
+  return path.join(rootDir, 'skills', targets[targetKey].skillName);
+}
+
+function homeDirFor(targetKey) {
+  const target = targets[targetKey];
+  return process.env[target.homeEnv] || target.defaultHome;
+}
+
+function installDirFor(targetKey) {
+  return path.join(homeDirFor(targetKey), 'skills', targets[targetKey].skillName);
+}
+
+function removeExisting(dest) {
+  if (!pathExists(dest)) return;
+  fs.rmSync(dest, { recursive: true, force: true });
+}
+
+function pathExists(file) {
+  return fs.lstatSync(file, { throwIfNoEntry: false }) !== undefined;
+}
+
+function copyRecursive(src, dest) {
+  fs.cpSync(src, dest, {
+    recursive: true,
+    dereference: false,
+    filter: source => !source.split(path.sep).includes('.git')
+  });
+}
+
+function chmodExecutables(targetKey) {
+  if (isWindows) return;
+  const target = targets[targetKey];
+  const dest = installDirFor(targetKey);
+  for (const relative of target.executables) {
+    const file = path.join(dest, relative);
+    if (fs.existsSync(file)) fs.chmodSync(file, 0o755);
+  }
+}
+
+function installOne(targetKey, options) {
+  const source = sourceDirFor(targetKey);
+  const dest = installDirFor(targetKey);
+  if (!fs.existsSync(path.join(source, 'SKILL.md'))) {
+    fail(`Missing skill source: ${source}`);
+  }
+  if (pathExists(dest)) {
+    if (!options.force) {
+      fail(`${targets[targetKey].label} skill already exists: ${dest}
+Use --force to replace it.`);
+    }
+    removeExisting(dest);
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (options.link) {
+    fs.symlinkSync(source, dest, 'dir');
+  } else {
+    copyRecursive(source, dest);
+  }
+  if (!options.link) chmodExecutables(targetKey);
+  console.log(`Installed ${targets[targetKey].label}: ${dest}${options.link ? ` -> ${source}` : ''}`);
+}
+
+function uninstallOne(targetKey) {
+  const dest = installDirFor(targetKey);
+  if (!pathExists(dest)) {
+    console.log(`${targets[targetKey].label} skill is not installed: ${dest}`);
+    return;
+  }
+  removeExisting(dest);
+  console.log(`Removed ${targets[targetKey].label}: ${dest}`);
+}
+
+function statInstall(targetKey) {
+  const target = targets[targetKey];
+  const source = sourceDirFor(targetKey);
+  const dest = installDirFor(targetKey);
+  const installed = pathExists(dest);
+  const linkTarget = installed && fs.lstatSync(dest).isSymbolicLink() ? fs.readlinkSync(dest) : null;
+  const executableStatus = target.executables.map(relative => {
+    const file = path.join(dest, relative);
+    if (!fs.existsSync(file)) return `${relative}: missing`;
+    const mode = fs.statSync(file).mode;
+    return `${relative}: ${(mode & 0o111) !== 0 ? 'executable' : 'not executable'}`;
+  });
+  return {
+    target,
+    source,
+    dest,
+    installed,
+    linkTarget,
+    executableStatus
+  };
+}
+
+function doctor() {
+  console.log(`Node: ${process.version}`);
+  for (const command of ['git', 'pnpm', 'corepack']) {
+    console.log(`${command}: ${commandExists(command) ? 'found' : 'missing'}`);
+  }
+  console.log(`package runner: ${commandExists('pnpm') ? 'pnpm' : commandExists('corepack') ? 'corepack pnpm' : 'missing'}`);
+  for (const key of Object.keys(targets)) {
+    const status = statInstall(key);
+    console.log(`\n${status.target.label}`);
+    console.log(`  source: ${status.source}`);
+    console.log(`  install: ${status.dest}`);
+    console.log(`  installed: ${status.installed ? 'yes' : 'no'}`);
+    if (status.linkTarget) console.log(`  link: ${status.linkTarget}`);
+    for (const line of status.executableStatus) console.log(`  ${line}`);
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  switch (args.command) {
+    case 'install':
+      for (const targetKey of expandTargets(args.target)) installOne(targetKey, args);
+      console.log('Restart Codex or CodeBuddy to pick up newly installed skills.');
+      break;
+    case 'uninstall':
+      for (const targetKey of expandTargets(args.target)) uninstallOne(targetKey);
+      break;
+    case 'doctor':
+      doctor();
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+      usage();
+      break;
+    default:
+      usage();
+      process.exitCode = 1;
+  }
+}
+
+main();