mirror of
https://github.com/JimLiu/baoyu-skills.git
synced 2026-07-12 22:09:48 +08:00
Compare commits
9 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Jim Liu 宝玉
|
ad1755fa23 | ||
|
Jim Liu 宝玉
|
3cc1225b18 | ||
|
Jim Liu 宝玉
|
460bd087c6 | ||
 千乘妍 (Xiaoyaner)
|
daf0fb7bec | ||
|
Jim Liu 宝玉
|
adbfa3036b | ||
|
Jim Liu 宝玉
|
6026b619f0 | ||
 Yelban
|
df16bd5d1a | ||
|
Yelban
|
9596d39e7b | ||
|
Yelban
|
e98fa33bc2 |
@@ -6,7 +6,7 @@
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Skills shared by Baoyu for improving daily work efficiency",
|
||||
"version": "1.117.5"
|
||||
"version": "1.119.0"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
@@ -22,6 +22,7 @@
|
||||
"./skills/baoyu-danger-gemini-web",
|
||||
"./skills/baoyu-danger-x-to-markdown",
|
||||
"./skills/baoyu-diagram",
|
||||
"./skills/baoyu-electron-extract",
|
||||
"./skills/baoyu-format-markdown",
|
||||
"./skills/baoyu-imagine",
|
||||
"./skills/baoyu-infographic",
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
name: codex-imagegen tests
|
||||
|
||||
on:
|
||||
push:
|
||||
paths:
|
||||
- 'scripts/codex-imagegen/**'
|
||||
- 'scripts/codex-imagegen.sh'
|
||||
- '.github/workflows/codex-imagegen-tests.yml'
|
||||
pull_request:
|
||||
paths:
|
||||
- 'scripts/codex-imagegen/**'
|
||||
- 'scripts/codex-imagegen.sh'
|
||||
- '.github/workflows/codex-imagegen-tests.yml'
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
unit-tests:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Bun
|
||||
uses: oven-sh/setup-bun@v2
|
||||
with:
|
||||
bun-version: latest
|
||||
|
||||
- name: Show Bun version
|
||||
run: bun --version
|
||||
|
||||
- name: Run unit tests
|
||||
working-directory: scripts/codex-imagegen
|
||||
run: bun test
|
||||
|
||||
- name: Bundle smoke test (catches import/syntax errors)
|
||||
run: bun build --target=node scripts/codex-imagegen/main.ts --outfile /tmp/main-build.js
|
||||
|
||||
- name: Help output smoke test
|
||||
run: bun scripts/codex-imagegen/main.ts --help
|
||||
@@ -2,6 +2,30 @@
|
||||
|
||||
English | [中文](./CHANGELOG.zh.md)
|
||||
|
||||
## 1.119.0 - 2026-05-24
|
||||
|
||||
### Features
|
||||
- `baoyu-electron-extract`: new skill that extracts resources and JavaScript from any installed Electron app's `app.asar`. Restores original sources from embedded `sourcesContent` in `.js.map` files when present (TypeScript/JSX included) or formats minified JS/CSS with Prettier in place when not. Source-map paths are resolved relative to each `.js.map` file first, so bundler-relative entries like `../../src/main.ts` restore to readable paths under `restored/` instead of hashed placeholders. Always skips `node_modules` and `webpack/runtime/*` entries. Auto-discovers apps on macOS (`/Applications`, `~/Applications`) and Windows (`%LOCALAPPDATA%\Programs`, `%PROGRAMFILES%`, `%PROGRAMFILES(X86)%`, `%APPDATA%`); other platforms can pass `--asar <path>` explicitly. Safety: refuses to write to `/`, the user home, or the current working directory, and refuses non-empty existing output dirs without `--force`
|
||||
|
||||
## 1.118.0 - 2026-05-21
|
||||
|
||||
### Features
|
||||
- `codex-imagegen`: new image-generation backend for non-Codex runtimes (e.g., Claude Code) — spawns `codex exec --json --sandbox danger-full-access` and delegates to Codex CLI's built-in `image_gen` tool, so no `OPENAI_API_KEY` is required. Ships with idempotency cache, file-lock concurrency control, JSONL event-stream parsing, PNG magic-byte validation, and exponential-backoff retries (by @yelban, #158)
|
||||
- `baoyu-cover-image`: wire `SKILL.md` to call the `codex-imagegen` wrapper when `preferred_image_backend: codex-imagegen` is set, with `--timeout` documented for slow networks
|
||||
|
||||
### Refactor
|
||||
- `codex-imagegen`: enforce `--prompt` / `--prompt-file` mutual exclusion in code (was docs-only)
|
||||
- `codex-imagegen`: replace `(opts as any).__promptFile` hack with a typed `promptFile` field on `CliOptions`
|
||||
- `codex-imagegen`: replace inline `cp|mv ... generated_images` regex with the shared `findCpToTarget` helper
|
||||
- `codex-imagegen`: propagate `attempts` on error responses (previously hardcoded to `0`)
|
||||
- `codex-imagegen`: drop dead `parseFinalJson()` + matching test (wrapper ignores agent-reported JSON in favor of disk verification)
|
||||
|
||||
### Security
|
||||
- `codex-imagegen`: reject `--image` / `--ref` paths containing shell metacharacters before interpolating them into the agent instruction sent to `codex exec --sandbox danger-full-access`
|
||||
|
||||
### Credits
|
||||
- `codex-imagegen` backend contributed by @yelban (#158)
|
||||
|
||||
## 1.117.5 - 2026-05-21
|
||||
|
||||
### Credits
|
||||
|
||||
@@ -2,6 +2,30 @@
|
||||
|
||||
[English](./CHANGELOG.md) | 中文
|
||||
|
||||
## 1.119.0 - 2026-05-24
|
||||
|
||||
### 新功能
|
||||
- `baoyu-electron-extract`：新增 skill，可从任意已安装的 Electron 应用的 `app.asar` 中提取资源和 JavaScript。`.js.map` 文件内嵌 `sourcesContent` 时还原原始源码（含 TypeScript/JSX），否则用 Prettier 原地美化压缩后的 JS/CSS。source-map 路径先相对各 `.js.map` 文件解析，因此 `../../src/main.ts` 这类打包器相对路径会还原为 `restored/` 下的可读路径，而不是哈希占位符。始终跳过 `node_modules` 和 `webpack/runtime/*` 条目。macOS 下自动从 `/Applications` 和 `~/Applications` 发现应用，Windows 下从 `%LOCALAPPDATA%\Programs`、`%PROGRAMFILES%`、`%PROGRAMFILES(X86)%`、`%APPDATA%` 发现；其他平台请用 `--asar <path>` 显式指定。安全：拒绝写入 `/`、用户主目录或当前工作目录，未加 `--force` 时拒绝写入非空的已有输出目录
|
||||
|
||||
## 1.118.0 - 2026-05-21
|
||||
|
||||
### 新功能
|
||||
- `codex-imagegen`：新增面向非 Codex 运行时（如 Claude Code）的图像生成后端 —— 通过 `codex exec --json --sandbox danger-full-access` 调用 Codex CLI 内置的 `image_gen` 工具，无需 `OPENAI_API_KEY`。内置幂等缓存、文件锁并发控制、JSONL 事件流解析、PNG 魔术字节校验和指数退避重试 (by @yelban, #158)
|
||||
- `baoyu-cover-image`：在 `SKILL.md` 中接入 `codex-imagegen` 包装脚本（当 `preferred_image_backend: codex-imagegen` 时生效），并补充慢网络下的 `--timeout` 参数说明
|
||||
|
||||
### 重构
|
||||
- `codex-imagegen`：在代码中强制校验 `--prompt` 与 `--prompt-file` 互斥（此前仅在文档说明）
|
||||
- `codex-imagegen`：将 `(opts as any).__promptFile` 这一 hack 改为 `CliOptions` 上类型化的 `promptFile` 字段
|
||||
- `codex-imagegen`：用复用的 `findCpToTarget` 辅助函数替换内联的 `cp|mv ... generated_images` 正则
|
||||
- `codex-imagegen`：错误返回时正确透传 `attempts`（此前硬编码为 `0`）
|
||||
- `codex-imagegen`：删除无用的 `parseFinalJson()` 函数及对应测试（包装脚本以磁盘校验为准，不再依赖 agent 自报 JSON）
|
||||
|
||||
### 安全
|
||||
- `codex-imagegen`：在拼入发往 `codex exec --sandbox danger-full-access` 的 agent 指令前，拒绝包含 shell 元字符的 `--image` / `--ref` 路径
|
||||
|
||||
### 致谢
|
||||
- `codex-imagegen` 后端由 @yelban 贡献 (#158)
|
||||
|
||||
## 1.117.5 - 2026-05-21
|
||||
|
||||
### 致谢
|
||||
|
||||
@@ -66,6 +66,22 @@ Skills that prompt users for choices MUST declare the tool-selection convention
|
||||
|
||||
Skills that render images MUST declare the backend-selection convention **inline** in exactly one place per `SKILL.md` — a `## Image Generation Tools` section near the top (after `## User Input Tools`). Do NOT link out to [docs/image-generation-tools.md](docs/image-generation-tools.md); that doc is the author-side canonical source — copy its body into each SKILL.md. Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) elsewhere in a skill are treated as examples — other runtimes substitute their local equivalent under the rule. The rule is stateless: use whatever backend is available; if multiple, ask the user once; if none, ask how to proceed. Every rendered image's full prompt must be written to a standalone `prompts/NN-*.md` file before any backend is invoked. Backend skills (`baoyu-imagine`, `baoyu-image-gen`, `baoyu-danger-gemini-web`) are exempt — they render directly rather than selecting a backend.
|
||||
|
||||
### `codex-imagegen` Backend
|
||||
|
||||
A backend for non-Codex runtimes (e.g., Claude Code) that generates images by spawning `codex exec --json --sandbox danger-full-access` and delegating to Codex CLI's built-in `image_gen` tool. Uses the user's Codex subscription — no `OPENAI_API_KEY` required.
|
||||
|
||||
Invoke via:
|
||||
|
||||
```bash
|
||||
./scripts/codex-imagegen.sh \
|
||||
--image <output.png> \
|
||||
--prompt-file prompts/01-cover.md \
|
||||
--aspect 16:9 \
|
||||
--cache-dir ~/.cache/baoyu-codex-imagegen
|
||||
```
|
||||
|
||||
Stdout emits a single JSON line: `{"status":"ok","path":...,"bytes":N,...}`. On failure, `{"status":"error","error_kind":...}`. Skills route here by setting `preferred_image_backend: codex-imagegen` in EXTEND.md. Full reference: [docs/codex-imagegen-backend.md](docs/codex-imagegen-backend.md).
|
||||
|
||||
## Deprecated Skills
|
||||
|
||||
| Skill | Note |
|
||||
|
||||
@@ -1154,6 +1154,43 @@ Summarize WeChat group chat highlights into a structured digest. Extracts topics
|
||||
- Normal and roast (毒舌) digest versions
|
||||
- Profile backfill from historical digests
|
||||
|
||||
#### baoyu-electron-extract
|
||||
|
||||
Extract resources and JavaScript from any installed Electron app's `app.asar`. When `.js.map` files embed `sourcesContent`, restores the original source tree (TypeScript/JSX included); otherwise formats the minified JS/CSS with Prettier in place. Always skips `node_modules`. Works on macOS and Windows; pass `--asar <path>` on other platforms.
|
||||
|
||||
```bash
|
||||
# Extract by app name (default output: ~/Downloads/Codex-electron-extract/)
|
||||
/baoyu-electron-extract Codex
|
||||
|
||||
# Extract by absolute path (.app bundle, install dir, or .asar file)
|
||||
/baoyu-electron-extract "/Applications/Visual Studio Code.app"
|
||||
/baoyu-electron-extract --asar /Applications/Codex.app/Contents/Resources/app.asar Codex
|
||||
|
||||
# Custom output directory
|
||||
/baoyu-electron-extract Codex --output ~/work/codex-source
|
||||
|
||||
# Preview discovery without writing anything
|
||||
/baoyu-electron-extract Codex --dry-run
|
||||
|
||||
# Overwrite an existing output directory
|
||||
/baoyu-electron-extract Codex --force
|
||||
```
|
||||
|
||||
**Options**:
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `<app>` | App name or absolute path (required unless `--asar`) | — |
|
||||
| `--output`, `-o` | Output directory | `~/Downloads/<AppName>-electron-extract` |
|
||||
| `--asar` | Override the resolved `.asar` path | auto-discovered |
|
||||
| `--force`, `-f` | Allow writing into a non-empty existing output dir | false |
|
||||
| `--skip-format` | Skip Prettier formatting | false |
|
||||
| `--skip-restore` | Skip source-map restoration | false |
|
||||
| `--no-unpacked` | Don't copy `app.asar.unpacked/` alongside | false |
|
||||
| `--dry-run` | Print resolved paths and exit without writing | false |
|
||||
| `--json` | Emit one JSON-line summary on stdout | false |
|
||||
|
||||
**Output layout**: `extract-report.json` (counts, warnings, paths), `extracted/` (raw asar, formatted in place when no map), `extracted.unpacked/` (native modules if present), and `restored/` (rebuilt source tree from `.js.map` files).
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
Some skills require API keys or custom configuration. Environment variables can be set in `.env` files:
|
||||
|
||||
@@ -1145,6 +1145,43 @@ AI 驱动的生成后端。
|
||||
- 正常版和毒舌版两种风格
|
||||
- 支持从历史摘要回溯初始化画像
|
||||
|
||||
#### baoyu-electron-extract
|
||||
|
||||
从任意已安装的 Electron 应用的 `app.asar` 中提取资源和 JavaScript。当 `.js.map` 内嵌 `sourcesContent` 时，还原原始源码树（含 TypeScript/JSX）；否则用 Prettier 原地美化压缩后的 JS/CSS。始终跳过 `node_modules`。支持 macOS 和 Windows，其他平台请用 `--asar <path>` 指定 asar 文件。
|
||||
|
||||
```bash
|
||||
# 按应用名提取（默认输出：~/Downloads/<AppName>-electron-extract/）
|
||||
/baoyu-electron-extract Codex
|
||||
|
||||
# 按绝对路径提取（.app 包、安装目录或 .asar 文件均可）
|
||||
/baoyu-electron-extract "/Applications/Visual Studio Code.app"
|
||||
/baoyu-electron-extract --asar /Applications/Codex.app/Contents/Resources/app.asar Codex
|
||||
|
||||
# 自定义输出目录
|
||||
/baoyu-electron-extract Codex --output ~/work/codex-source
|
||||
|
||||
# 仅预览发现的路径，不写入任何文件
|
||||
/baoyu-electron-extract Codex --dry-run
|
||||
|
||||
# 覆盖已存在的输出目录
|
||||
/baoyu-electron-extract Codex --force
|
||||
```
|
||||
|
||||
**选项**：
|
||||
| 选项 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `<app>` | 应用名或绝对路径（未给 `--asar` 时必填） | — |
|
||||
| `--output`, `-o` | 输出目录 | `~/Downloads/<AppName>-electron-extract` |
|
||||
| `--asar` | 覆盖解析得到的 `.asar` 路径 | 自动发现 |
|
||||
| `--force`, `-f` | 允许写入非空的已有输出目录 | false |
|
||||
| `--skip-format` | 跳过 Prettier 格式化 | false |
|
||||
| `--skip-restore` | 跳过 source-map 还原 | false |
|
||||
| `--no-unpacked` | 不复制同级的 `app.asar.unpacked/` | false |
|
||||
| `--dry-run` | 打印解析路径后退出，不写文件 | false |
|
||||
| `--json` | 在 stdout 输出一行 JSON 概要 | false |
|
||||
|
||||
**输出结构**：`extract-report.json`（计数、警告、路径），`extracted/`（asar 原始内容，无 map 时原地美化），`extracted.unpacked/`（存在时复制的原生模块），以及 `restored/`（基于 `.js.map` 重建的源码树）。
|
||||
|
||||
## 环境配置
|
||||
|
||||
部分技能需要 API 密钥或自定义配置。环境变量可以在 `.env` 文件中设置：
|
||||
|
||||
@@ -0,0 +1,256 @@
|
||||
# `codex-imagegen` Backend
|
||||
|
||||
Generate images via Codex CLI's built-in `image_gen` tool from non-Codex runtimes (e.g., Claude Code). The wrapper spawns `codex exec --json` and lets the user's existing Codex subscription drive image generation — **no `OPENAI_API_KEY` required**.
|
||||
|
||||
This backend implements the `preferred_image_backend: codex-imagegen` config key already referenced in several `SKILL.md` files across this repo.
|
||||
|
||||
## Features
|
||||
|
||||
| Feature | Status |
|
||||
|---------|--------|
|
||||
| **Reliability**: retry + exponential backoff | Default 2 retries |
|
||||
| **Verification**: confirms `image_gen` was actually invoked (not bypassed) | Checks `$CODEX_HOME/generated_images/{thread_id}/` |
|
||||
| **Verification**: PNG magic-byte sanity check | ✓ |
|
||||
| **Idempotency cache**: reuses output for same prompt+aspect+refs | `--cache-dir` |
|
||||
| **Concurrency control**: file lock prevents parallel `codex exec` collisions | Built-in |
|
||||
| **Structured logging**: JSONL log file | `--log-file` |
|
||||
| **Token usage returned** | Embedded in result JSON |
|
||||
| **`--ref` reference images** | Repeatable |
|
||||
| **Unit tests** | 16 tests (parser / cache / validator) |
|
||||
| **Error classification**: retryable vs non-retryable | 9 `error_kind` values |
|
||||
|
||||
## Why this backend
|
||||
|
||||
| Scenario | Conventional backend | This backend |
|
||||
|----------|---------------------|--------------|
|
||||
| You have a Codex subscription | OpenAI Images API costs add up per image | Subscription already covers it — zero marginal API cost |
|
||||
| No `OPENAI_API_KEY` available | `baoyu-imagine` needs an API key | `codex login` is enough |
|
||||
| Want to use GPT Image 2 | Only via OpenAI API | Codex's `image_gen` *is* GPT Image 2 |
|
||||
|
||||
## Prerequisites
|
||||
|
||||
```bash
|
||||
npm install -g @openai/codex
|
||||
codex login # signs in with your OpenAI account (subscription)
|
||||
codex --version # confirm >= 0.130
|
||||
```
|
||||
|
||||
`bun` is preferred for running the wrapper. On macOS:
|
||||
|
||||
```bash
|
||||
brew install oven-sh/bun/bun
|
||||
```
|
||||
|
||||
If `bun` is missing, the shell entrypoint falls back to `npx -y bun`.
|
||||
|
||||
## Usage
|
||||
|
||||
### Direct CLI
|
||||
|
||||
```bash
|
||||
# Inline prompt
|
||||
./scripts/codex-imagegen.sh \
|
||||
--image /tmp/cat.png \
|
||||
--prompt "A friendly orange cat, watercolor"
|
||||
|
||||
# Prompt from file
|
||||
./scripts/codex-imagegen.sh \
|
||||
--image cover.png \
|
||||
--prompt-file prompts/01-cover.md \
|
||||
--aspect 16:9
|
||||
|
||||
# Verbose mode for debugging
|
||||
./scripts/codex-imagegen.sh -v --image dog.png --prompt "A corgi" --aspect 1:1
|
||||
```
|
||||
|
||||
On success, stdout emits a single JSON line:
|
||||
|
||||
```json
|
||||
{"status":"ok","path":"/tmp/cat.png","bytes":2567101,"elapsed_seconds":53}
|
||||
```
|
||||
|
||||
On failure, exit code is non-zero and stderr contains the error message.
|
||||
|
||||
### Enabling within image skills
|
||||
|
||||
Image-generating skills (e.g., `baoyu-cover-image`, `baoyu-article-illustrator`) already support a `preferred_image_backend` preference. To route them through this backend, set the following in the corresponding `EXTEND.md`:
|
||||
|
||||
```yaml
|
||||
# ~/.baoyu-skills/baoyu-cover-image/EXTEND.md
|
||||
preferred_image_backend: codex-imagegen
|
||||
```
|
||||
|
||||
When the LLM runs the skill, it reads the preference and — guided by the `### codex-imagegen Backend` section in `CLAUDE.md` — invokes `scripts/codex-imagegen.sh`.
|
||||
|
||||
> **Note**: The integration is mediated by the LLM reading `CLAUDE.md`. It is not a hard binding. If a skill does not route to the backend automatically, mentioning it explicitly in the prompt works.
|
||||
|
||||
## Parameters
|
||||
|
||||
| Flag | Required | Description |
|
||||
|------|----------|-------------|
|
||||
| `--image <path>` | ✓ | Output PNG path (absolute recommended; relative paths are resolved against cwd) |
|
||||
| `--prompt <text>` | one of | Prompt string (mutually exclusive with `--prompt-file`) |
|
||||
| `--prompt-file <path>` | one of | Read prompt from file (mutually exclusive with `--prompt`) |
|
||||
| `--aspect <ratio>` | | Aspect ratio. Default `1:1`. Common: `16:9`, `9:16`, `4:3`, `2.35:1` |
|
||||
| `--ref <file>` | | Reference image path (repeatable) |
|
||||
| `--timeout <ms>` | | `codex exec` timeout in ms. Default `300000` |
|
||||
| `--retries <n>` | | Retry count on retryable errors. Default `2` (total attempts = retries + 1) |
|
||||
| `--retry-delay <ms>` | | Base delay between retries (exponential backoff). Default `1500` |
|
||||
| `--cache-dir <path>` | | Enable idempotency cache (reuses output for same prompt+aspect+refs) |
|
||||
| `--log-file <path>` | | Structured JSONL log path (appended) |
|
||||
| `-v` / `--verbose` | | Mirror log entries to stderr |
|
||||
| `-h` / `--help` | | Show usage |
|
||||
|
||||
## Structured Output
|
||||
|
||||
On success, stdout contains a single JSON line:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"path": "/tmp/owl.png",
|
||||
"bytes": 1693831,
|
||||
"elapsed_seconds": 87,
|
||||
"thread_id": "019e40e8-daef-7c60-943d-5e7bb3f6cb3d",
|
||||
"attempts": 1,
|
||||
"cached": false,
|
||||
"usage": {
|
||||
"input": 110899,
|
||||
"cached_input": 83456,
|
||||
"output": 457,
|
||||
"reasoning": 47
|
||||
},
|
||||
"tool_calls": [
|
||||
{"tool": "shell", "status": "completed"},
|
||||
{"tool": "agent_message", "status": "completed"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Cache hits return with `elapsed_seconds: 0`, `cached: true`, `attempts: 0`.
|
||||
|
||||
On failure, exit code is `1` and the JSON contains `error` and `error_kind`:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"error": "image_gen was not invoked: no PNG in ...",
|
||||
"error_kind": "no_image_gen_tool_use"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Kinds
|
||||
|
||||
| `error_kind` | Retryable | Meaning |
|
||||
|--------------|-----------|---------|
|
||||
| `codex_not_installed` | ✗ | `codex` CLI not found |
|
||||
| `invalid_args` | ✗ | Argument parsing error |
|
||||
| `prompt_file_missing` | ✗ | `--prompt-file` path does not exist |
|
||||
| `spawn_failed` | ✓ | `codex exec` exited non-zero |
|
||||
| `timeout` | ✓ | Exceeded `--timeout` |
|
||||
| `no_image_gen_tool_use` | ✓ | Agent did not invoke `image_gen` (it took another path) |
|
||||
| `output_missing` | ✓ | Output file not created |
|
||||
| `invalid_png` | ✓ | Output is not a valid PNG |
|
||||
| `agent_refused` | ✓ | No `thread_id` in event stream (Codex refused to respond) |
|
||||
| `lock_busy` | ✗ | Concurrency lock acquisition timed out |
|
||||
|
||||
## Measured Performance
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| First-run latency | 50–90 s |
|
||||
| Cache-hit latency | < 0.3 s |
|
||||
| Output dimensions | 1024×1024, 1672×941 (16:9), etc. — chosen by `image_gen` |
|
||||
| Output format | PNG (RGB, 8-bit) |
|
||||
| Token usage per call | ~110k input (~80k cached) + ~500 output |
|
||||
| Quota source | Codex subscription (does not consume OpenAI API quota) |
|
||||
| Default timeout | 300 s (5 min) |
|
||||
|
||||
## Limitations & Risks
|
||||
|
||||
1. **5–10× slower than direct API**. `codex exec` cold-starts the agent, loads the built-in `image_gen` SKILL.md, and runs reasoning before invoking the tool. Cache hits avoid this for repeated prompts.
|
||||
2. **ToS gray area**. Codex's `image_gen` tool is designed for interactive use. Invoking it programmatically via `codex exec` from an external agent is not explicitly addressed by current OpenAI policies. Suggested guardrails:
|
||||
- Personal, low-volume use is reasonable.
|
||||
- Not recommended for production automation or high-volume batch jobs.
|
||||
- Users are responsible for ensuring their usage complies with applicable terms of service.
|
||||
3. **Sandbox permissions**. The wrapper passes `--sandbox danger-full-access` so the spawned agent can move the rendered PNG out of `$CODEX_HOME/generated_images/`. This is necessary because the agent must `cp`/`mv` the file to the user-specified output path.
|
||||
4. **Concurrency = 1**. The file lock serializes concurrent invocations to avoid `codex exec` collisions. Parallel calls queue.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | `error_kind` | Resolution |
|
||||
|---------|--------------|------------|
|
||||
| `command not found: codex` | `codex_not_installed` | `npm install -g @openai/codex` |
|
||||
| `codex exec` fails | `spawn_failed` | Check `codex login` status; inspect `raw_log` path |
|
||||
| Timeout | `timeout` | Pass `--timeout 600000` (10 min) for slow networks |
|
||||
| Agent skipped `image_gen` | `no_image_gen_tool_use` | Auto-retries; consider sharpening the prompt — abstract prompts let the agent wander |
|
||||
| Output missing | `output_missing` | Agent did not `cp` to the target path; check `raw_log` for the actual save location under `generated_images/` |
|
||||
| Lock held | `lock_busy` | Wait for the in-flight request to finish; or `rm ~/.cache/baoyu-codex-imagegen/codex-exec.lock` |
|
||||
| Low image quality | — | Sharpen the prompt, try a different aspect, or supply `--ref` |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
scripts/codex-imagegen.sh # thin bash entrypoint
|
||||
scripts/codex-imagegen/
|
||||
├── main.ts # parseArgs → cache → lock → retry loop → emit JSON
|
||||
├── types.ts # CliOptions, GenerateResult, GenError, ErrorKind
|
||||
├── spawn.ts # spawn codex exec --json --sandbox danger-full-access
|
||||
├── parser.ts # parse JSONL event stream → toolCalls, usage, thread_id
|
||||
├── validator.ts # verify image_gen invocation + PNG magic + file size
|
||||
├── cache.ts # cacheKey(sha256), FileLock, lookup/store
|
||||
├── logger.ts # JsonLogger (verbose stderr + JSONL file)
|
||||
├── parser.test.ts
|
||||
├── cache.test.ts
|
||||
└── validator.test.ts
|
||||
```
|
||||
|
||||
Run tests:
|
||||
|
||||
```bash
|
||||
cd scripts/codex-imagegen && bun test
|
||||
```
|
||||
|
||||
## Internal Flow
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
CC[Claude Code / any caller]
|
||||
WRAPPER[scripts/codex-imagegen.sh]
|
||||
CODEX["codex exec --json<br/>--sandbox danger-full-access"]
|
||||
AGENT[Codex agent]
|
||||
TOOL[image_gen built-in tool]
|
||||
DEFAULT["$CODEX_HOME/<br/>generated_images/{thread_id}/"]
|
||||
OUT[/specified OUTPUT path/]
|
||||
|
||||
CC -->|exec wrapper| WRAPPER
|
||||
WRAPPER -->|stdin: instruction| CODEX
|
||||
CODEX --> AGENT
|
||||
AGENT -->|tool call| TOOL
|
||||
TOOL -->|writes file| DEFAULT
|
||||
AGENT -->|agent cp/mv| OUT
|
||||
WRAPPER -->|verify + parse| CC
|
||||
|
||||
classDef cc fill:#1e40af,color:#fff,stroke:#93c5fd
|
||||
classDef cdx fill:#7c2d12,color:#fff,stroke:#fdba74
|
||||
class CC,WRAPPER cc
|
||||
class CODEX,AGENT,TOOL cdx
|
||||
```
|
||||
|
||||
## Design Decisions
|
||||
|
||||
1. **Bash entrypoint + TypeScript implementation** — the shell wrapper picks the runtime (`bun` preferred, falling back to `npx -y bun`); TypeScript handles the orchestration, parsing, retry, cache, and logging. This mirrors the project's existing `scripts/*.mjs` and `skills/<skill>/scripts/main.ts` pattern.
|
||||
2. **`--sandbox danger-full-access`** — necessary so the spawned agent can `cp`/`mv` the rendered PNG out of `$CODEX_HOME/generated_images/` to the user-specified path. Standard sandboxes block this.
|
||||
3. **Parse the JSONL event stream** — the final `agent_message` and intermediate `command_execution` events let the wrapper verify what actually happened (was `image_gen` called? did `cp` reach the right destination?), which is far more reliable than scraping freeform stdout.
|
||||
4. **Infrastructure, not a skill** — this backend is a CLI utility that skills route to via `preferred_image_backend`. It belongs in `scripts/`, not `skills/`, because it has no `SKILL.md` and is never loaded directly by an agent.
|
||||
5. **File lock instead of internal queue** — keeps the implementation small and works across multiple shell sessions or processes invoking the same wrapper concurrently.
|
||||
|
||||
## Related Files
|
||||
|
||||
| File | Role |
|
||||
|------|------|
|
||||
| `scripts/codex-imagegen.sh` | CLI entrypoint |
|
||||
| `scripts/codex-imagegen/` | TypeScript implementation |
|
||||
| `docs/codex-imagegen-backend.md` | This document |
|
||||
| `CLAUDE.md` | Tells LLMs how to invoke this backend |
|
||||
| `.github/workflows/codex-imagegen-tests.yml` | CI unit tests |
|
||||
Executable
+19
@@ -0,0 +1,19 @@
|
||||
#!/bin/bash
|
||||
# codex-imagegen: generate images via Codex CLI's built-in image_gen tool
|
||||
# Thin shell wrapper — implementation in codex-imagegen/main.ts (Bun TypeScript)
|
||||
#
|
||||
# Usage: ./codex-imagegen.sh --help
|
||||
|
||||
set -euo pipefail
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
if command -v bun &>/dev/null; then
|
||||
BUN_X="bun"
|
||||
elif command -v npx &>/dev/null; then
|
||||
BUN_X="npx -y bun"
|
||||
else
|
||||
echo "Error: bun or npx required. Install: brew install oven-sh/bun/bun" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
exec $BUN_X "$SCRIPT_DIR/codex-imagegen/main.ts" "$@"
|
||||
@@ -0,0 +1,63 @@
|
||||
import { test, expect } from "bun:test";
|
||||
import { mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
import { cacheKey, lookupCache, storeCache, FileLock } from "./cache.ts";
|
||||
|
||||
test("cacheKey is deterministic and order-independent for refs", () => {
|
||||
const k1 = cacheKey("hello", "16:9", ["a.png", "b.png"]);
|
||||
const k2 = cacheKey("hello", "16:9", ["b.png", "a.png"]);
|
||||
expect(k1).toBe(k2);
|
||||
const k3 = cacheKey("hello", "16:9", []);
|
||||
expect(k3).not.toBe(k1);
|
||||
const k4 = cacheKey("hello", "1:1", []);
|
||||
expect(k4).not.toBe(k3);
|
||||
});
|
||||
|
||||
test("lookupCache returns null on miss, path on hit", async () => {
|
||||
const dir = await mkdtemp(path.join(tmpdir(), "cig-test-"));
|
||||
try {
|
||||
expect(await lookupCache(dir, "abc")).toBeNull();
|
||||
const fake = path.join(dir, "abc.png");
|
||||
await writeFile(fake, Buffer.alloc(2000));
|
||||
expect(await lookupCache(dir, "abc")).toBe(fake);
|
||||
} finally {
|
||||
await rm(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("storeCache copies source into cache", async () => {
|
||||
const dir = await mkdtemp(path.join(tmpdir(), "cig-test-"));
|
||||
const src = path.join(dir, "src.png");
|
||||
try {
|
||||
await writeFile(src, Buffer.from("xxxx".repeat(1000)));
|
||||
await storeCache(dir, "key1", src);
|
||||
const cached = await lookupCache(dir, "key1");
|
||||
expect(cached).not.toBeNull();
|
||||
const a = await readFile(src);
|
||||
const b = await readFile(cached!);
|
||||
expect(a.equals(b)).toBe(true);
|
||||
} finally {
|
||||
await rm(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("FileLock prevents concurrent acquisition", async () => {
|
||||
const dir = await mkdtemp(path.join(tmpdir(), "cig-lock-"));
|
||||
try {
|
||||
const lockPath = path.join(dir, "x.lock");
|
||||
const lock1 = new FileLock(lockPath);
|
||||
const lock2 = new FileLock(lockPath);
|
||||
await lock1.acquire(1000);
|
||||
let lock2Acquired = false;
|
||||
const p = lock2.acquire(500).then(() => (lock2Acquired = true)).catch(() => {});
|
||||
await new Promise((r) => setTimeout(r, 300));
|
||||
expect(lock2Acquired).toBe(false);
|
||||
await lock1.release();
|
||||
await p;
|
||||
expect(lock2Acquired).toBe(true);
|
||||
await lock2.release();
|
||||
} finally {
|
||||
await rm(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,80 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, readFile, writeFile, copyFile, stat } from "node:fs/promises";
|
||||
import { existsSync, openSync, closeSync } from "node:fs";
|
||||
import path from "node:path";
|
||||
import { setTimeout as delay } from "node:timers/promises";
|
||||
|
||||
export function cacheKey(prompt: string, aspect: string, refs: string[]): string {
|
||||
const h = createHash("sha256");
|
||||
h.update(prompt);
|
||||
h.update("|");
|
||||
h.update(aspect);
|
||||
h.update("|");
|
||||
for (const r of [...refs].sort()) h.update(r);
|
||||
return h.digest("hex").slice(0, 16);
|
||||
}
|
||||
|
||||
export async function lookupCache(cacheDir: string, key: string): Promise<string | null> {
|
||||
const entry = path.join(cacheDir, `${key}.png`);
|
||||
try {
|
||||
const s = await stat(entry);
|
||||
if (s.size > 1000) return entry;
|
||||
} catch {}
|
||||
return null;
|
||||
}
|
||||
|
||||
export async function storeCache(cacheDir: string, key: string, sourcePath: string): Promise<void> {
|
||||
await mkdir(cacheDir, { recursive: true });
|
||||
const entry = path.join(cacheDir, `${key}.png`);
|
||||
await copyFile(sourcePath, entry);
|
||||
}
|
||||
|
||||
export class FileLock {
|
||||
private fd: number | null = null;
|
||||
constructor(private lockPath: string) {}
|
||||
|
||||
async acquire(timeoutMs = 30_000): Promise<void> {
|
||||
const start = Date.now();
|
||||
await mkdir(path.dirname(this.lockPath), { recursive: true });
|
||||
while (Date.now() - start < timeoutMs) {
|
||||
try {
|
||||
this.fd = openSync(this.lockPath, "wx");
|
||||
return;
|
||||
} catch (e: any) {
|
||||
if (e.code !== "EEXIST") throw e;
|
||||
if (await this.isStale()) {
|
||||
try {
|
||||
await this.release(true);
|
||||
} catch {}
|
||||
continue;
|
||||
}
|
||||
await delay(200);
|
||||
}
|
||||
}
|
||||
throw new Error(`Failed to acquire lock at ${this.lockPath} within ${timeoutMs}ms`);
|
||||
}
|
||||
|
||||
private async isStale(): Promise<boolean> {
|
||||
try {
|
||||
const s = await stat(this.lockPath);
|
||||
return Date.now() - s.mtimeMs > 10 * 60 * 1000;
|
||||
} catch {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
async release(force = false): Promise<void> {
|
||||
if (this.fd != null) {
|
||||
try {
|
||||
closeSync(this.fd);
|
||||
} catch {}
|
||||
this.fd = null;
|
||||
}
|
||||
if (existsSync(this.lockPath) || force) {
|
||||
const { unlink } = await import("node:fs/promises");
|
||||
try {
|
||||
await unlink(this.lockPath);
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
import { appendFile, mkdir } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
export interface LogEntry {
|
||||
ts: string;
|
||||
level: "info" | "warn" | "error";
|
||||
event: string;
|
||||
[k: string]: unknown;
|
||||
}
|
||||
|
||||
export class JsonLogger {
|
||||
constructor(private logFile: string | null, public verbose: boolean) {}
|
||||
|
||||
async log(level: LogEntry["level"], event: string, extra: Record<string, unknown> = {}): Promise<void> {
|
||||
const entry: LogEntry = { ts: new Date().toISOString(), level, event, ...extra };
|
||||
const line = JSON.stringify(entry);
|
||||
if (this.verbose) process.stderr.write(`[${level}] ${event} ${jsonExtras(extra)}\n`);
|
||||
if (this.logFile) {
|
||||
await mkdir(path.dirname(this.logFile), { recursive: true });
|
||||
await appendFile(this.logFile, line + "\n", "utf-8");
|
||||
}
|
||||
}
|
||||
|
||||
info(event: string, extra?: Record<string, unknown>) {
|
||||
return this.log("info", event, extra);
|
||||
}
|
||||
warn(event: string, extra?: Record<string, unknown>) {
|
||||
return this.log("warn", event, extra);
|
||||
}
|
||||
error(event: string, extra?: Record<string, unknown>) {
|
||||
return this.log("error", event, extra);
|
||||
}
|
||||
}
|
||||
|
||||
function jsonExtras(extra: Record<string, unknown>): string {
|
||||
const entries = Object.entries(extra);
|
||||
if (entries.length === 0) return "";
|
||||
return entries.map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`).join(" ");
|
||||
}
|
||||
@@ -0,0 +1,325 @@
|
||||
import { readFile, mkdir, copyFile, stat } from "node:fs/promises";
|
||||
import { homedir } from "node:os";
|
||||
import path from "node:path";
|
||||
import process from "node:process";
|
||||
import { setTimeout as delay } from "node:timers/promises";
|
||||
import { GenError, type CliOptions, type GenerateResult } from "./types.ts";
|
||||
import { runCodexExec } from "./spawn.ts";
|
||||
import { findCpToTarget, verifyImageGenWasInvoked, verifyOutput } from "./validator.ts";
|
||||
import { cacheKey, lookupCache, storeCache, FileLock } from "./cache.ts";
|
||||
import { JsonLogger } from "./logger.ts";
|
||||
|
||||
const HELP = `codex-imagegen — generate images via Codex CLI's image_gen tool
|
||||
|
||||
Usage:
|
||||
codex-imagegen --image <output.png> [--prompt <text> | --prompt-file <path>] [options]
|
||||
|
||||
Required:
|
||||
--image <path> Output PNG path
|
||||
--prompt <text> Prompt text (or use --prompt-file)
|
||||
--prompt-file <path> Read prompt from file
|
||||
|
||||
Options:
|
||||
--aspect <ratio> Aspect ratio (1:1, 16:9, 9:16, 4:3, 2.35:1). Default: 1:1
|
||||
--ref <file> Reference image (repeatable)
|
||||
--timeout <ms> Codex exec timeout in ms. Default: 300000
|
||||
--retries <n> Retry attempts on retryable errors. Default: 2
|
||||
--retry-delay <ms> Base retry delay (exponential). Default: 1500
|
||||
--cache-dir <path> Enable idempotency cache. Disabled by default.
|
||||
--log-file <path> Append JSONL log
|
||||
-v, --verbose Verbose stderr logging
|
||||
-h, --help Show this help
|
||||
|
||||
Stdout: single JSON line on success or failure.
|
||||
`;
|
||||
|
||||
const SHELL_METACHAR = /[;|&`$<>\n\r()'"]/;
|
||||
|
||||
function assertSafePath(label: string, value: string): void {
|
||||
if (SHELL_METACHAR.test(value)) {
|
||||
throw new GenError(
|
||||
"invalid_args",
|
||||
`${label} contains shell metacharacters and would be unsafe to interpolate into the codex instruction: ${value}`,
|
||||
false,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
function parseArgs(argv: string[]): CliOptions {
|
||||
const opts: CliOptions = {
|
||||
prompt: "",
|
||||
promptFile: null,
|
||||
outputPath: "",
|
||||
aspect: "1:1",
|
||||
refImages: [],
|
||||
timeoutMs: 300_000,
|
||||
retries: 2,
|
||||
retryDelayMs: 1500,
|
||||
cacheDir: null,
|
||||
logFile: null,
|
||||
verbose: false,
|
||||
};
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const a = argv[i];
|
||||
const next = () => argv[++i];
|
||||
switch (a) {
|
||||
case "--prompt": opts.prompt = next(); break;
|
||||
case "--prompt-file": opts.promptFile = next(); break;
|
||||
case "--image": opts.outputPath = next(); break;
|
||||
case "--aspect": opts.aspect = next(); break;
|
||||
case "--ref": opts.refImages.push(next()); break;
|
||||
case "--timeout": opts.timeoutMs = Number(next()); break;
|
||||
case "--retries": opts.retries = Number(next()); break;
|
||||
case "--retry-delay": opts.retryDelayMs = Number(next()); break;
|
||||
case "--cache-dir": opts.cacheDir = next(); break;
|
||||
case "--log-file": opts.logFile = next(); break;
|
||||
case "-v":
|
||||
case "--verbose": opts.verbose = true; break;
|
||||
case "-h":
|
||||
case "--help": process.stdout.write(HELP); process.exit(0);
|
||||
default: throw new GenError("invalid_args", `Unknown argument: ${a}`, false);
|
||||
}
|
||||
}
|
||||
if (!opts.outputPath) throw new GenError("invalid_args", "--image is required", false);
|
||||
if (opts.prompt && opts.promptFile) {
|
||||
throw new GenError("invalid_args", "--prompt and --prompt-file are mutually exclusive", false);
|
||||
}
|
||||
if (!opts.prompt && !opts.promptFile) {
|
||||
throw new GenError("invalid_args", "--prompt or --prompt-file required", false);
|
||||
}
|
||||
|
||||
// Resolve every filesystem path to absolute up front, so behavior is
|
||||
// independent of the caller's cwd. This matters when the wrapper is
|
||||
// invoked from a skill running in an arbitrary working directory.
|
||||
const cwd = process.cwd();
|
||||
const toAbs = (p: string) => (path.isAbsolute(p) ? p : path.resolve(cwd, p));
|
||||
|
||||
opts.outputPath = toAbs(opts.outputPath);
|
||||
if (opts.promptFile) opts.promptFile = toAbs(opts.promptFile);
|
||||
opts.refImages = opts.refImages.map(toAbs);
|
||||
if (opts.cacheDir) opts.cacheDir = toAbs(opts.cacheDir);
|
||||
if (opts.logFile) opts.logFile = toAbs(opts.logFile);
|
||||
|
||||
// The output and ref paths are interpolated raw into the agent instruction
|
||||
// sent to `codex exec --sandbox danger-full-access`. A path containing shell
|
||||
// metacharacters could be misread by the agent's shell when it cp's the
|
||||
// result into place. Reject upfront rather than trusting the agent to quote.
|
||||
assertSafePath("--image path", opts.outputPath);
|
||||
for (const ref of opts.refImages) assertSafePath("--ref path", ref);
|
||||
|
||||
return opts;
|
||||
}
|
||||
|
||||
async function loadPrompt(opts: CliOptions): Promise<string> {
|
||||
if (opts.prompt) return opts.prompt;
|
||||
const file = opts.promptFile!;
|
||||
try {
|
||||
return await readFile(file, "utf-8");
|
||||
} catch {
|
||||
throw new GenError("prompt_file_missing", `Prompt file not found: ${file}`, false);
|
||||
}
|
||||
}
|
||||
|
||||
function buildInstruction(prompt: string, opts: CliOptions): string {
|
||||
const refHint = opts.refImages.length > 0
|
||||
? `\nREFERENCE IMAGES (attached above): ${opts.refImages.length} image(s) provided for style/composition guidance.\n`
|
||||
: "";
|
||||
return `You have an internal tool called image_gen for image generation. Use it.
|
||||
|
||||
TASK: Generate an image with the spec below, then save to disk.
|
||||
|
||||
PROMPT:
|
||||
${prompt}
|
||||
|
||||
ASPECT RATIO: ${opts.aspect}
|
||||
OUTPUT PATH: ${opts.outputPath}
|
||||
${refHint}
|
||||
STEPS:
|
||||
1. Call image_gen with the prompt and aspect ratio above${opts.refImages.length > 0 ? " (using the attached reference images for guidance)" : ""}.
|
||||
2. Move or copy the resulting image from Codex default location ($CODEX_HOME/generated_images/...) to: ${opts.outputPath}
|
||||
3. Verify with: ls -la ${opts.outputPath}
|
||||
4. Reply with ONLY this JSON line (no markdown fences, no other text):
|
||||
{"status":"ok","path":"${opts.outputPath}","bytes":<file_size_in_bytes>}
|
||||
|
||||
HARD CONSTRAINTS:
|
||||
- Do NOT use curl, wget, Python, or any external API.
|
||||
- Do NOT use bash to fabricate an image; only image_gen produces real pixels.
|
||||
- Use ONLY the image_gen internal tool.`;
|
||||
}
|
||||
|
||||
async function attemptGenerate(
|
||||
opts: CliOptions,
|
||||
instruction: string,
|
||||
attempt: number,
|
||||
log: JsonLogger,
|
||||
): Promise<{ bytes: number; threadId: string | null; usage: any; toolCalls: any[] }> {
|
||||
await log.info("attempt.start", { attempt, output: opts.outputPath, aspect: opts.aspect });
|
||||
|
||||
const run = await runCodexExec({
|
||||
instruction,
|
||||
timeoutMs: opts.timeoutMs,
|
||||
refImages: opts.refImages,
|
||||
});
|
||||
|
||||
await log.info("codex.completed", {
|
||||
duration_ms: run.durationMs,
|
||||
thread_id: run.threadId,
|
||||
tool_calls: run.toolCalls.length,
|
||||
usage: run.usage,
|
||||
raw_log: run.rawLogPath,
|
||||
});
|
||||
|
||||
// verify: thread id must be present
|
||||
if (!run.threadId) {
|
||||
throw new GenError("agent_refused", "No thread id in event stream");
|
||||
}
|
||||
|
||||
// verify: image_gen was actually invoked (check $CODEX_HOME/generated_images/{threadId}/)
|
||||
const ver = await verifyImageGenWasInvoked(run.threadId);
|
||||
if (!ver.ok) {
|
||||
// secondary verify: did tool_calls include cp/mv from generated_images to our target
|
||||
if (!findCpToTarget(run.toolCalls, opts.outputPath)) {
|
||||
throw new GenError("no_image_gen_tool_use", `image_gen was not invoked: ${ver.reason}`);
|
||||
}
|
||||
}
|
||||
|
||||
// verify output
|
||||
const { bytes } = await verifyOutput(opts.outputPath);
|
||||
|
||||
return {
|
||||
bytes,
|
||||
threadId: run.threadId,
|
||||
usage: run.usage,
|
||||
toolCalls: run.toolCalls.map((tc) => ({ tool: tc.tool, status: tc.status })),
|
||||
};
|
||||
}
|
||||
|
||||
async function generate(opts: CliOptions, log: JsonLogger): Promise<GenerateResult> {
|
||||
const startEpoch = Date.now();
|
||||
const prompt = await loadPrompt(opts);
|
||||
|
||||
// Cache lookup
|
||||
if (opts.cacheDir) {
|
||||
const key = cacheKey(prompt, opts.aspect, opts.refImages);
|
||||
const cached = await lookupCache(opts.cacheDir, key);
|
||||
if (cached) {
|
||||
await mkdir(path.dirname(opts.outputPath), { recursive: true });
|
||||
await copyFile(cached, opts.outputPath);
|
||||
const s = await stat(opts.outputPath);
|
||||
await log.info("cache.hit", { key, source: cached });
|
||||
return {
|
||||
status: "ok",
|
||||
path: opts.outputPath,
|
||||
bytes: s.size,
|
||||
elapsed_seconds: 0,
|
||||
thread_id: null,
|
||||
attempts: 0,
|
||||
cached: true,
|
||||
usage: null,
|
||||
tool_calls: [],
|
||||
};
|
||||
}
|
||||
await log.info("cache.miss", { key });
|
||||
}
|
||||
|
||||
// lock to prevent concurrent codex exec
|
||||
const lockDir = opts.cacheDir ?? path.join(homedir(), ".cache", "baoyu-codex-imagegen");
|
||||
const lock = new FileLock(path.join(lockDir, "codex-exec.lock"));
|
||||
try {
|
||||
await lock.acquire(60_000);
|
||||
} catch (e) {
|
||||
throw new GenError("lock_busy", String(e), false);
|
||||
}
|
||||
|
||||
await mkdir(path.dirname(opts.outputPath), { recursive: true });
|
||||
const instruction = buildInstruction(prompt, opts);
|
||||
|
||||
let lastErr: GenError | null = null;
|
||||
let lastAttempt = 0;
|
||||
try {
|
||||
for (let attempt = 1; attempt <= opts.retries + 1; attempt++) {
|
||||
lastAttempt = attempt;
|
||||
try {
|
||||
const result = await attemptGenerate(opts, instruction, attempt, log);
|
||||
|
||||
// write to cache
|
||||
if (opts.cacheDir) {
|
||||
const key = cacheKey(prompt, opts.aspect, opts.refImages);
|
||||
await storeCache(opts.cacheDir, key, opts.outputPath);
|
||||
await log.info("cache.stored", { key });
|
||||
}
|
||||
|
||||
return {
|
||||
status: "ok",
|
||||
path: opts.outputPath,
|
||||
bytes: result.bytes,
|
||||
elapsed_seconds: Math.round((Date.now() - startEpoch) / 1000),
|
||||
thread_id: result.threadId,
|
||||
attempts: attempt,
|
||||
cached: false,
|
||||
usage: result.usage,
|
||||
tool_calls: result.toolCalls,
|
||||
};
|
||||
} catch (e) {
|
||||
lastErr = e instanceof GenError ? e : new GenError("spawn_failed", String(e));
|
||||
await log.warn("attempt.failed", {
|
||||
attempt,
|
||||
kind: lastErr.kind,
|
||||
retryable: lastErr.retryable,
|
||||
error: lastErr.message,
|
||||
});
|
||||
if (!lastErr.retryable || attempt > opts.retries) break;
|
||||
const wait = opts.retryDelayMs * Math.pow(2, attempt - 1);
|
||||
await log.info("retry.wait", { wait_ms: wait, next_attempt: attempt + 1 });
|
||||
await delay(wait);
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
await lock.release();
|
||||
}
|
||||
|
||||
const err = lastErr ?? new GenError("spawn_failed", "Unknown failure");
|
||||
err.attempts = lastAttempt;
|
||||
throw err;
|
||||
}
|
||||
|
||||
async function main() {
|
||||
let opts: CliOptions;
|
||||
try {
|
||||
opts = parseArgs(process.argv.slice(2));
|
||||
} catch (e) {
|
||||
const err = e instanceof GenError ? e : new GenError("invalid_args", String(e), false);
|
||||
process.stderr.write(`Error: ${err.message}\n`);
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
const log = new JsonLogger(opts.logFile, opts.verbose);
|
||||
await log.info("start", { output: opts.outputPath, aspect: opts.aspect, refs: opts.refImages.length });
|
||||
|
||||
try {
|
||||
const result = await generate(opts, log);
|
||||
await log.info("done", { bytes: result.bytes, attempts: result.attempts, cached: result.cached });
|
||||
process.stdout.write(JSON.stringify(result) + "\n");
|
||||
process.exit(0);
|
||||
} catch (e) {
|
||||
const err = e instanceof GenError ? e : new GenError("spawn_failed", String(e));
|
||||
await log.error("failed", { kind: err.kind, error: err.message, attempts: err.attempts ?? 0 });
|
||||
const out: GenerateResult = {
|
||||
status: "error",
|
||||
path: opts.outputPath,
|
||||
bytes: 0,
|
||||
elapsed_seconds: 0,
|
||||
thread_id: null,
|
||||
attempts: err.attempts ?? 0,
|
||||
cached: false,
|
||||
usage: null,
|
||||
tool_calls: [],
|
||||
error: err.message,
|
||||
error_kind: err.kind,
|
||||
};
|
||||
process.stdout.write(JSON.stringify(out) + "\n");
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -0,0 +1,49 @@
|
||||
import { test, expect } from "bun:test";
|
||||
import { parseEventStream, hasImageGenInvocation } from "./parser.ts";
|
||||
|
||||
const REAL_PoC_STREAM = `{"type":"thread.started","thread_id":"019e40d3-30e3-7030-874d-773bc0d6d1eb"}
|
||||
{"type":"turn.started"}
|
||||
{"type":"item.started","item":{"id":"item_0","type":"command_execution","command":"sed -n '1,5p' /tmp/x.md","status":"in_progress"}}
|
||||
{"type":"item.completed","item":{"id":"item_0","type":"command_execution","command":"sed -n '1,5p' /tmp/x.md","exit_code":0,"status":"completed"}}
|
||||
{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"cp /Users/x/.codex/generated_images/019e40d3/ig_abc.png /tmp/out.png","status":"in_progress"}}
|
||||
{"type":"item.completed","item":{"id":"item_1","type":"command_execution","command":"cp /Users/x/.codex/generated_images/019e40d3/ig_abc.png /tmp/out.png","exit_code":0,"status":"completed"}}
|
||||
{"type":"item.completed","item":{"id":"item_2","type":"agent_message","text":"{\\"status\\":\\"ok\\",\\"path\\":\\"/tmp/out.png\\",\\"bytes\\":1234567}"}}
|
||||
{"type":"turn.completed","usage":{"input_tokens":100000,"cached_input_tokens":80000,"output_tokens":500,"reasoning_output_tokens":50}}`;
|
||||
|
||||
test("parseEventStream extracts threadId, toolCalls, agentMessage, usage", () => {
|
||||
const r = parseEventStream(REAL_PoC_STREAM);
|
||||
expect(r.threadId).toBe("019e40d3-30e3-7030-874d-773bc0d6d1eb");
|
||||
expect(r.toolCalls.length).toBe(3);
|
||||
expect(r.usage).toEqual({
|
||||
input: 100000,
|
||||
cached_input: 80000,
|
||||
output: 500,
|
||||
reasoning: 50,
|
||||
});
|
||||
expect(r.agentMessage).toContain('"status":"ok"');
|
||||
});
|
||||
|
||||
test("parseEventStream tolerates malformed lines", () => {
|
||||
const stream = `not json at all
|
||||
{"type":"thread.started","thread_id":"abc"}
|
||||
{partial json
|
||||
{"type":"turn.completed","usage":{"input_tokens":1,"cached_input_tokens":0,"output_tokens":1,"reasoning_output_tokens":0}}`;
|
||||
const r = parseEventStream(stream);
|
||||
expect(r.threadId).toBe("abc");
|
||||
expect(r.usage?.input).toBe(1);
|
||||
});
|
||||
|
||||
test("hasImageGenInvocation finds shell calls touching generated_images", () => {
|
||||
const r = parseEventStream(REAL_PoC_STREAM);
|
||||
// image_gen itself is not an event; inferred via generated_images cp path
|
||||
// this test only verifies parser behavior; driver logic lives in validator
|
||||
const hasCp = r.toolCalls.some((tc) => tc.command?.includes("generated_images"));
|
||||
expect(hasCp).toBe(true);
|
||||
});
|
||||
|
||||
test("hasImageGenInvocation (proper) returns false when no image_gen tool", () => {
|
||||
expect(hasImageGenInvocation([{ id: "1", tool: "shell", status: "completed" }])).toBe(false);
|
||||
expect(
|
||||
hasImageGenInvocation([{ id: "1", tool: "image_gen", status: "completed" }]),
|
||||
).toBe(true);
|
||||
});
|
||||
@@ -0,0 +1,64 @@
|
||||
import type { CodexRunResult, ToolCall, TokenUsage } from "./types.ts";
|
||||
|
||||
export function parseEventStream(raw: string): Omit<CodexRunResult, "rawLogPath" | "durationMs"> {
|
||||
const lines = raw.split("\n").filter((l) => l.trim().length > 0);
|
||||
let threadId: string | null = null;
|
||||
let agentMessage: string | null = null;
|
||||
let usage: TokenUsage | null = null;
|
||||
const toolCallsById = new Map<string, ToolCall>();
|
||||
|
||||
for (const line of lines) {
|
||||
let event: any;
|
||||
try {
|
||||
event = JSON.parse(line);
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
const type = event?.type;
|
||||
if (type === "thread.started") {
|
||||
threadId = event.thread_id ?? null;
|
||||
} else if (type === "item.started" || type === "item.completed") {
|
||||
const item = event.item;
|
||||
if (!item?.id) continue;
|
||||
const tc: ToolCall = {
|
||||
id: item.id,
|
||||
tool: deriveToolName(item),
|
||||
status: item.status ?? (type === "item.completed" ? "completed" : "in_progress"),
|
||||
command: item.command,
|
||||
};
|
||||
toolCallsById.set(item.id, tc);
|
||||
if (item.type === "agent_message" && type === "item.completed") {
|
||||
agentMessage = String(item.text ?? "");
|
||||
}
|
||||
} else if (type === "turn.completed") {
|
||||
const u = event.usage;
|
||||
if (u) {
|
||||
usage = {
|
||||
input: u.input_tokens ?? 0,
|
||||
cached_input: u.cached_input_tokens ?? 0,
|
||||
output: u.output_tokens ?? 0,
|
||||
reasoning: u.reasoning_output_tokens ?? 0,
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
threadId,
|
||||
toolCalls: Array.from(toolCallsById.values()),
|
||||
agentMessage,
|
||||
usage,
|
||||
};
|
||||
}
|
||||
|
||||
function deriveToolName(item: any): string {
|
||||
if (item.type === "command_execution") return "shell";
|
||||
if (item.type === "agent_message") return "agent_message";
|
||||
if (item.type === "image_gen" || item.type === "image_generation") return "image_gen";
|
||||
if (typeof item.tool === "string") return item.tool;
|
||||
return item.type ?? "unknown";
|
||||
}
|
||||
|
||||
export function hasImageGenInvocation(toolCalls: ToolCall[]): boolean {
|
||||
return toolCalls.some((tc) => tc.tool === "image_gen");
|
||||
}
|
||||
@@ -0,0 +1,81 @@
|
||||
import { spawn } from "node:child_process";
|
||||
import { writeFile, mkdtemp } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
import { GenError, type CodexRunResult } from "./types.ts";
|
||||
import { parseEventStream } from "./parser.ts";
|
||||
|
||||
export interface SpawnInput {
|
||||
instruction: string;
|
||||
timeoutMs: number;
|
||||
refImages?: string[];
|
||||
}
|
||||
|
||||
export async function runCodexExec(input: SpawnInput): Promise<CodexRunResult> {
|
||||
const start = Date.now();
|
||||
const logDir = await mkdtemp(path.join(tmpdir(), "codex-imggen-"));
|
||||
const rawLogPath = path.join(logDir, "stream.jsonl");
|
||||
|
||||
// --skip-git-repo-check: lets the wrapper run from non-git cwds
|
||||
// (e.g. /tmp, or a skill installed under ~/.claude/plugins/...).
|
||||
// Without it, codex refuses with "Not inside a trusted directory".
|
||||
const args = [
|
||||
"exec",
|
||||
"--json",
|
||||
"--sandbox",
|
||||
"danger-full-access",
|
||||
"--skip-git-repo-check",
|
||||
];
|
||||
for (const img of input.refImages ?? []) {
|
||||
args.push("--image", img);
|
||||
}
|
||||
args.push("-");
|
||||
|
||||
let timedOut = false;
|
||||
const child = spawn("codex", args, { stdio: ["pipe", "pipe", "pipe"] });
|
||||
|
||||
let stdout = "";
|
||||
let stderr = "";
|
||||
child.stdout.on("data", (chunk) => {
|
||||
stdout += chunk.toString();
|
||||
});
|
||||
child.stderr.on("data", (chunk) => {
|
||||
stderr += chunk.toString();
|
||||
});
|
||||
|
||||
child.stdin.write(input.instruction);
|
||||
child.stdin.end();
|
||||
|
||||
const timer = setTimeout(() => {
|
||||
timedOut = true;
|
||||
child.kill("SIGTERM");
|
||||
setTimeout(() => child.kill("SIGKILL"), 2000);
|
||||
}, input.timeoutMs);
|
||||
|
||||
const exit = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve) => {
|
||||
child.on("close", (code, signal) => resolve({ code, signal }));
|
||||
});
|
||||
clearTimeout(timer);
|
||||
|
||||
await writeFile(rawLogPath, stdout + (stderr ? `\n--- stderr ---\n${stderr}` : ""));
|
||||
|
||||
if (timedOut) {
|
||||
throw new GenError("timeout", `codex exec exceeded ${input.timeoutMs}ms (log: ${rawLogPath})`);
|
||||
}
|
||||
if (exit.code !== 0) {
|
||||
if (stderr.includes("command not found") || stderr.includes("not found: codex")) {
|
||||
throw new GenError("codex_not_installed", "codex CLI not installed", false);
|
||||
}
|
||||
throw new GenError(
|
||||
"spawn_failed",
|
||||
`codex exec exited ${exit.code} signal=${exit.signal} (log: ${rawLogPath})`,
|
||||
);
|
||||
}
|
||||
|
||||
const parsed = parseEventStream(stdout);
|
||||
return {
|
||||
...parsed,
|
||||
rawLogPath,
|
||||
durationMs: Date.now() - start,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
export interface CliOptions {
|
||||
prompt: string;
|
||||
promptFile: string | null;
|
||||
outputPath: string;
|
||||
aspect: string;
|
||||
refImages: string[];
|
||||
timeoutMs: number;
|
||||
retries: number;
|
||||
retryDelayMs: number;
|
||||
cacheDir: string | null;
|
||||
logFile: string | null;
|
||||
verbose: boolean;
|
||||
}
|
||||
|
||||
export interface ToolCall {
|
||||
id: string;
|
||||
tool: string;
|
||||
status: string;
|
||||
command?: string;
|
||||
}
|
||||
|
||||
export interface TokenUsage {
|
||||
input: number;
|
||||
cached_input: number;
|
||||
output: number;
|
||||
reasoning: number;
|
||||
}
|
||||
|
||||
export interface CodexRunResult {
|
||||
threadId: string | null;
|
||||
toolCalls: ToolCall[];
|
||||
agentMessage: string | null;
|
||||
usage: TokenUsage | null;
|
||||
rawLogPath: string;
|
||||
durationMs: number;
|
||||
}
|
||||
|
||||
export interface GenerateResult {
|
||||
status: "ok" | "error";
|
||||
path: string;
|
||||
bytes: number;
|
||||
elapsed_seconds: number;
|
||||
thread_id: string | null;
|
||||
attempts: number;
|
||||
cached: boolean;
|
||||
usage: TokenUsage | null;
|
||||
tool_calls: { tool: string; status: string }[];
|
||||
error?: string;
|
||||
error_kind?: ErrorKind;
|
||||
}
|
||||
|
||||
export type ErrorKind =
|
||||
| "codex_not_installed"
|
||||
| "invalid_args"
|
||||
| "prompt_file_missing"
|
||||
| "spawn_failed"
|
||||
| "timeout"
|
||||
| "no_image_gen_tool_use"
|
||||
| "output_missing"
|
||||
| "invalid_png"
|
||||
| "agent_refused"
|
||||
| "lock_busy";
|
||||
|
||||
export const RETRYABLE: ReadonlySet<ErrorKind> = new Set([
|
||||
"spawn_failed",
|
||||
"timeout",
|
||||
"no_image_gen_tool_use",
|
||||
"output_missing",
|
||||
"invalid_png",
|
||||
"agent_refused",
|
||||
]);
|
||||
|
||||
export class GenError extends Error {
|
||||
attempts?: number;
|
||||
constructor(public kind: ErrorKind, message: string, public retryable?: boolean) {
|
||||
super(message);
|
||||
this.retryable = retryable ?? RETRYABLE.has(kind);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,98 @@
|
||||
import { test, expect } from "bun:test";
|
||||
import { mkdtemp, writeFile, rm, mkdir } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
import { verifyOutput, verifyImageGenWasInvoked, findCpToTarget } from "./validator.ts";
|
||||
import { GenError } from "./types.ts";
|
||||
|
||||
const PNG_HEADER = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
|
||||
|
||||
test("verifyOutput passes for valid PNG", async () => {
|
||||
const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
|
||||
try {
|
||||
const p = path.join(dir, "good.png");
|
||||
await writeFile(p, Buffer.concat([PNG_HEADER, Buffer.alloc(5000)]));
|
||||
const r = await verifyOutput(p);
|
||||
expect(r.bytes).toBeGreaterThan(1000);
|
||||
} finally {
|
||||
await rm(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("verifyOutput rejects missing file", async () => {
|
||||
await expect(verifyOutput("/no/such/file.png")).rejects.toBeInstanceOf(GenError);
|
||||
});
|
||||
|
||||
test("verifyOutput rejects tiny file", async () => {
|
||||
const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
|
||||
try {
|
||||
const p = path.join(dir, "tiny.png");
|
||||
await writeFile(p, "tiny");
|
||||
await expect(verifyOutput(p)).rejects.toThrow(/too small/);
|
||||
} finally {
|
||||
await rm(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("verifyOutput rejects non-PNG magic", async () => {
|
||||
const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
|
||||
try {
|
||||
const p = path.join(dir, "fake.png");
|
||||
await writeFile(p, Buffer.concat([Buffer.from("GIF89a"), Buffer.alloc(5000)]));
|
||||
await expect(verifyOutput(p)).rejects.toThrow(/not a valid PNG/);
|
||||
} finally {
|
||||
await rm(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("verifyImageGenWasInvoked false when no thread directory", async () => {
|
||||
const orig = process.env.CODEX_HOME;
|
||||
const tempHome = await mkdtemp(path.join(tmpdir(), "cig-home-"));
|
||||
process.env.CODEX_HOME = tempHome;
|
||||
try {
|
||||
const r = await verifyImageGenWasInvoked("no-such-thread");
|
||||
expect(r.ok).toBe(false);
|
||||
} finally {
|
||||
process.env.CODEX_HOME = orig;
|
||||
await rm(tempHome, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("verifyImageGenWasInvoked true when PNG exists in thread dir", async () => {
|
||||
const orig = process.env.CODEX_HOME;
|
||||
const tempHome = await mkdtemp(path.join(tmpdir(), "cig-home-"));
|
||||
process.env.CODEX_HOME = tempHome;
|
||||
try {
|
||||
const threadDir = path.join(tempHome, "generated_images", "thread-xyz");
|
||||
await mkdir(threadDir, { recursive: true });
|
||||
await writeFile(path.join(threadDir, "ig_abc.png"), Buffer.alloc(100));
|
||||
const r = await verifyImageGenWasInvoked("thread-xyz");
|
||||
expect(r.ok).toBe(true);
|
||||
} finally {
|
||||
process.env.CODEX_HOME = orig;
|
||||
await rm(tempHome, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("findCpToTarget detects cp from generated_images", () => {
|
||||
expect(
|
||||
findCpToTarget(
|
||||
[
|
||||
{
|
||||
id: "1",
|
||||
tool: "shell",
|
||||
status: "completed",
|
||||
command: "cp ~/.codex/generated_images/thread/ig_x.png /tmp/out.png",
|
||||
},
|
||||
],
|
||||
"/tmp/out.png",
|
||||
),
|
||||
).toBe(true);
|
||||
|
||||
expect(
|
||||
findCpToTarget(
|
||||
[{ id: "1", tool: "shell", status: "completed", command: "ls /tmp" }],
|
||||
"/tmp/out.png",
|
||||
),
|
||||
).toBe(false);
|
||||
});
|
||||
@@ -0,0 +1,55 @@
|
||||
import { stat, readdir } from "node:fs/promises";
|
||||
import { homedir } from "node:os";
|
||||
import path from "node:path";
|
||||
import { GenError } from "./types.ts";
|
||||
import type { ToolCall } from "./types.ts";
|
||||
|
||||
const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
|
||||
|
||||
export function codexHome(): string {
|
||||
return process.env.CODEX_HOME ?? path.join(homedir(), ".codex");
|
||||
}
|
||||
|
||||
export async function verifyImageGenWasInvoked(threadId: string | null): Promise<{ ok: boolean; reason?: string }> {
|
||||
if (!threadId) return { ok: false, reason: "no thread id" };
|
||||
const dir = path.join(codexHome(), "generated_images", threadId);
|
||||
try {
|
||||
const entries = await readdir(dir);
|
||||
const pngs = entries.filter((e) => e.toLowerCase().endsWith(".png"));
|
||||
if (pngs.length === 0) return { ok: false, reason: `no PNG in ${dir}` };
|
||||
return { ok: true };
|
||||
} catch (e: any) {
|
||||
return { ok: false, reason: `cannot read ${dir}: ${e?.code ?? e?.message}` };
|
||||
}
|
||||
}
|
||||
|
||||
export function findCpToTarget(toolCalls: ToolCall[], target: string): boolean {
|
||||
return toolCalls.some(
|
||||
(tc) =>
|
||||
tc.tool === "shell" &&
|
||||
typeof tc.command === "string" &&
|
||||
(tc.command.includes(target) || tc.command.includes(path.basename(target))) &&
|
||||
/\b(cp|mv|cat)\b/.test(tc.command) &&
|
||||
tc.command.includes("generated_images"),
|
||||
);
|
||||
}
|
||||
|
||||
export async function verifyOutput(outputPath: string): Promise<{ bytes: number }> {
|
||||
let s;
|
||||
try {
|
||||
s = await stat(outputPath);
|
||||
} catch {
|
||||
throw new GenError("output_missing", `Output file not created: ${outputPath}`);
|
||||
}
|
||||
if (s.size < 1000) {
|
||||
throw new GenError("invalid_png", `Output file too small (${s.size} bytes)`);
|
||||
}
|
||||
const file = Bun.file(outputPath);
|
||||
const head = new Uint8Array(await file.slice(0, 8).arrayBuffer());
|
||||
for (let i = 0; i < PNG_MAGIC.length; i++) {
|
||||
if (head[i] !== PNG_MAGIC[i]) {
|
||||
throw new GenError("invalid_png", `Output is not a valid PNG (magic mismatch)`);
|
||||
}
|
||||
}
|
||||
return { bytes: s.size };
|
||||
}
|
||||
@@ -29,6 +29,19 @@ When this skill needs to render an image, resolve the backend in this order:
|
||||
2. **Saved preference** — if `EXTEND.md` sets `preferred_image_backend` to a backend available right now, use it.
|
||||
3. **Auto-select** (when the preference is `auto`, unset, or the pinned backend isn't available):
|
||||
- **Codex (`imagegen`)** — first, inspect your available-skills / tool inventory. If a skill named `imagegen` is listed, you are running inside Codex and MUST use it: invoke via the `Skill` tool with `skill: "imagegen"`, passing the saved prompt file's content (plus output path and aspect ratio per Codex `imagegen`'s own args). Codex `imagegen` is the official raster backend in that runtime and outranks any non-native skill (e.g., `baoyu-imagine`) unless the user has explicitly pinned a different `preferred_image_backend`.
|
||||
- **Codex via `codex exec` (`codex-imagegen`)** — if the current runtime does NOT expose a native `imagegen` skill but the `codex` CLI is on `PATH` and `codex login` is active (e.g., Claude Code with Codex CLI installed), invoke the `codex-imagegen` wrapper. **Path resolution**: `scripts/codex-imagegen.sh` lives at the plugin/repo root, NOT relative to your shell cwd. From this `SKILL.md`'s base directory, the wrapper is at `../../scripts/codex-imagegen.sh` — resolve to an absolute path before invoking. Command shape:
|
||||
```bash
|
||||
<ABSOLUTE_PLUGIN_ROOT>/scripts/codex-imagegen.sh \
|
||||
--image <absolute_output_path> \
|
||||
--prompt-file <absolute_path_to_prompts/NN-cover-[slug].md> \
|
||||
--aspect <ratio> \
|
||||
[--ref <absolute_file>]... \
|
||||
[--timeout <ms>] \
|
||||
[--cache-dir ~/.cache/baoyu-codex-imagegen] \
|
||||
[--log-file <absolute_jsonl_log_path>]
|
||||
```
|
||||
`--timeout` defaults to 300000 (5 min) per codex exec attempt; raise it (e.g. `--timeout 600000` for 10 min) on slow networks or large prompts.
|
||||
All input paths to the wrapper are auto-resolved against the wrapper's `process.cwd()` if you pass relative ones, but agents should pass absolute paths to be robust against cwd drift. Parse the single-line JSON on stdout. On `{"status":"ok",...}` proceed to Step 5. On `{"status":"error","error_kind":...}` report the `error_kind` to the user and (if retryable) ask whether to retry or fall back to another backend. The wrapper uses the user's Codex subscription — no `OPENAI_API_KEY` needed.
|
||||
- **Other runtime-native tools** — if the runtime exposes a different native image tool (e.g., Hermes `image_generate`), use it the same way.
|
||||
- Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-imagine`), use it.
|
||||
- Otherwise (multiple non-native backends with no runtime-native tool), ask the user once — batch with any other initial questions.
|
||||
@@ -214,7 +227,9 @@ Save to `prompts/cover.md`. Template: [references/workflow/prompt-template.md](r
|
||||
4. **Process references** from prompt frontmatter:
|
||||
- `direct` usage → pass via `--ref` (use ref-capable backend)
|
||||
- `style`/`palette` → extract traits, append to prompt
|
||||
5. **Generate**: Call the chosen backend with the prompt file, output path, aspect ratio
|
||||
5. **Generate**: Call the chosen backend with the prompt file, output path, aspect ratio.
|
||||
- **`codex-imagegen`**: invoke `<ABSOLUTE_PLUGIN_ROOT>/scripts/codex-imagegen.sh` (NOT a cwd-relative `./scripts/...` — resolve the absolute path from this skill's base directory: `../../scripts/codex-imagegen.sh`) with `--image <ABSOLUTE_output>` `--prompt-file <ABSOLUTE_prompts/01-cover-[slug].md>` `--aspect <ratio>` (add `--ref <ABSOLUTE_file>` per reference, `--cache-dir ~/.cache/baoyu-codex-imagegen` to enable the idempotency cache, `--timeout <ms>` to override the default 300000 / 5-min per-attempt limit on slow networks). All input paths to the wrapper are auto-resolved against its `process.cwd()` if relative, but passing absolutes is more robust. Read the stdout JSON; act on `status` and `error_kind`.
|
||||
- **Codex `imagegen` (native)** or other runtime-native tools / `baoyu-imagine` skill: per the rule in `## Image Generation Tools` above.
|
||||
6. On failure: auto-retry once
|
||||
|
||||
### Step 5: Completion Report
|
||||
|
||||
@@ -0,0 +1,140 @@
|
||||
---
|
||||
name: baoyu-electron-extract
|
||||
description: Extracts resources and JavaScript from any installed Electron app (`.asar` bundle), restoring original sources from `.js.map` files when available or formatting minified code with Prettier otherwise. Use when user wants to "extract Electron app", "decompile Electron", "get the source code of <app>", "inspect app.asar", "看 Electron 应用源码", "提取 .asar", or asks how a desktop Electron app is built. Skips `node_modules` and supports both macOS and Windows.
|
||||
version: 1.119.0
|
||||
metadata:
|
||||
openclaw:
|
||||
homepage: https://github.com/JimLiu/baoyu-skills#baoyu-electron-extract
|
||||
requires:
|
||||
anyBins:
|
||||
- bun
|
||||
- npx
|
||||
---
|
||||
|
||||
# Electron App Extract
|
||||
|
||||
Extracts resources and code from an installed Electron app's `app.asar`. When a `.js.map` is present, restores the original source files from the embedded `sourcesContent`; otherwise formats the minified code with Prettier. Source-map paths are resolved relative to the `.js.map` file first, so bundled paths like `../../src/main.ts` restore to readable paths such as `restored/src/main.ts` instead of hashed placeholders. Always skips `node_modules`. Works on macOS and Windows.
|
||||
|
||||
## User Input Tools
|
||||
|
||||
When this skill prompts the user, follow this tool-selection rule (priority order):
|
||||
|
||||
1. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
|
||||
2. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
|
||||
3. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.
|
||||
|
||||
Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
|
||||
|
||||
## Script Directory
|
||||
|
||||
Scripts in `scripts/` subdirectory. `{baseDir}` = this SKILL.md's directory path. Resolve `${BUN_X}` runtime: if `bun` installed → `bun`; if `npx` available → `npx -y bun`; else suggest installing bun. Replace `{baseDir}` and `${BUN_X}` with actual values.
|
||||
|
||||
| Script | Purpose |
|
||||
| ----------------- | ------------------------------------------------------------------------------ |
|
||||
| `scripts/main.ts` | App discovery + asar extraction + source-map restoration + Prettier formatting |
|
||||
|
||||
## When to use
|
||||
|
||||
Use this skill whenever the user wants to look inside an installed Electron application or inspect its bundled code. Trigger phrases include:
|
||||
|
||||
- "extract Electron app", "decompile this Electron app", "unpack app.asar"
|
||||
- "show me the source of <app>", "look inside <app>", "how is <app> built"
|
||||
- "get the source code of Codex / Cursor / Discord / Slack / VS Code / Notion / Obsidian / ChatGPT desktop"
|
||||
- "提取 Electron 应用", "看 <app> 的源码", "反编译 Electron", "解包 app.asar", "还原 source map"
|
||||
|
||||
Both **app name** (e.g., `Codex`) and **absolute path** (e.g., `/Applications/Codex.app`, a `.asar` file, or a Windows install dir) are accepted. The script handles discovery for both platforms.
|
||||
|
||||
## Workflow
|
||||
|
||||
**1. Determine the input.** Ask the user for the app name or path if they haven't given one. If they want a custom output directory, ask for that too.
|
||||
|
||||
**2. Run the script.**
|
||||
|
||||
```bash
|
||||
${BUN_X} {baseDir}/scripts/main.ts "<app>" [--output <dir>] [--asar <path>] [--force]
|
||||
```
|
||||
|
||||
Start with `--dry-run` first if you're unsure whether discovery will find the right bundle — it prints the resolved paths and exits without touching the filesystem.
|
||||
|
||||
**3. Handle the result.**
|
||||
|
||||
- **Success** → report the output paths and the counts (extracted / restored / formatted).
|
||||
- **Multiple matches** → the script lists candidates and exits non-zero. Show the user the candidates, ask which one to use (via `AskUserQuestion` or the runtime equivalent), then re-run with the chosen absolute path.
|
||||
- **Existing non-empty output dir** → the script refuses without `--force`. Ask the user whether to overwrite (`--force`) or pick a new `--output` path.
|
||||
- **Unsupported platform / no match** → suggest passing `--asar /full/path/to/app.asar` if the user knows where the bundle lives.
|
||||
|
||||
**4. Point the user at the result.** The default output dir is `~/Downloads/<AppName>-electron-extract/`. The most interesting subdirectory depends on what was found:
|
||||
|
||||
- `restored/` exists → the original source tree was reconstructed from `.js.map` files; this is what to read first.
|
||||
- Only `extracted/` exists (no maps) → the JS/CSS in `extracted/` was Prettier-formatted in place; read from there.
|
||||
|
||||
## Source-map path restoration
|
||||
|
||||
The script should preserve original source names and directory structure as much as the source map allows:
|
||||
|
||||
- Resolve each `sources[]` entry with `sourceRoot` when present, then relative to the `.js.map` file's directory inside `extracted/`.
|
||||
- Collapse normal bundler-relative paths into the restored project tree. For example, `.vite/main/index.js.map` + `../../src/main.ts` becomes `restored/src/main.ts`.
|
||||
- If a source path climbs above `extracted/`, keep the readable remaining path under `restored/` instead of hashing it. For example, `.vite/main/index.js.map` + `../../../shared/src/lib/foo.ts` becomes `restored/shared/src/lib/foo.ts`.
|
||||
- Strip URL/query decorations from source names, including common `webpack://`, `file://`, and `?loader` suffixes.
|
||||
- Use `restored/__unknown/<hash>.<ext>` only when the source name is empty or cannot be reduced to a safe file path.
|
||||
- Continue skipping `node_modules` and `webpack/runtime/*` entries; these are bundler/runtime noise, not app sources.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Extract by app name (default output: ~/Downloads/Codex-electron-extract/)
|
||||
${BUN_X} {baseDir}/scripts/main.ts Codex
|
||||
|
||||
# Extract by absolute path (works for .app bundles, install dirs, or .asar files)
|
||||
${BUN_X} {baseDir}/scripts/main.ts "/Applications/Visual Studio Code.app"
|
||||
${BUN_X} {baseDir}/scripts/main.ts "C:\Users\you\AppData\Local\Programs\codex"
|
||||
${BUN_X} {baseDir}/scripts/main.ts --asar /Applications/Codex.app/Contents/Resources/app.asar Codex
|
||||
|
||||
# Custom output
|
||||
${BUN_X} {baseDir}/scripts/main.ts Codex --output ~/work/codex-source
|
||||
|
||||
# Preview discovery without writing anything
|
||||
${BUN_X} {baseDir}/scripts/main.ts Codex --dry-run
|
||||
|
||||
# Overwrite an existing output dir
|
||||
${BUN_X} {baseDir}/scripts/main.ts Codex --force
|
||||
|
||||
# Machine-readable result (one JSON line on stdout)
|
||||
${BUN_X} {baseDir}/scripts/main.ts Codex --json
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Short | Description | Default |
|
||||
| ---------------- | ----- | --------------------------------------------------------------- | ---------------------------------------- |
|
||||
| `<app>` | | App name or absolute path. Required unless `--asar` is given. | — |
|
||||
| `--output` | `-o` | Output directory | `~/Downloads/<AppName>-electron-extract` |
|
||||
| `--asar` | | Override the resolved `.asar` path | auto-discovered |
|
||||
| `--force` | `-f` | Allow writing into a non-empty existing output dir | false |
|
||||
| `--skip-format` | | Skip Prettier formatting | false |
|
||||
| `--skip-restore` | | Skip source-map restoration | false |
|
||||
| `--no-unpacked` | | Don't copy `app.asar.unpacked/` alongside | false |
|
||||
| `--dry-run` | | Print resolved paths and exit without writing | false |
|
||||
| `--json` | | Emit one JSON-line summary on stdout (suppresses normal output) | false |
|
||||
|
||||
## Output layout
|
||||
|
||||
```
|
||||
~/Downloads/<AppName>-electron-extract/
|
||||
├── extract-report.json # JSON summary: counts, warnings, resolved paths
|
||||
├── extracted/ # raw asar contents (JS/CSS Prettier-formatted when no map)
|
||||
│ └── ... # node_modules left untouched (skipped from format)
|
||||
├── extracted.unpacked/ # copied from <asar>.unpacked/ if present
|
||||
│ └── ... # native modules (.node), large assets
|
||||
└── restored/ # only present if at least one .js.map was usable
|
||||
└── <original/source/tree> # rebuilt from sourcesContent in each .js.map
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- **node_modules** is always skipped — both for source-map restoration and Prettier formatting — because vendored dependencies are noise when inspecting an app.
|
||||
- **Source-map restoration** only works when the `.js.map` embeds `sourcesContent`. This is the common case for modern bundlers (webpack, esbuild, Vite, rollup). If a map references external `.ts`/`.js` files without embedding them, that map is skipped and the corresponding `.js` is Prettier-formatted instead. Skipped maps are listed in `extract-report.json` under `warnings`.
|
||||
- **Readable paths over hashes** — don't treat `../` segments in source-map paths as automatically unsafe. First resolve them from the map location and then sanitize the final output path so it still stays under `restored/`. Hash fallback is only for unusable source names.
|
||||
- **App discovery** searches `/Applications` + `~/Applications` on macOS, and `%LOCALAPPDATA%\Programs`, `%PROGRAMFILES%`, `%PROGRAMFILES(X86)%`, `%APPDATA%` on Windows. If discovery finds multiple matches, the script exits and lists them — re-run with an absolute path. On Linux or other platforms, pass `--asar /path/to/app.asar` explicitly.
|
||||
- **Safety** — the script refuses to write to `/`, the user home directly, or the current working directory, and refuses to populate an existing non-empty output dir without `--force`.
|
||||
- **No global installs** — `@electron/asar` and `prettier` are resolved on-the-fly via `npx -y`. First run will be slower while npx caches them.
|
||||
@@ -0,0 +1,123 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
import test from "node:test";
|
||||
|
||||
import { normalizeSourcePath, restoreFromMap } from "./main.ts";
|
||||
|
||||
test("normalizes Vite source map paths into readable project paths", () => {
|
||||
const extractedRoot = path.join(os.tmpdir(), "app", "extracted");
|
||||
const mapPath = path.join(extractedRoot, ".vite", "main", "index.js.map");
|
||||
|
||||
assert.equal(
|
||||
normalizeSourcePath(
|
||||
"../../src/main/agent/claude-agent.ts",
|
||||
mapPath,
|
||||
extractedRoot,
|
||||
undefined
|
||||
),
|
||||
"src/main/agent/claude-agent.ts"
|
||||
);
|
||||
|
||||
assert.equal(
|
||||
normalizeSourcePath(
|
||||
"../../../shared/src/lib/prompt-classification.ts",
|
||||
mapPath,
|
||||
extractedRoot,
|
||||
undefined
|
||||
),
|
||||
"shared/src/lib/prompt-classification.ts"
|
||||
);
|
||||
|
||||
assert.equal(
|
||||
normalizeSourcePath(
|
||||
"./src/renderer/app.tsx",
|
||||
mapPath,
|
||||
extractedRoot,
|
||||
"webpack://moss/"
|
||||
),
|
||||
"moss/src/renderer/app.tsx"
|
||||
);
|
||||
});
|
||||
|
||||
test("restores source map sources without hashing usable relative paths", async () => {
|
||||
const root = await mkdtemp(path.join(os.tmpdir(), "baoyu-electron-extract-"));
|
||||
try {
|
||||
const extractedRoot = path.join(root, "extracted");
|
||||
const restoredRoot = path.join(root, "restored");
|
||||
const mapDir = path.join(extractedRoot, ".vite", "main");
|
||||
const mapPath = path.join(mapDir, "index.js.map");
|
||||
await mkdir(mapDir, { recursive: true });
|
||||
await writeFile(
|
||||
mapPath,
|
||||
JSON.stringify({
|
||||
version: 3,
|
||||
file: "index.js",
|
||||
sources: [
|
||||
"../../src/main.ts",
|
||||
"../../src/common/ipcChannels.ts",
|
||||
"../../../shared/src/lib/prompt-classification.ts",
|
||||
"webpack://moss/./src/renderer/app.tsx",
|
||||
"../../../../node_modules/pkg/index.js",
|
||||
"..\\..\\node_modules\\windows-pkg\\index.js",
|
||||
"webpack/runtime/chunk loading",
|
||||
],
|
||||
sourcesContent: [
|
||||
"export const main = true;\n",
|
||||
"export const ipc = true;\n",
|
||||
"export const shared = true;\n",
|
||||
"export const renderer = true;\n",
|
||||
"module.exports = {};\n",
|
||||
"module.exports = {};\n",
|
||||
"runtime();\n",
|
||||
],
|
||||
}),
|
||||
"utf8"
|
||||
);
|
||||
|
||||
const warnings: string[] = [];
|
||||
const restored = restoreFromMap(
|
||||
mapPath,
|
||||
extractedRoot,
|
||||
restoredRoot,
|
||||
warnings
|
||||
);
|
||||
|
||||
assert.equal(restored, 4);
|
||||
assert.deepEqual(warnings, []);
|
||||
assert.equal(
|
||||
await readFile(path.join(restoredRoot, "src", "main.ts"), "utf8"),
|
||||
"export const main = true;\n"
|
||||
);
|
||||
assert.equal(
|
||||
await readFile(
|
||||
path.join(restoredRoot, "src", "common", "ipcChannels.ts"),
|
||||
"utf8"
|
||||
),
|
||||
"export const ipc = true;\n"
|
||||
);
|
||||
assert.equal(
|
||||
await readFile(
|
||||
path.join(
|
||||
restoredRoot,
|
||||
"shared",
|
||||
"src",
|
||||
"lib",
|
||||
"prompt-classification.ts"
|
||||
),
|
||||
"utf8"
|
||||
),
|
||||
"export const shared = true;\n"
|
||||
);
|
||||
assert.equal(
|
||||
await readFile(
|
||||
path.join(restoredRoot, "moss", "src", "renderer", "app.tsx"),
|
||||
"utf8"
|
||||
),
|
||||
"export const renderer = true;\n"
|
||||
);
|
||||
} finally {
|
||||
await rm(root, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
@@ -0,0 +1,928 @@
|
||||
#!/usr/bin/env bun
|
||||
import {
|
||||
cpSync,
|
||||
existsSync,
|
||||
mkdirSync,
|
||||
readdirSync,
|
||||
readFileSync,
|
||||
statSync,
|
||||
writeFileSync,
|
||||
} from "fs";
|
||||
import {
|
||||
basename,
|
||||
dirname,
|
||||
extname,
|
||||
isAbsolute,
|
||||
join,
|
||||
posix as posixPath,
|
||||
relative,
|
||||
resolve,
|
||||
sep,
|
||||
} from "path";
|
||||
import { createHash } from "crypto";
|
||||
import { spawn, spawnSync } from "child_process";
|
||||
import { homedir } from "os";
|
||||
import { pathToFileURL } from "url";
|
||||
|
||||
interface Options {
|
||||
app: string;
|
||||
output?: string;
|
||||
asar?: string;
|
||||
force: boolean;
|
||||
skipFormat: boolean;
|
||||
skipRestore: boolean;
|
||||
noUnpacked: boolean;
|
||||
dryRun: boolean;
|
||||
json: boolean;
|
||||
}
|
||||
|
||||
interface ResolvedApp {
|
||||
appName: string;
|
||||
asarPath: string;
|
||||
unpackedDir: string | null;
|
||||
installRoot: string | null;
|
||||
}
|
||||
|
||||
interface Counts {
|
||||
extractedFiles: number;
|
||||
restoredFiles: number;
|
||||
formattedFiles: number;
|
||||
skippedNodeModules: number;
|
||||
unpackedFiles: number;
|
||||
}
|
||||
|
||||
interface Report {
|
||||
appName: string;
|
||||
source: {
|
||||
input: string;
|
||||
asar: string;
|
||||
platform: string;
|
||||
installRoot: string | null;
|
||||
};
|
||||
output: {
|
||||
root: string;
|
||||
extracted: string;
|
||||
unpacked: string | null;
|
||||
restored: string | null;
|
||||
};
|
||||
counts: Counts;
|
||||
warnings: string[];
|
||||
durationMs: number;
|
||||
}
|
||||
|
||||
function usage(): string {
|
||||
return `Usage: main.ts <app> [options]
|
||||
|
||||
Extract resources & JavaScript from an installed Electron app.
|
||||
|
||||
Arguments:
|
||||
<app> App name (e.g. "Codex", "Visual Studio Code") or absolute
|
||||
path to a .app bundle, install directory, or .asar file.
|
||||
|
||||
Options:
|
||||
-o, --output PATH Output directory (default: ~/Downloads/<App>-electron-extract)
|
||||
--asar PATH Override the resolved .asar path
|
||||
-f, --force Allow writing into a non-empty existing output dir
|
||||
--skip-format Skip Prettier formatting (extract only)
|
||||
--skip-restore Skip source-map restoration
|
||||
--no-unpacked Don't copy app.asar.unpacked/ alongside
|
||||
--dry-run Print resolved paths and exit without writing
|
||||
--json Emit a single JSON line summary to stdout
|
||||
-h, --help Show this help
|
||||
`;
|
||||
}
|
||||
|
||||
function fail(message: string, json: boolean): never {
|
||||
if (json) {
|
||||
process.stdout.write(
|
||||
JSON.stringify({ status: "error", error: message }) + "\n"
|
||||
);
|
||||
} else {
|
||||
process.stderr.write(`Error: ${message}\n`);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
function parseArgs(argv: string[]): Options {
|
||||
const opts: Options = {
|
||||
app: "",
|
||||
force: false,
|
||||
skipFormat: false,
|
||||
skipRestore: false,
|
||||
noUnpacked: false,
|
||||
dryRun: false,
|
||||
json: false,
|
||||
};
|
||||
const positional: string[] = [];
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const a = argv[i];
|
||||
if (a === "-h" || a === "--help") {
|
||||
process.stdout.write(usage());
|
||||
process.exit(0);
|
||||
} else if (a === "-o" || a === "--output") {
|
||||
opts.output = argv[++i];
|
||||
} else if (a === "--asar") {
|
||||
opts.asar = argv[++i];
|
||||
} else if (a === "-f" || a === "--force") {
|
||||
opts.force = true;
|
||||
} else if (a === "--skip-format") {
|
||||
opts.skipFormat = true;
|
||||
} else if (a === "--skip-restore") {
|
||||
opts.skipRestore = true;
|
||||
} else if (a === "--no-unpacked") {
|
||||
opts.noUnpacked = true;
|
||||
} else if (a === "--dry-run") {
|
||||
opts.dryRun = true;
|
||||
} else if (a === "--json") {
|
||||
opts.json = true;
|
||||
} else if (a.startsWith("-")) {
|
||||
throw new Error(`unknown option: ${a}\n\n${usage()}`);
|
||||
} else {
|
||||
positional.push(a);
|
||||
}
|
||||
}
|
||||
if (positional.length === 0 && !opts.asar) {
|
||||
throw new Error(
|
||||
`missing <app> argument (or pass --asar PATH)\n\n${usage()}`
|
||||
);
|
||||
}
|
||||
if (positional.length > 1) {
|
||||
throw new Error(
|
||||
`too many positional arguments: ${positional.join(", ")}\n\n${usage()}`
|
||||
);
|
||||
}
|
||||
opts.app = positional[0] ?? "";
|
||||
return opts;
|
||||
}
|
||||
|
||||
function sanitizeAppName(name: string): string {
|
||||
return name.replace(/[\\/:*?"<>|]/g, "_").replace(/\s+/g, "-");
|
||||
}
|
||||
|
||||
function appNameFromPath(p: string): string {
|
||||
const parts = resolve(p).split(sep);
|
||||
for (let i = parts.length - 1; i >= 0; i--) {
|
||||
if (parts[i].endsWith(".app")) return parts[i].slice(0, -4);
|
||||
}
|
||||
const n = basename(p);
|
||||
if (n === "app.asar") {
|
||||
if (
|
||||
parts.length >= 3 &&
|
||||
parts[parts.length - 2].toLowerCase() === "resources"
|
||||
) {
|
||||
return parts[parts.length - 3];
|
||||
}
|
||||
if (parts.length >= 2) return parts[parts.length - 2];
|
||||
}
|
||||
if (n.endsWith(".asar")) return n.slice(0, -5);
|
||||
if (n.endsWith(".app")) return n.slice(0, -4);
|
||||
return n;
|
||||
}
|
||||
|
||||
function existsAsFile(p: string): boolean {
|
||||
try {
|
||||
return statSync(p).isFile();
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function existsAsDir(p: string): boolean {
|
||||
try {
|
||||
return statSync(p).isDirectory();
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function findAsarUnderDir(dir: string): string | null {
|
||||
const candidates = [
|
||||
join(dir, "resources", "app.asar"),
|
||||
join(dir, "Resources", "app.asar"),
|
||||
join(dir, "app.asar"),
|
||||
];
|
||||
for (const c of candidates) {
|
||||
if (existsAsFile(c)) return c;
|
||||
}
|
||||
if (!existsAsDir(dir)) return null;
|
||||
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
const nested = join(dir, entry.name, "resources", "app.asar");
|
||||
if (existsAsFile(nested)) return nested;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function resolveByPath(input: string): ResolvedApp | null {
|
||||
if (!existsSync(input)) return null;
|
||||
const st = statSync(input);
|
||||
if (st.isFile() && input.endsWith(".asar")) {
|
||||
return {
|
||||
appName: appNameFromPath(input),
|
||||
asarPath: input,
|
||||
unpackedDir: existsAsDir(input + ".unpacked")
|
||||
? input + ".unpacked"
|
||||
: null,
|
||||
installRoot: dirname(input),
|
||||
};
|
||||
}
|
||||
if (st.isDirectory()) {
|
||||
if (input.endsWith(".app")) {
|
||||
const asar = join(input, "Contents", "Resources", "app.asar");
|
||||
if (existsAsFile(asar)) {
|
||||
return {
|
||||
appName: appNameFromPath(input),
|
||||
asarPath: asar,
|
||||
unpackedDir: existsAsDir(asar + ".unpacked")
|
||||
? asar + ".unpacked"
|
||||
: null,
|
||||
installRoot: input,
|
||||
};
|
||||
}
|
||||
return null;
|
||||
}
|
||||
const asar = findAsarUnderDir(input);
|
||||
if (asar) {
|
||||
return {
|
||||
appName: appNameFromPath(input),
|
||||
asarPath: asar,
|
||||
unpackedDir: existsAsDir(asar + ".unpacked")
|
||||
? asar + ".unpacked"
|
||||
: null,
|
||||
installRoot: input,
|
||||
};
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function listAppCandidates(name: string): string[] {
|
||||
const lower = name.toLowerCase();
|
||||
const stripped = lower.endsWith(".app") ? lower.slice(0, -4) : lower;
|
||||
const matches: string[] = [];
|
||||
|
||||
if (process.platform === "darwin") {
|
||||
const roots = ["/Applications", join(homedir(), "Applications")];
|
||||
for (const root of roots) {
|
||||
if (!existsAsDir(root)) continue;
|
||||
for (const entry of readdirSync(root, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
const en = entry.name.toLowerCase();
|
||||
const enStripped = en.endsWith(".app") ? en.slice(0, -4) : en;
|
||||
if (
|
||||
en === lower ||
|
||||
en === `${stripped}.app` ||
|
||||
enStripped === stripped
|
||||
) {
|
||||
matches.push(join(root, entry.name));
|
||||
}
|
||||
}
|
||||
}
|
||||
} else if (process.platform === "win32") {
|
||||
const roots = [
|
||||
process.env.LOCALAPPDATA
|
||||
? join(process.env.LOCALAPPDATA, "Programs")
|
||||
: null,
|
||||
process.env.PROGRAMFILES || null,
|
||||
process.env["PROGRAMFILES(X86)"] || null,
|
||||
process.env.APPDATA || null,
|
||||
].filter((x): x is string => Boolean(x));
|
||||
for (const root of roots) {
|
||||
if (!existsAsDir(root)) continue;
|
||||
for (const entry of readdirSync(root, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
if (entry.name.toLowerCase() === stripped) {
|
||||
matches.push(join(root, entry.name));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return matches;
|
||||
}
|
||||
|
||||
function resolveApp(input: string): ResolvedApp {
|
||||
if (isAbsolute(input)) {
|
||||
const r = resolveByPath(input);
|
||||
if (r) return r;
|
||||
throw new Error(`path exists but no app.asar found at or under: ${input}`);
|
||||
}
|
||||
|
||||
if (process.platform !== "darwin" && process.platform !== "win32") {
|
||||
throw new Error(
|
||||
`platform ${process.platform} is not auto-supported. Pass --asar /path/to/app.asar to override.`
|
||||
);
|
||||
}
|
||||
|
||||
const candidates = listAppCandidates(input);
|
||||
if (candidates.length === 0) {
|
||||
throw new Error(
|
||||
`could not find an installed app matching "${input}". Try passing an absolute path or --asar.`
|
||||
);
|
||||
}
|
||||
|
||||
const resolved = candidates
|
||||
.map((c) => resolveByPath(c))
|
||||
.filter((r): r is ResolvedApp => r !== null);
|
||||
|
||||
if (resolved.length === 0) {
|
||||
throw new Error(
|
||||
`found app directories for "${input}" but none contained app.asar:\n ${candidates.join(
|
||||
"\n "
|
||||
)}`
|
||||
);
|
||||
}
|
||||
if (resolved.length > 1) {
|
||||
throw new Error(
|
||||
`multiple apps match "${input}". Re-run with an absolute path:\n ${resolved
|
||||
.map((r) => r.installRoot ?? r.asarPath)
|
||||
.join("\n ")}`
|
||||
);
|
||||
}
|
||||
return resolved[0];
|
||||
}
|
||||
|
||||
function downloadsDir(): string {
|
||||
return join(homedir(), "Downloads");
|
||||
}
|
||||
|
||||
function assertSafeOutputDir(outputDir: string, appName: string): void {
|
||||
const root =
|
||||
process.platform === "win32" ? outputDir.split(sep)[0] + sep : "/";
|
||||
const home = resolve(homedir());
|
||||
const cwd = resolve(process.cwd());
|
||||
const forbidden = [root, home, cwd];
|
||||
if (forbidden.includes(outputDir)) {
|
||||
throw new Error(`output directory is unsafe to write into: ${outputDir}`);
|
||||
}
|
||||
const base = basename(outputDir).toLowerCase();
|
||||
const tag = sanitizeAppName(appName).toLowerCase();
|
||||
if (!base.includes(tag.toLowerCase()) && !base.includes("electron-extract")) {
|
||||
throw new Error(
|
||||
`output directory basename must contain the app name (or "electron-extract"): ${outputDir}`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
function dirIsNonEmpty(p: string): boolean {
|
||||
try {
|
||||
return readdirSync(p).length > 0;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function runQuiet(
|
||||
cmd: string,
|
||||
args: string[]
|
||||
): { code: number; stderr: string; stdout: string } {
|
||||
const r = spawnSync(cmd, args, {
|
||||
stdio: ["ignore", "pipe", "pipe"],
|
||||
encoding: "utf8",
|
||||
});
|
||||
if (r.error) return { code: 1, stderr: r.error.message, stdout: "" };
|
||||
return {
|
||||
code: r.status ?? 1,
|
||||
stderr: r.stderr ?? "",
|
||||
stdout: r.stdout ?? "",
|
||||
};
|
||||
}
|
||||
|
||||
function runForwarded(cmd: string, args: string[]): Promise<number> {
|
||||
return new Promise((res) => {
|
||||
const proc = spawn(cmd, args, { stdio: ["ignore", "inherit", "inherit"] });
|
||||
proc.on("close", (code) => res(code ?? 1));
|
||||
proc.on("error", () => res(1));
|
||||
});
|
||||
}
|
||||
|
||||
async function extractAsar(
|
||||
asarPath: string,
|
||||
dest: string,
|
||||
json: boolean
|
||||
): Promise<void> {
|
||||
mkdirSync(dest, { recursive: true });
|
||||
const args = ["-y", "@electron/asar", "extract", asarPath, dest];
|
||||
const code = json
|
||||
? await new Promise<number>((res) => {
|
||||
const p = spawn("npx", args, { stdio: ["ignore", "ignore", "pipe"] });
|
||||
let err = "";
|
||||
p.stderr?.on("data", (d) => (err += d.toString()));
|
||||
p.on("close", (c) => {
|
||||
if ((c ?? 1) !== 0) process.stderr.write(err);
|
||||
res(c ?? 1);
|
||||
});
|
||||
p.on("error", (e) => {
|
||||
process.stderr.write(e.message);
|
||||
res(1);
|
||||
});
|
||||
})
|
||||
: await runForwarded("npx", args);
|
||||
if (code !== 0)
|
||||
throw new Error(`@electron/asar extract failed (code ${code})`);
|
||||
}
|
||||
|
||||
type FileKind = "js" | "css" | "other";
|
||||
|
||||
function classifyExt(p: string): FileKind {
|
||||
const e = extname(p).toLowerCase();
|
||||
if (e === ".js" || e === ".mjs" || e === ".cjs") return "js";
|
||||
if (e === ".css") return "css";
|
||||
return "other";
|
||||
}
|
||||
|
||||
function walk(
|
||||
root: string,
|
||||
out: { jsFiles: string[]; cssFiles: string[] },
|
||||
counts: Counts
|
||||
): void {
|
||||
for (const entry of readdirSync(root, { withFileTypes: true })) {
|
||||
if (entry.name === "node_modules") {
|
||||
counts.skippedNodeModules += 1;
|
||||
continue;
|
||||
}
|
||||
const full = join(root, entry.name);
|
||||
if (entry.isDirectory()) {
|
||||
walk(full, out, counts);
|
||||
} else if (entry.isFile()) {
|
||||
counts.extractedFiles += 1;
|
||||
const k = classifyExt(full);
|
||||
if (k === "js") out.jsFiles.push(full);
|
||||
else if (k === "css") out.cssFiles.push(full);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function countFiles(dir: string): number {
|
||||
let total = 0;
|
||||
if (!existsAsDir(dir)) return 0;
|
||||
const stack = [dir];
|
||||
while (stack.length) {
|
||||
const cur = stack.pop()!;
|
||||
for (const entry of readdirSync(cur, { withFileTypes: true })) {
|
||||
const full = join(cur, entry.name);
|
||||
if (entry.isDirectory()) stack.push(full);
|
||||
else if (entry.isFile()) total += 1;
|
||||
}
|
||||
}
|
||||
return total;
|
||||
}
|
||||
|
||||
function toPosix(p: string): string {
|
||||
return p.split(sep).join("/");
|
||||
}
|
||||
|
||||
function sourcePathExt(src: string): string {
|
||||
return extname(src.split(/[?#]/)[0]) || ".txt";
|
||||
}
|
||||
|
||||
function stripSourceDecorations(src: string): {
|
||||
path: string;
|
||||
hadProtocol: boolean;
|
||||
} {
|
||||
let s = src.trim();
|
||||
let hadProtocol = false;
|
||||
if (/^webpack:\/\/\/?/.test(s)) {
|
||||
hadProtocol = true;
|
||||
s = s.replace(/^webpack:\/\/\/?/, "");
|
||||
} else if (/^file:\/\//.test(s)) {
|
||||
hadProtocol = true;
|
||||
s = s.replace(/^file:\/\//, "");
|
||||
} else if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(s)) {
|
||||
hadProtocol = true;
|
||||
s = s.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "");
|
||||
}
|
||||
return { path: s.split(/[?#]/)[0].replace(/\\/g, "/"), hadProtocol };
|
||||
}
|
||||
|
||||
function isSafeRelativePath(p: string): boolean {
|
||||
return (
|
||||
p !== "" &&
|
||||
p !== "." &&
|
||||
p !== ".." &&
|
||||
!p.startsWith("../") &&
|
||||
!p.includes("/../")
|
||||
);
|
||||
}
|
||||
|
||||
function fallbackUnknownPath(src: string): string {
|
||||
const h = createHash("sha1").update(src).digest("hex").slice(0, 10);
|
||||
return posixPath.join("__unknown", `${h}${sourcePathExt(src)}`);
|
||||
}
|
||||
|
||||
function normalizeForOutputPath(p: string): string {
|
||||
let s = p.replace(/\\/g, "/").replace(/^[a-zA-Z]:\//, "");
|
||||
if (s.startsWith("/")) s = s.replace(/^\/+/, "");
|
||||
return posixPath.normalize(s);
|
||||
}
|
||||
|
||||
function sanitizeEscapedSourcePath(
|
||||
normalized: string,
|
||||
original: string
|
||||
): string {
|
||||
let s = normalized
|
||||
.replace(/\\/g, "/")
|
||||
.replace(/^[a-zA-Z]:\//, "")
|
||||
.replace(/^\/+/, "");
|
||||
while (s.startsWith("../")) s = s.slice(3);
|
||||
s = posixPath.normalize(s);
|
||||
if (!isSafeRelativePath(s)) return fallbackUnknownPath(original);
|
||||
return s;
|
||||
}
|
||||
|
||||
function shouldSkipRestoredSource(src: string): boolean {
|
||||
const s = src.replace(/\\/g, "/");
|
||||
return s.includes("node_modules/") || s.startsWith("webpack/runtime/");
|
||||
}
|
||||
|
||||
function sourceWithRoot(
|
||||
src: string,
|
||||
sourceRoot: unknown
|
||||
): { path: string; hadProtocol: boolean } {
|
||||
const source = stripSourceDecorations(src);
|
||||
if (typeof sourceRoot !== "string" || sourceRoot.trim() === "") return source;
|
||||
|
||||
const root = stripSourceDecorations(sourceRoot);
|
||||
const sourceIsAbsolute =
|
||||
source.path.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(source.path);
|
||||
if (!root.path || source.hadProtocol || sourceIsAbsolute) {
|
||||
return {
|
||||
path: source.path,
|
||||
hadProtocol: source.hadProtocol || root.hadProtocol,
|
||||
};
|
||||
}
|
||||
return {
|
||||
path: posixPath.join(root.path.replace(/\\/g, "/"), source.path),
|
||||
hadProtocol: source.hadProtocol || root.hadProtocol,
|
||||
};
|
||||
}
|
||||
|
||||
export function normalizeSourcePath(
|
||||
src: string,
|
||||
mapPath: string,
|
||||
extractedRoot: string,
|
||||
sourceRoot: unknown
|
||||
): string {
|
||||
const source = sourceWithRoot(src, sourceRoot);
|
||||
if (!source.path) return "";
|
||||
|
||||
if (
|
||||
!source.hadProtocol &&
|
||||
(source.path.startsWith("./") || source.path.startsWith("../"))
|
||||
) {
|
||||
const mapRelDir = toPosix(relative(extractedRoot, dirname(mapPath))) || ".";
|
||||
const relativeToExtracted = posixPath.normalize(
|
||||
posixPath.join(mapRelDir, source.path)
|
||||
);
|
||||
if (isSafeRelativePath(relativeToExtracted)) return relativeToExtracted;
|
||||
return sanitizeEscapedSourcePath(relativeToExtracted, src);
|
||||
}
|
||||
|
||||
const normalized = normalizeForOutputPath(source.path);
|
||||
if (isSafeRelativePath(normalized)) return normalized;
|
||||
return sanitizeEscapedSourcePath(normalized, src);
|
||||
}
|
||||
|
||||
function restoredTargetPath(
|
||||
restoredRoot: string,
|
||||
sourcePath: string
|
||||
): string | null {
|
||||
const target = resolve(restoredRoot, ...sourcePath.split("/"));
|
||||
const rel = relative(restoredRoot, target);
|
||||
if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
|
||||
return target;
|
||||
}
|
||||
|
||||
interface MapData {
|
||||
sources?: unknown;
|
||||
sourcesContent?: unknown;
|
||||
sourceRoot?: unknown;
|
||||
}
|
||||
|
||||
export function restoreFromMap(
|
||||
mapPath: string,
|
||||
extractedRoot: string,
|
||||
restoredRoot: string,
|
||||
warnings: string[]
|
||||
): number {
|
||||
let raw: string;
|
||||
try {
|
||||
raw = readFileSync(mapPath, "utf8");
|
||||
} catch (e: any) {
|
||||
warnings.push(`read ${mapPath}: ${e.message}`);
|
||||
return 0;
|
||||
}
|
||||
let data: MapData;
|
||||
try {
|
||||
data = JSON.parse(raw);
|
||||
} catch (e: any) {
|
||||
warnings.push(`parse ${mapPath}: ${e.message}`);
|
||||
return 0;
|
||||
}
|
||||
const sources = Array.isArray(data.sources)
|
||||
? (data.sources as unknown[])
|
||||
: null;
|
||||
const contents = Array.isArray(data.sourcesContent)
|
||||
? (data.sourcesContent as unknown[])
|
||||
: null;
|
||||
if (!sources || !contents) return 0;
|
||||
if (sources.length !== contents.length) {
|
||||
warnings.push(`${mapPath}: sources/sourcesContent length mismatch`);
|
||||
}
|
||||
const n = Math.min(sources.length, contents.length);
|
||||
let written = 0;
|
||||
for (let i = 0; i < n; i++) {
|
||||
const src = sources[i];
|
||||
const content = contents[i];
|
||||
if (typeof src !== "string" || typeof content !== "string") continue;
|
||||
if (shouldSkipRestoredSource(src)) continue;
|
||||
const restoredPath = normalizeSourcePath(
|
||||
src,
|
||||
mapPath,
|
||||
extractedRoot,
|
||||
data.sourceRoot
|
||||
);
|
||||
if (!restoredPath) continue;
|
||||
const target = restoredTargetPath(restoredRoot, restoredPath);
|
||||
if (!target) {
|
||||
warnings.push(`${mapPath}: unsafe restored path for source ${src}`);
|
||||
continue;
|
||||
}
|
||||
try {
|
||||
mkdirSync(dirname(target), { recursive: true });
|
||||
writeFileSync(target, content);
|
||||
written += 1;
|
||||
} catch (e: any) {
|
||||
warnings.push(`write ${target}: ${e.message}`);
|
||||
}
|
||||
}
|
||||
return written;
|
||||
}
|
||||
|
||||
function formatBatches(files: string[], json: boolean): Promise<void> {
|
||||
const maxArgLen = 50_000;
|
||||
let batch: string[] = [];
|
||||
let len = 0;
|
||||
const flush = async () => {
|
||||
if (batch.length === 0) return;
|
||||
const args = ["-y", "prettier", "--write", ...batch];
|
||||
const code = json
|
||||
? await new Promise<number>((res) => {
|
||||
const p = spawn("npx", args, { stdio: ["ignore", "ignore", "pipe"] });
|
||||
let err = "";
|
||||
p.stderr?.on("data", (d) => (err += d.toString()));
|
||||
p.on("close", (c) => {
|
||||
if ((c ?? 1) !== 0) process.stderr.write(err);
|
||||
res(c ?? 1);
|
||||
});
|
||||
p.on("error", (e) => {
|
||||
process.stderr.write(e.message);
|
||||
res(1);
|
||||
});
|
||||
})
|
||||
: await runForwarded("npx", args);
|
||||
if (code !== 0) {
|
||||
process.stderr.write(
|
||||
`prettier batch exited with code ${code} (continuing)\n`
|
||||
);
|
||||
}
|
||||
batch = [];
|
||||
len = 0;
|
||||
};
|
||||
|
||||
return (async () => {
|
||||
for (const f of files) {
|
||||
batch.push(f);
|
||||
len += f.length + 1;
|
||||
if (len >= maxArgLen) await flush();
|
||||
}
|
||||
await flush();
|
||||
})();
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const started = Date.now();
|
||||
let opts: Options;
|
||||
try {
|
||||
opts = parseArgs(process.argv.slice(2));
|
||||
} catch (e: any) {
|
||||
process.stderr.write(`Error: ${e.message}\n`);
|
||||
process.exit(2);
|
||||
}
|
||||
|
||||
let resolved: ResolvedApp;
|
||||
try {
|
||||
if (opts.asar) {
|
||||
const r = resolveByPath(opts.asar);
|
||||
if (!r) throw new Error(`--asar path not found: ${opts.asar}`);
|
||||
const appName =
|
||||
opts.app && !isAbsolute(opts.app)
|
||||
? opts.app
|
||||
: appNameFromPath(opts.asar);
|
||||
resolved = { ...r, appName };
|
||||
} else {
|
||||
resolved = resolveApp(opts.app);
|
||||
}
|
||||
} catch (e: any) {
|
||||
fail(e.message, opts.json);
|
||||
}
|
||||
|
||||
const outputDir = resolve(
|
||||
opts.output ??
|
||||
join(
|
||||
downloadsDir(),
|
||||
`${sanitizeAppName(resolved.appName)}-electron-extract`
|
||||
)
|
||||
);
|
||||
try {
|
||||
assertSafeOutputDir(outputDir, resolved.appName);
|
||||
} catch (e: any) {
|
||||
fail(e.message, opts.json);
|
||||
}
|
||||
|
||||
const extractedDir = join(outputDir, "extracted");
|
||||
const unpackedOut = join(outputDir, "extracted.unpacked");
|
||||
const restoredDir = join(outputDir, "restored");
|
||||
|
||||
if (opts.dryRun) {
|
||||
const summary = {
|
||||
status: "dry-run",
|
||||
appName: resolved.appName,
|
||||
asar: resolved.asarPath,
|
||||
unpacked: resolved.unpackedDir,
|
||||
output: outputDir,
|
||||
extracted: extractedDir,
|
||||
extractedUnpacked: opts.noUnpacked
|
||||
? null
|
||||
: resolved.unpackedDir
|
||||
? unpackedOut
|
||||
: null,
|
||||
restored: opts.skipRestore ? null : restoredDir,
|
||||
};
|
||||
if (opts.json) {
|
||||
process.stdout.write(JSON.stringify(summary) + "\n");
|
||||
} else {
|
||||
process.stdout.write(
|
||||
`[dry-run] App: ${resolved.appName}\n` +
|
||||
`[dry-run] Asar: ${resolved.asarPath}\n` +
|
||||
`[dry-run] Unpacked: ${resolved.unpackedDir ?? "(none)"}\n` +
|
||||
`[dry-run] Output: ${outputDir}\n` +
|
||||
`[dry-run] extracted: ${extractedDir}\n` +
|
||||
`[dry-run] unpacked: ${
|
||||
opts.noUnpacked
|
||||
? "(skipped)"
|
||||
: resolved.unpackedDir
|
||||
? unpackedOut
|
||||
: "(none)"
|
||||
}\n` +
|
||||
`[dry-run] restored: ${
|
||||
opts.skipRestore ? "(skipped)" : restoredDir
|
||||
}\n`
|
||||
);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
if (existsSync(outputDir) && dirIsNonEmpty(outputDir) && !opts.force) {
|
||||
fail(
|
||||
`output directory exists and is not empty: ${outputDir}\n Pass --force to allow writing into it, or choose another --output.`,
|
||||
opts.json
|
||||
);
|
||||
}
|
||||
mkdirSync(outputDir, { recursive: true });
|
||||
|
||||
if (!opts.json) {
|
||||
process.stdout.write(`App: ${resolved.appName}\n`);
|
||||
process.stdout.write(`Asar: ${resolved.asarPath}\n`);
|
||||
process.stdout.write(`Output: ${outputDir}\n`);
|
||||
process.stdout.write(`Extracting asar...\n`);
|
||||
}
|
||||
|
||||
try {
|
||||
await extractAsar(resolved.asarPath, extractedDir, opts.json);
|
||||
} catch (e: any) {
|
||||
fail(e.message, opts.json);
|
||||
}
|
||||
|
||||
const counts: Counts = {
|
||||
extractedFiles: 0,
|
||||
restoredFiles: 0,
|
||||
formattedFiles: 0,
|
||||
skippedNodeModules: 0,
|
||||
unpackedFiles: 0,
|
||||
};
|
||||
const warnings: string[] = [];
|
||||
|
||||
let unpackedFinal: string | null = null;
|
||||
if (
|
||||
!opts.noUnpacked &&
|
||||
resolved.unpackedDir &&
|
||||
existsAsDir(resolved.unpackedDir)
|
||||
) {
|
||||
if (!opts.json) process.stdout.write(`Copying app.asar.unpacked...\n`);
|
||||
try {
|
||||
cpSync(resolved.unpackedDir, unpackedOut, { recursive: true });
|
||||
counts.unpackedFiles = countFiles(unpackedOut);
|
||||
unpackedFinal = unpackedOut;
|
||||
} catch (e: any) {
|
||||
warnings.push(`copy unpacked: ${e.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
const walked = { jsFiles: [] as string[], cssFiles: [] as string[] };
|
||||
walk(extractedDir, walked, counts);
|
||||
|
||||
const toFormat: string[] = [];
|
||||
const restoredMapFiles = new Set<string>();
|
||||
const skipFormatSet = new Set<string>();
|
||||
|
||||
if (!opts.skipRestore) {
|
||||
for (const js of walked.jsFiles) {
|
||||
const mapPath = js + ".map";
|
||||
if (!existsAsFile(mapPath)) continue;
|
||||
const w = restoreFromMap(mapPath, extractedDir, restoredDir, warnings);
|
||||
if (w > 0) {
|
||||
counts.restoredFiles += w;
|
||||
restoredMapFiles.add(mapPath);
|
||||
skipFormatSet.add(js);
|
||||
const license = js + ".LICENSE.txt";
|
||||
if (existsAsFile(license)) skipFormatSet.add(license);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (!opts.skipFormat) {
|
||||
for (const js of walked.jsFiles)
|
||||
if (!skipFormatSet.has(js)) toFormat.push(js);
|
||||
for (const css of walked.cssFiles) toFormat.push(css);
|
||||
if (toFormat.length > 0) {
|
||||
if (!opts.json)
|
||||
process.stdout.write(
|
||||
`Formatting ${toFormat.length} file(s) with prettier...\n`
|
||||
);
|
||||
await formatBatches(toFormat, opts.json);
|
||||
counts.formattedFiles = toFormat.length;
|
||||
}
|
||||
}
|
||||
|
||||
const report: Report = {
|
||||
appName: resolved.appName,
|
||||
source: {
|
||||
input: opts.app,
|
||||
asar: resolved.asarPath,
|
||||
platform: process.platform,
|
||||
installRoot: resolved.installRoot,
|
||||
},
|
||||
output: {
|
||||
root: outputDir,
|
||||
extracted: extractedDir,
|
||||
unpacked: unpackedFinal,
|
||||
restored: counts.restoredFiles > 0 ? restoredDir : null,
|
||||
},
|
||||
counts,
|
||||
warnings,
|
||||
durationMs: Date.now() - started,
|
||||
};
|
||||
|
||||
try {
|
||||
writeFileSync(
|
||||
join(outputDir, "extract-report.json"),
|
||||
JSON.stringify(report, null, 2)
|
||||
);
|
||||
} catch (e: any) {
|
||||
warnings.push(`write extract-report.json: ${e.message}`);
|
||||
}
|
||||
|
||||
if (opts.json) {
|
||||
process.stdout.write(JSON.stringify({ status: "ok", ...report }) + "\n");
|
||||
} else {
|
||||
process.stdout.write(
|
||||
`\nDone in ${(report.durationMs / 1000).toFixed(1)}s\n` +
|
||||
` Extracted: ${counts.extractedFiles} file(s) into ${extractedDir}\n` +
|
||||
(counts.unpackedFiles > 0
|
||||
? ` Unpacked copied: ${counts.unpackedFiles} file(s) into ${unpackedOut}\n`
|
||||
: "") +
|
||||
` Restored: ${counts.restoredFiles} file(s)` +
|
||||
(counts.restoredFiles > 0 ? ` into ${restoredDir}\n` : `\n`) +
|
||||
` Formatted: ${counts.formattedFiles} file(s)\n` +
|
||||
` node_modules dirs skipped: ${counts.skippedNodeModules}\n` +
|
||||
(warnings.length > 0
|
||||
? ` Warnings: ${warnings.length} (see extract-report.json)\n`
|
||||
: "")
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
function isDirectRun(): boolean {
|
||||
if (import.meta.main) return true;
|
||||
const scriptPath = process.argv[1];
|
||||
return Boolean(
|
||||
scriptPath && pathToFileURL(resolve(scriptPath)).href === import.meta.url
|
||||
);
|
||||
}
|
||||
|
||||
if (isDirectRun()) {
|
||||
main().catch((e) => {
|
||||
process.stderr.write(`Unexpected error: ${e?.stack ?? e}\n`);
|
||||
process.exit(1);
|
||||
});
|
||||
}
|
||||
@@ -51,6 +51,16 @@ Check these paths in order; first hit wins:
|
||||
|
||||
Minimum working examples — see `references/usage-examples.md` for the full set including per-provider invocations and batch mode.
|
||||
|
||||
### Identity-preserving reference prompts
|
||||
|
||||
When the user wants a real person/character/object preserved from reference images, do **not** replace the reference with a long generic description. Prefer short, hard identity-preservation language:
|
||||
|
||||
- "Use the person/object in the reference image(s) as the same identity. Do not redesign it or create a similar-looking new subject."
|
||||
- "Only change scene, clothing, pose, lighting, rendering style, and composition. Keep the face/proportions/hair/key accessories/overall identity from the references."
|
||||
- If using multiple references, state that they are the same subject and should jointly define identity.
|
||||
|
||||
Pitfall: long descriptions like "young East Asian woman, oval face, clear eyes..." can cause the model to synthesize a new person matching the description instead of preserving the referenced person.
|
||||
|
||||
```bash
|
||||
# Basic
|
||||
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image cat.png
|
||||
@@ -71,6 +81,16 @@ ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider d
|
||||
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4
|
||||
```
|
||||
|
||||
## Reference-Image Identity Preservation
|
||||
|
||||
When the user wants a person/object preserved from reference images:
|
||||
|
||||
- Prefer a small curated set of existing source references (usually 2–4) over many images; large multi-megabyte refs can destabilize streaming providers.
|
||||
- Make the prompt say the references are the same subject and the output must use that identity. Avoid long generic facial-feature descriptions that can cause the model to synthesize a new similar-looking person.
|
||||
- Do not use newly generated outputs as references unless the user explicitly asks; generated refs compound drift.
|
||||
- If results become too polished or influencer-like, reduce stylized refs and add explicit anti-beautification constraints (no face slimming, eye enlargement, heavy makeup, commercial travel shoot, over-smoothing).
|
||||
- If the subject should look younger/older, preserve the face and express age through clothing, posture, scene, and styling; do not ask the model to change facial identity.
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description |
|
||||
@@ -118,6 +138,18 @@ ${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4
|
||||
|
||||
**Load priority**: CLI args > EXTEND.md > env vars > `<cwd>/.baoyu-skills/.env` > `~/.baoyu-skills/.env`
|
||||
|
||||
### Codex/ChatGPT OAuth is not an OpenAI API key
|
||||
|
||||
`--provider openai` uses the standard OpenAI Images API and requires `OPENAI_API_KEY`. A Codex or ChatGPT desktop login is a different entitlement and is not a drop-in replacement for `OPENAI_API_KEY`; do not paste a Codex OAuth token into `OPENAI_API_KEY` or only set `OPENAI_BASE_URL` to a Codex backend.
|
||||
|
||||
If the user wants to use their Codex subscription / GPT Image 2 entitlement without an OpenAI API key, route through a Codex-native backend instead of this skill's `openai` provider:
|
||||
|
||||
- In Codex runtime: use the native `imagegen` skill/tool.
|
||||
- In non-Codex runtimes with `codex` CLI installed and logged in: use the repo-level `scripts/codex-imagegen.sh` wrapper when the calling skill supports it. Resolve it from the plugin/repo root and pass absolute prompt/output/reference paths.
|
||||
- In Hermes runtimes with a native `image_generate` tool: use that tool as a fallback, and state whether reference images were passed directly or reconstructed from extracted traits.
|
||||
|
||||
Do not modify the existing `openai` provider to silently consume Codex OAuth. If first-class Codex OAuth support is added, implement it as a distinct provider (for example `openai-codex`) with its own auth, route, request shape, docs, and tests. See `references/codex-oauth-vs-openai-api-key.md`.
|
||||
|
||||
## Model Resolution
|
||||
|
||||
Priority (highest → lowest) applies to every provider:
|
||||
@@ -211,11 +243,17 @@ Rule of thumb: once prompt files are saved and the task is "generate all of thes
|
||||
- Invalid aspect ratio → warning, proceed with default
|
||||
- Reference images with unsupported provider/model → error with fix hint
|
||||
|
||||
### Codex image2 fallback
|
||||
|
||||
If `--provider openai` fails because `OPENAI_API_KEY` is missing but the current runtime has a native image-generation backend or the repo-level `codex-imagegen` wrapper is available, use that path rather than leaving the user waiting. Be explicit about whether the fallback is true reference-image generation or only a text-prompt reconstruction from extracted visual traits. See `references/codex-image2-fallback.md`.
|
||||
|
||||
## References
|
||||
|
||||
| File | Content |
|
||||
|------|---------|
|
||||
| `references/usage-examples.md` | Extended CLI examples across providers and batch mode |
|
||||
| `references/codex-oauth-vs-openai-api-key.md` | Why Codex/ChatGPT OAuth image2 entitlement is not usable through the standard OpenAI API-key provider |
|
||||
| `references/codex-image2-fallback.md` | Practical fallback behavior when OpenAI API credentials are absent but Codex/native image generation is available |
|
||||
| `references/providers/dashscope.md` | DashScope families, sizes, limits |
|
||||
| `references/providers/zai.md` | Z.AI GLM-image / cogview-4 |
|
||||
| `references/providers/minimax.md` | MiniMax image-01 + subject reference |
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
name: codex-image2-fallback
|
||||
description: Fallback behavior when OpenAI API credentials are absent but Codex/native image generation is available
|
||||
---
|
||||
|
||||
# Codex Image2 Fallback
|
||||
|
||||
The `openai` provider can fail with:
|
||||
|
||||
```text
|
||||
OPENAI_API_KEY is required. Codex/ChatGPT desktop login does not automatically grant OpenAI Images API access to this script.
|
||||
```
|
||||
|
||||
This is expected. The `openai` provider uses the public OpenAI Images API and needs `OPENAI_API_KEY`. Codex / ChatGPT image2 entitlement is a separate runtime-native path.
|
||||
|
||||
## Practical fallback pattern
|
||||
|
||||
1. Try this skill when provider credentials are available.
|
||||
2. If it fails only because `OPENAI_API_KEY` is missing, do not leave the user waiting.
|
||||
3. Prefer a Codex/native raster backend in this order:
|
||||
- Codex runtime native `imagegen` skill/tool, if available.
|
||||
- Repo-level `scripts/codex-imagegen.sh`, if `codex` CLI is installed/logged in and the calling skill supports the wrapper.
|
||||
- Hermes native `image_generate`, if available.
|
||||
4. Be transparent about reference-image behavior:
|
||||
- If the fallback backend accepts references, pass the reference images.
|
||||
- If it does not, derive a concise identity-preserving prompt from the references and state that it is a text-description fallback, not strict reference-image editing.
|
||||
5. Return the generated media path or structured backend error promptly.
|
||||
@@ -0,0 +1,20 @@
|
||||
# Codex OAuth vs OpenAI API key
|
||||
|
||||
This deprecated skill keeps cross-cutting image-generation guidance in sync with `baoyu-imagine`.
|
||||
|
||||
The `openai` provider uses the standard OpenAI Images API and requires `OPENAI_API_KEY`. It calls OpenAI-compatible image endpoints such as `/images/generations` and `/images/edits`.
|
||||
|
||||
Codex / ChatGPT login is different. Codex image generation is driven by Codex OAuth and the Codex runtime's `image_gen` capability, not by the public OpenAI Images API key path. A Codex OAuth token is not a drop-in replacement for `OPENAI_API_KEY`, and setting `OPENAI_BASE_URL` to a Codex backend will not make the existing `openai` provider work because the auth, route, and payload shape differ.
|
||||
|
||||
## What to use instead
|
||||
|
||||
- If running inside Codex and the native `imagegen` skill/tool is available, use it directly.
|
||||
- If running outside Codex but the `codex` CLI is installed and logged in, use the repo-level `scripts/codex-imagegen.sh` wrapper when the calling skill supports it.
|
||||
- If running inside Hermes and a native `image_generate` tool is available, use that as a runtime-native fallback. Be explicit about whether reference images are passed directly or only reconstructed from extracted traits.
|
||||
- If first-class Codex OAuth support is added, add a distinct provider such as `openai-codex` rather than modifying the existing `openai` provider.
|
||||
|
||||
## Reference-image prompting note
|
||||
|
||||
When using actual reference images for identity preservation, avoid long generic descriptions of the subject. Prefer direct wording:
|
||||
|
||||
> Use the person/object in the reference image(s) as the same identity. Do not redesign it or create a similar-looking new subject. Only change scene, clothing, pose, lighting, rendering style, and composition.
|
||||
@@ -52,6 +52,16 @@ Legacy compatibility: if `.baoyu-skills/baoyu-image-gen/EXTEND.md` exists and th
|
||||
|
||||
Minimum working examples — see `references/usage-examples.md` for the full set including per-provider invocations and batch mode.
|
||||
|
||||
### Identity-preserving reference prompts
|
||||
|
||||
When the user wants a real person/character/object preserved from reference images, do **not** replace the reference with a long generic description. Prefer short, hard identity-preservation language:
|
||||
|
||||
- "Use the person/object in the reference image(s) as the same identity. Do not redesign it or create a similar-looking new subject."
|
||||
- "Only change scene, clothing, pose, lighting, rendering style, and composition. Keep the face/proportions/hair/key accessories/overall identity from the references."
|
||||
- If using multiple references, state that they are the same subject and should jointly define identity.
|
||||
|
||||
Pitfall: long descriptions like "young East Asian woman, oval face, clear eyes..." can cause the model to synthesize a new person matching the description instead of preserving the referenced person.
|
||||
|
||||
```bash
|
||||
# Basic
|
||||
${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image cat.png
|
||||
@@ -75,6 +85,16 @@ ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider o
|
||||
${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4
|
||||
```
|
||||
|
||||
## Reference-Image Identity Preservation
|
||||
|
||||
When the user wants a person/object preserved from reference images:
|
||||
|
||||
- Prefer a small curated set of existing source references (usually 2–4) over many images; large multi-megabyte refs can destabilize streaming providers.
|
||||
- Make the prompt say the references are the same subject and the output must use that identity. Avoid long generic facial-feature descriptions that can cause the model to synthesize a new similar-looking person.
|
||||
- Do not use newly generated outputs as references unless the user explicitly asks; generated refs compound drift.
|
||||
- If results become too polished or influencer-like, reduce stylized refs and add explicit anti-beautification constraints (no face slimming, eye enlargement, heavy makeup, commercial travel shoot, over-smoothing).
|
||||
- If the subject should look younger/older, preserve the face and express age through clothing, posture, scene, and styling; do not ask the model to change facial identity.
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description |
|
||||
@@ -122,6 +142,18 @@ ${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4
|
||||
|
||||
**Load priority**: CLI args > EXTEND.md > env vars > `<cwd>/.baoyu-skills/.env` > `~/.baoyu-skills/.env`
|
||||
|
||||
### Codex/ChatGPT OAuth is not an OpenAI API key
|
||||
|
||||
`--provider openai --model gpt-image-2` uses the standard OpenAI Images API (`/v1/images/generations` or `/v1/images/edits`) and requires `OPENAI_API_KEY`. A Codex or ChatGPT desktop login is a different entitlement and is not a drop-in replacement for `OPENAI_API_KEY`; do not paste a Codex OAuth token into `OPENAI_API_KEY` or only set `OPENAI_BASE_URL` to a Codex backend.
|
||||
|
||||
If the user wants to use their Codex subscription / GPT Image 2 entitlement without an OpenAI API key, route through a Codex-native backend instead of this skill's `openai` provider:
|
||||
|
||||
- In Codex runtime: use the native `imagegen` skill/tool.
|
||||
- In non-Codex runtimes with `codex` CLI installed and logged in: use the repo-level `scripts/codex-imagegen.sh` wrapper when the calling skill supports it (for example `baoyu-cover-image`). Resolve it from the plugin/repo root and pass absolute prompt/output/reference paths.
|
||||
- In Hermes runtimes with a native `image_generate` tool: use that tool as a fallback, and state whether reference images were passed directly or reconstructed from extracted traits.
|
||||
|
||||
Do not modify the existing `openai` provider to silently consume Codex OAuth. If first-class Codex OAuth support is added to `baoyu-imagine`, implement it as a distinct provider (for example `openai-codex`) with its own auth, route, request shape, docs, and tests. See `references/codex-oauth-vs-openai-api-key.md`.
|
||||
|
||||
## Model Resolution
|
||||
|
||||
Priority (highest → lowest) applies to every provider:
|
||||
@@ -219,11 +251,17 @@ Rule of thumb: once prompt files are saved and the task is "generate all of thes
|
||||
- Invalid aspect ratio → warning, proceed with default
|
||||
- Reference images with unsupported provider/model → error with fix hint
|
||||
|
||||
### Codex image2 fallback
|
||||
|
||||
If `--provider openai --model gpt-image-2` fails because `OPENAI_API_KEY` is missing but the current runtime has a native image-generation backend or the repo-level `codex-imagegen` wrapper is available, use that path rather than leaving the user waiting. Be explicit about whether the fallback is true reference-image generation or only a text-prompt reconstruction from extracted visual traits. See `references/codex-image2-fallback.md`.
|
||||
|
||||
## References
|
||||
|
||||
| File | Content |
|
||||
|------|---------|
|
||||
| `references/usage-examples.md` | Extended CLI examples across providers and batch mode |
|
||||
| `references/codex-oauth-vs-openai-api-key.md` | Why Codex/ChatGPT OAuth image2 entitlement is not usable through baoyu-imagine's standard OpenAI API-key provider |
|
||||
| `references/codex-image2-fallback.md` | Practical fallback behavior when OpenAI API credentials are absent but Codex/native image generation is available |
|
||||
| `references/providers/dashscope.md` | DashScope families, sizes, limits |
|
||||
| `references/providers/zai.md` | Z.AI GLM-image / cogview-4 |
|
||||
| `references/providers/minimax.md` | MiniMax image-01 + subject reference |
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
name: codex-image2-fallback
|
||||
description: Fallback behavior when baoyu-imagine lacks OpenAI API credentials but Codex/native image generation is available
|
||||
---
|
||||
|
||||
# Codex Image2 Fallback
|
||||
|
||||
When using `baoyu-imagine` with `--provider openai --model gpt-image-2`, the CLI can fail with:
|
||||
|
||||
```text
|
||||
OPENAI_API_KEY is required. Codex/ChatGPT desktop login does not automatically grant OpenAI Images API access to this script.
|
||||
```
|
||||
|
||||
This is expected. The `openai` provider uses the public OpenAI Images API and needs `OPENAI_API_KEY`. Codex / ChatGPT image2 entitlement is a separate runtime-native path.
|
||||
|
||||
## Practical fallback pattern
|
||||
|
||||
1. Try `baoyu-imagine` when provider credentials are available.
|
||||
2. If it fails only because `OPENAI_API_KEY` is missing, do not leave the user waiting.
|
||||
3. Prefer a Codex/native raster backend in this order:
|
||||
- Codex runtime native `imagegen` skill/tool, if available.
|
||||
- Repo-level `scripts/codex-imagegen.sh`, if `codex` CLI is installed/logged in and the calling skill supports the wrapper.
|
||||
- Hermes native `image_generate`, if available.
|
||||
4. Be transparent about reference-image behavior:
|
||||
- If the fallback backend accepts references, pass the reference images.
|
||||
- If it does not, derive a concise identity-preserving prompt from the references and state that it is a text-description fallback, not strict reference-image editing.
|
||||
5. Return the generated media path or structured backend error promptly.
|
||||
|
||||
## User-facing wording
|
||||
|
||||
Use concise wording such as:
|
||||
|
||||
> The OpenAI API path needs `OPENAI_API_KEY`; Codex login is a separate image2 backend. I used the available Codex/native image backend instead. Reference images were [passed directly / reconstructed from visual traits].
|
||||
|
||||
Avoid implying that `baoyu-imagine --provider openai` can use Codex OAuth without a dedicated provider implementation.
|
||||
@@ -0,0 +1,18 @@
|
||||
# Codex OAuth vs OpenAI API key for baoyu-imagine
|
||||
|
||||
`baoyu-imagine --provider openai` uses the standard OpenAI Images API and requires `OPENAI_API_KEY`. It calls OpenAI-compatible image endpoints such as `/images/generations` and `/images/edits`.
|
||||
|
||||
Codex / ChatGPT login is different. Codex image generation is driven by Codex OAuth and the Codex runtime's `image_gen` capability, not by the public OpenAI Images API key path. A Codex OAuth token is not a drop-in replacement for `OPENAI_API_KEY`, and setting `OPENAI_BASE_URL` to a Codex backend will not make baoyu-imagine's existing `openai` provider work because the auth, route, and payload shape differ.
|
||||
|
||||
## What to use instead
|
||||
|
||||
- If running inside Codex and the native `imagegen` skill/tool is available, use it directly.
|
||||
- If running outside Codex but the `codex` CLI is installed and logged in, use the repo-level `scripts/codex-imagegen.sh` wrapper when the calling skill supports it. The wrapper invokes `codex exec` and the Codex `image_gen` tool; no `OPENAI_API_KEY` is required.
|
||||
- If running inside Hermes and a native `image_generate` tool is available, use that as a runtime-native fallback. Be explicit about whether reference images are passed directly or only reconstructed from extracted traits.
|
||||
- If the user wants `baoyu-imagine` itself to support Codex OAuth, add a distinct provider such as `openai-codex` rather than modifying the existing `openai` provider.
|
||||
|
||||
## Reference-image prompting note
|
||||
|
||||
When using actual reference images for identity preservation, avoid long generic descriptions of the subject. Long descriptions can cause the model to synthesize a new similar-looking person/object. Prefer direct wording:
|
||||
|
||||
> Use the person/object in the reference image(s) as the same identity. Do not redesign it or create a similar-looking new subject. Only change scene, clothing, pose, lighting, rendering style, and composition.
|
||||
Reference in New Issue
Block a user