@lovehlmmm/primekit 1.0.0

package/skills/journal/references/zernio-integration.md

@@ -0,0 +1,143 @@
+# Zernio integration
+
+`scripts/post-social.cjs` dispatches journal posts through
+[`mrgoonie/zernio-cli`](https://github.com/mrgoonie/zernio-cli) (a
+user-linked fork of `zernio-dev/zernio-cli`), invoked via `npx` — no global
+install required.
+
+## Pinned version
+
+**Current pin:** `github:mrgoonie/zernio-cli#946ee2aa1f7e9c5abf2ccf5d30ae730ce40e621e`
+
+Every emitted `npx ... github:mrgoonie/zernio-cli...` command pins this exact
+commit SHA. **Never invoke `github:mrgoonie/zernio-cli` without a `#<sha>`.**
+An unpinned `HEAD` reference combined with `ZERNIO_API_KEY` in the
+environment is a supply-chain / account-takeover risk: a malicious or
+compromised push to the fork's default branch would run with your API key on
+your next invocation.
+
+### Bump procedure
+
+1. Review the new commits on `mrgoonie/zernio-cli` (diff against the
+   currently pinned SHA) before bumping.
+2. Update the `ZERNIO_SHA` constant in `scripts/post-social.cjs`.
+3. Update the "Current pin" line above in this file.
+4. Re-run `scripts/post-social.test.cjs` and a manual `--dry-run` smoke test.
+5. Ship as its own small PR — never bundle a version bump with unrelated changes.
+
+## Install
+
+No install step is required for normal use — `post-social.cjs` invokes the
+pinned commit via `npx -y`. For faster local iteration you may install the
+pinned fork globally instead (do NOT install the upstream `zernio-cli` from
+npm — this skill targets the `mrgoonie` fork at the pinned commit):
+
+```bash
+npm install -g github:mrgoonie/zernio-cli#946ee2aa1f7e9c5abf2ccf5d30ae730ce40e621e
+```
+
+## Auth
+
+Two options, resolved by zernio-cli itself:
+
+```bash
+# Interactive browser login (writes ~/.zernio/config.json)
+npx -y github:mrgoonie/zernio-cli#946ee2aa1f7e9c5abf2ccf5d30ae730ce40e621e auth:login
+
+# Headless / CI — API key via env
+export ZERNIO_API_KEY="sk_your-api-key"
+```
+
+`post-social.cjs` requires `ZERNIO_API_KEY` to be resolvable through the
+env cascade (`references/env-cascade.md`) before it will do anything —
+including `--dry-run` — and exits 1 with a clear message if it isn't set.
+
+The published zernio-cli binary does **not** auto-load a project `.env`
+file. `post-social.cjs` resolves secrets itself via `scripts/env-loader.cjs`
+and passes the resolved values into the child process's environment, along
+with `ZERNIO_CLI_LOAD_ENV=1` so zernio-cli's own env loading (if any) stays
+consistent.
+
+Add `.primekit/.env` to your project's `.gitignore` — never commit
+`ZERNIO_API_KEY`.
+
+## `posts:create` flags used by this skill
+
+| Flag | Used for |
+|------|----------|
+| `--text <body>` | The post body (already localized/styled by the calling agent — see Layering below). |
+| `--accounts <accountId>` | The channel's `account_id` from `.primekit/journal.yaml`. |
+| `--threadJson '["post1","post2",...]'` | Native thread mode for `platform: x` / `platform: threads` when the body needed splitting — see `references/channels-config.md` and `scripts/split-thread.cjs`. |
+| `--media <url>` (repeatable) | The public URL(s) returned by `zernio media:upload`, for `--image`/`--image-ai`/`--video`/`--video-ai` — see `references/media-flags.md`. |
+
+Full upstream flag set (for reference; not all used by this skill yet):
+`--scheduledAt`, `--quoteTweetId`, `--replyToTweetId`, `--replySettings`,
+`--threadFile`, `--platformSpecificData`, `--debug-safe`. See the upstream
+README for the authoritative list — flags can change between pins, which is
+exactly why every invocation is SHA-pinned.
+
+## `--threadJson` shape
+
+A JSON array of strings, one per post in the thread, already split and
+numbered by `scripts/split-thread.cjs`:
+
+```json
+["First post of the thread (1/3)", "Second post (2/3)", "Third post (3/3)"]
+```
+
+If zernio-cli ever renames or removes `--threadJson`, `post-social.cjs`'s
+fallback path is N sequential `posts:create` calls chained with
+`--replyToTweetId` (not yet implemented — the pinned SHA above is verified
+to support `--threadJson`).
+
+## `media:upload`
+
+`--image` / `--image-ai` / `--video` / `--video-ai` resolve local file(s)
+(see `references/media-flags.md`), which are then uploaded once via `zernio
+media:upload <file> --json` → the returned public URL is captured and passed
+via `--media <url>` (repeatable) on every targeted channel's `posts:create`
+call. If a specific channel's `posts:create` rejects the attached media
+downstream, that channel falls back to a text-only post automatically
+(`MEDIA_UNSUPPORTED` in the summary) — see `references/media-flags.md` for
+the full contract, cache-key shape, and platform size-limit table.
+
+## Rate limits and retries
+
+`post-social.cjs` detects a rate-limited response (exit code non-zero plus a
+`429` / "rate limit" marker in stdout/stderr), honors a `Retry-After`
+duration if present (default 1s, capped at 30s), and retries **once**. If
+the retry also fails, the channel is marked `RATE_LIMITED` in the summary
+and other channels continue unaffected.
+
+## Layering — no translation in scripts
+
+Per the plan's locked layering decision: `post-social.cjs` never translates
+or tone-transforms text. It accepts a body per channel — either from
+`--channel-bodies <path-to-json>` (a `{channel_id: body}` map the calling
+agent already localized/styled) or a single fallback body applied to every
+channel. The agent (LLM) is responsible for producing per-channel bodies
+using `references/writing-styles-resolver.md` guidance; the script only
+splits (for thread platforms), counts, and dispatches.
+
+## Retry contract
+
+The `--json` summary is the retry contract:
+
+```json
+{
+  "results": [
+    { "channelId": "x_main", "status": "SUCCESS", "url": "https://x.com/...", "argv": [...], "error": null },
+    { "channelId": "li_main", "status": "RATE_LIMITED", "url": null, "argv": [...], "error": "..." }
+  ],
+  "dryRun": false,
+  "statePath": "/path/to/plans/reports/journal-media-2026-08-07-my-entry/posted.json"
+}
+```
+
+Successful posts are recorded in `posted.json` next to the journal
+(`plans/reports/journal-media-<journal-file-slug>/posted.json`). A bare
+re-run of `post-social.cjs` against the same `--journal-file` automatically
+skips (`SKIPPED_ALREADY_POSTED`) any channel already marked `SUCCESS` there —
+it will not double-post. To retry only the channels that failed, pass
+`--channels <failed-id-1>,<failed-id-2>` explicitly, or simply re-run without
+`--channels`: already-succeeded channels are always skipped regardless.

package/skills/journal/scripts/env-loader.cjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Environment Variable Loader for the ak-journal skill.
+ *
+ * Vendored (not shared) — this skill installs standalone and cannot import
+ * across the source `kits/` tree once installed, so it carries its own copy
+ * of the env-cascade loader. Mirrors the ak-seo skill's env-loader.cjs
+ * pattern (see references/env-cascade.md for rationale).
+ *
+ * Cascade (highest → lowest priority):
+ *   1. process.env                  (already-set values always win)
+ *   2. <cwd>/.agentkit/.env         (project-scoped, preferred)
+ *   3. ~/.agentkit/.env             (user-scoped, preferred)
+ *   4. <cwd>/.claude/.env           (legacy project-scoped)
+ *   5. ~/.claude/.env               (legacy user-scoped)
+ *
+ * Usage:
+ *   const { loadEnv, parseEnvContent } = require('./env-loader.cjs');
+ *   const env = loadEnv(process.cwd());
+ *   const apiKey = env.ZERNIO_API_KEY;
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Parse .env-formatted text into a plain key/value object.
+ * Supports: comments (#...), blank lines, unquoted values, single- and
+ * double-quoted values, `KEY=value=with=equals`, and `\n`/`\t` escapes
+ * inside double-quoted values only (matches ak-seo's env-loader.cjs).
+ *
+ * @param {string} content
+ * @returns {Record<string, string>}
+ */
+function parseEnvContent(content) {
+  const env = {};
+  if (typeof content !== 'string') return env;
+
+  const lines = content.split('\n');
+  for (const rawLine of lines) {
+    const trimmed = rawLine.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const eqIndex = trimmed.indexOf('=');
+    if (eqIndex === -1) continue;
+
+    const key = trimmed.slice(0, eqIndex).trim();
+    if (!key) continue;
+
+    const rawValue = trimmed.slice(eqIndex + 1).trim();
+    let value = rawValue;
+
+    const isDoubleQuoted = rawValue.startsWith('"') && rawValue.endsWith('"') && rawValue.length >= 2;
+    const isSingleQuoted = rawValue.startsWith("'") && rawValue.endsWith("'") && rawValue.length >= 2;
+
+    if (isDoubleQuoted || isSingleQuoted) {
+      value = rawValue.slice(1, -1);
+    }
+
+    if (isDoubleQuoted) {
+      value = value.replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+    }
+
+    env[key] = value;
+  }
+
+  return env;
+}
+
+/**
+ * Safely read + parse an .env file. Never throws.
+ * @param {string} filePath
+ * @returns {Record<string, string>}
+ */
+function readEnvFile(filePath) {
+  try {
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+      return parseEnvContent(fs.readFileSync(filePath, 'utf8'));
+    }
+  } catch (error) {
+    if (process.env.DEBUG) {
+      console.error(`[ak-journal env-loader] could not read ${filePath}: ${error.message}`);
+    }
+  }
+  return {};
+}
+
+function getHomeDir() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+/**
+ * Load the merged env cascade for a given project directory. Does NOT
+ * mutate process.env — callers read from the returned object, falling back
+ * to process.env themselves (or use {@link resolveEnv}).
+ *
+ * @param {string} [cwd] project root to resolve `.agentkit/.env` /
+ *   `.claude/.env` from. Defaults to process.cwd().
+ * @returns {Record<string, string>} merged file-sourced env (process.env
+ *   NOT included — see resolveEnv for the process.env-aware accessor)
+ */
+function loadEnv(cwd) {
+  const projectRoot = cwd || process.cwd();
+  const homeDir = getHomeDir();
+
+  // Lowest priority first; later entries override earlier ones.
+  const layers = [
+    readEnvFile(path.join(homeDir, '.claude', '.env')), // 5. legacy user
+    readEnvFile(path.join(projectRoot, '.claude', '.env')), // 4. legacy project
+    readEnvFile(path.join(homeDir, '.agentkit', '.env')), // 3. user
+    readEnvFile(path.join(projectRoot, '.agentkit', '.env')), // 2. project
+  ];
+
+  let merged = {};
+  for (const layer of layers) {
+    merged = { ...merged, ...layer };
+  }
+  return merged;
+}
+
+/**
+ * Resolve a single env var honoring the full cascade, process.env highest.
+ * @param {string} key
+ * @param {string} [cwd]
+ * @param {string} [defaultValue]
+ * @returns {string | undefined}
+ */
+function resolveEnv(key, cwd, defaultValue) {
+  if (process.env[key] !== undefined) return process.env[key];
+  const fileEnv = loadEnv(cwd);
+  return fileEnv[key] !== undefined ? fileEnv[key] : defaultValue;
+}
+
+/**
+ * Merge the cascade with process.env (process.env wins) into one object.
+ * Convenience for callers that want a single lookup table.
+ * @param {string} [cwd]
+ * @returns {Record<string, string>}
+ */
+function resolveAllEnv(cwd) {
+  return { ...loadEnv(cwd), ...process.env };
+}
+
+module.exports = {
+  loadEnv,
+  parseEnvContent,
+  resolveEnv,
+  resolveAllEnv,
+};

package/skills/journal/scripts/env-loader.test.cjs

@@ -0,0 +1,131 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+
+const { loadEnv, parseEnvContent, resolveEnv, resolveAllEnv } = require('./env-loader.cjs');
+
+function makeTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+test('parseEnvContent: parses simple key=value pairs', () => {
+  const result = parseEnvContent('KEY=value\nOTHER=thing');
+  assert.equal(result.KEY, 'value');
+  assert.equal(result.OTHER, 'thing');
+});
+
+test('parseEnvContent: skips comments and blank lines', () => {
+  const result = parseEnvContent('# comment\n\nKEY=value\n  # indented comment\nKEY2=value2');
+  assert.deepEqual(result, { KEY: 'value', KEY2: 'value2' });
+});
+
+test('parseEnvContent: strips matching double and single quotes', () => {
+  const result = parseEnvContent('DOUBLE="hello world"\nSINGLE=\'hello world\'');
+  assert.equal(result.DOUBLE, 'hello world');
+  assert.equal(result.SINGLE, 'hello world');
+});
+
+test('parseEnvContent: handles values containing extra equals signs', () => {
+  const result = parseEnvContent('KEY=a=b=c');
+  assert.equal(result.KEY, 'a=b=c');
+});
+
+test('parseEnvContent: expands \\n and \\t escapes only inside double quotes', () => {
+  const result = parseEnvContent('DOUBLE="line1\\nline2"\nSINGLE=\'line1\\nline2\'');
+  assert.equal(result.DOUBLE, 'line1\nline2');
+  assert.equal(result.SINGLE, 'line1\\nline2');
+});
+
+test('parseEnvContent: non-string input returns empty object', () => {
+  assert.deepEqual(parseEnvContent(undefined), {});
+  assert.deepEqual(parseEnvContent(null), {});
+});
+
+test('loadEnv: missing files across the whole cascade returns empty object', () => {
+  const projectRoot = makeTempDir('ak-journal-env-missing-');
+  const homeDir = makeTempDir('ak-journal-env-missing-home-');
+  const originalHome = process.env.HOME;
+  try {
+    process.env.HOME = homeDir;
+    const result = loadEnv(projectRoot);
+    assert.deepEqual(result, {});
+  } finally {
+    process.env.HOME = originalHome;
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});
+
+test('loadEnv: cascade precedence — project .agentkit/.env wins over user .agentkit/.env, .claude/.env layers, but process.env still wins via resolveEnv', () => {
+  const projectRoot = makeTempDir('ak-journal-env-cascade-');
+  const homeDir = makeTempDir('ak-journal-env-cascade-home-');
+  const originalHome = process.env.HOME;
+  try {
+    process.env.HOME = homeDir;
+
+    fs.mkdirSync(path.join(homeDir, '.claude'), { recursive: true });
+    fs.writeFileSync(path.join(homeDir, '.claude', '.env'), 'VAR=legacy-user\nONLY_LEGACY_USER=1\n');
+
+    fs.mkdirSync(path.join(projectRoot, '.claude'), { recursive: true });
+    fs.writeFileSync(path.join(projectRoot, '.claude', '.env'), 'VAR=legacy-project\n');
+
+    fs.mkdirSync(path.join(homeDir, '.agentkit'), { recursive: true });
+    fs.writeFileSync(path.join(homeDir, '.agentkit', '.env'), 'VAR=agentkit-user\n');
+
+    fs.mkdirSync(path.join(projectRoot, '.agentkit'), { recursive: true });
+    fs.writeFileSync(path.join(projectRoot, '.agentkit', '.env'), 'VAR=agentkit-project\n');
+
+    const fileEnv = loadEnv(projectRoot);
+    assert.equal(fileEnv.VAR, 'agentkit-project');
+    assert.equal(fileEnv.ONLY_LEGACY_USER, '1');
+
+    delete process.env.VAR;
+    assert.equal(resolveEnv('VAR', projectRoot), 'agentkit-project');
+
+    process.env.VAR = 'from-process-env';
+    assert.equal(resolveEnv('VAR', projectRoot), 'from-process-env');
+    delete process.env.VAR;
+  } finally {
+    process.env.HOME = originalHome;
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});
+
+test('resolveEnv: falls back to defaultValue when key is absent everywhere', () => {
+  const projectRoot = makeTempDir('ak-journal-env-default-');
+  const homeDir = makeTempDir('ak-journal-env-default-home-');
+  const originalHome = process.env.HOME;
+  try {
+    process.env.HOME = homeDir;
+    assert.equal(resolveEnv('NOPE_NOT_SET', projectRoot, 'fallback'), 'fallback');
+    assert.equal(resolveEnv('NOPE_NOT_SET', projectRoot), undefined);
+  } finally {
+    process.env.HOME = originalHome;
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});
+
+test('resolveAllEnv: merges file cascade with process.env, process.env winning', () => {
+  const projectRoot = makeTempDir('ak-journal-env-merge-');
+  const homeDir = makeTempDir('ak-journal-env-merge-home-');
+  const originalHome = process.env.HOME;
+  try {
+    process.env.HOME = homeDir;
+    fs.mkdirSync(path.join(projectRoot, '.agentkit'), { recursive: true });
+    fs.writeFileSync(path.join(projectRoot, '.agentkit', '.env'), 'FILE_ONLY=from-file\nOVERRIDDEN=from-file\n');
+    process.env.OVERRIDDEN = 'from-process';
+
+    const merged = resolveAllEnv(projectRoot);
+    assert.equal(merged.FILE_ONLY, 'from-file');
+    assert.equal(merged.OVERRIDDEN, 'from-process');
+  } finally {
+    delete process.env.OVERRIDDEN;
+    process.env.HOME = originalHome;
+    fs.rmSync(projectRoot, { recursive: true, force: true });
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});

package/skills/journal/scripts/generate-image.cjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * generate-image.cjs — resolves local image file(s) for a journal's social
+ * media attachment, either from user-provided path(s)/glob(s) or by
+ * generating one via `multix` (AI image generation).
+ *
+ * CLI usage:
+ *   node generate-image.cjs --image <path-or-glob>... [--json]
+ *   node generate-image.cjs --image-ai <prompt> [--journal-file <path>]
+ *     [--project-root <path>] [--dry-run] [--json]
+ *
+ * Per AMENDMENTS.md V7 (Phase 7): only `--image <path>` and `--image-ai
+ * <prompt>` are direct script inputs — there is no no-value "generate a
+ * template image" branch here. That orchestration (via ak-design /
+ * ak-frontend-design) is the calling agent's job; the agent passes the
+ * resulting file back in via `--image <path>`.
+ *
+ * Cache key (kongming R6): sha256 of journal_body + writing_style +
+ * language + model + TEMPLATE_VERSION. Bump TEMPLATE_VERSION whenever the
+ * generation prompt/template shape changes, to invalidate stale cache
+ * entries deterministically.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { parseArgs } = require('util');
+const { spawnSync } = require('child_process');
+
+const { resolveConfig } = require('./resolve-config.cjs');
+const {
+  resolveMediaPaths,
+  hashFields,
+  slugForJournalFile,
+  cacheDirFor,
+  readJournalBodyRaw,
+  npxCommand,
+  redactSecrets,
+} = require('./media-utils.cjs');
+
+const TEMPLATE_VERSION = '1';
+const DEFAULT_IMAGE_MODEL = 'google/gemini-2.5-flash-image';
+
+function parseCliArgs(argv) {
+  return parseArgs({
+    args: argv,
+    options: {
+      image: { type: 'string', multiple: true, default: [] },
+      'image-ai': { type: 'string' },
+      'journal-file': { type: 'string' },
+      'project-root': { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+      help: { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  });
+}
+
+/** sha256 cache key per AMENDMENTS.md R6. */
+function buildCacheKey({ journalBody, imageAiPrompt, writingStyle, language, model }) {
+  return hashFields([journalBody, imageAiPrompt, writingStyle, language, model, TEMPLATE_VERSION]);
+}
+
+/**
+ * Invoke multix to generate an AI image. Test doubles:
+ *   MOCK_MULTIX_OUTPUT=<path>  — short-circuits the spawn; copies that file to outputPath.
+ *   MOCK_MULTIX_ARGV=1         — additionally writes the argv that would have
+ *                                 been used to MOCK_MULTIX_ARGV_PATH (default
+ *                                 <tmpdir>/multix-argv.json) for assertion.
+ */
+function invokeMultixImage({ prompt, model, outputPath, env }) {
+  if (env.MOCK_MULTIX_OUTPUT) {
+    const argv = ['-y', 'multix', 'image', '--model', model, '--prompt', prompt, '--output', outputPath];
+    if (env.MOCK_MULTIX_ARGV === '1') {
+      const argvPath = env.MOCK_MULTIX_ARGV_PATH || path.join(os.tmpdir(), 'multix-argv.json');
+      fs.writeFileSync(argvPath, JSON.stringify(argv));
+    }
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.copyFileSync(env.MOCK_MULTIX_OUTPUT, outputPath);
+    return;
+  }
+
+  const argv = ['-y', 'multix', 'image', '--model', model, '--prompt', prompt, '--output', outputPath];
+  const { command, args } = npxCommand(argv);
+  const result = spawnSync(command, args, { encoding: 'utf8', env });
+  if (result.status !== 0) {
+    const message = redactSecrets((result.stderr || result.stdout || 'unknown error').trim(), env);
+    throw new Error(`multix image generation failed: ${message}`);
+  }
+}
+
+/**
+ * Resolve image(s) for social posting: direct path/glob passthrough, or
+ * multix AI generation (cached).
+ * @returns {{paths: string[], cached?: boolean, dryRun?: boolean}}
+ */
+function generateImages({
+  imageArgs = [],
+  imageAiPrompt,
+  journalFile,
+  projectRoot,
+  cwd,
+  dryRun = false,
+  env = process.env,
+} = {}) {
+  const startDir = cwd || process.cwd();
+
+  if (imageArgs.length > 0) {
+    return { paths: resolveMediaPaths(imageArgs, startDir) };
+  }
+
+  if (!imageAiPrompt) {
+    return { paths: [] };
+  }
+
+  const config = resolveConfig({ projectRoot, cwd: startDir });
+  const model = (config.ai && config.ai.image_model) || DEFAULT_IMAGE_MODEL;
+  const journalBody = journalFile && fs.existsSync(journalFile) ? readJournalBodyRaw(journalFile) : '';
+  const slug = journalFile ? slugForJournalFile(journalFile) : 'ad-hoc';
+  const cacheKey = buildCacheKey({
+    journalBody,
+    imageAiPrompt,
+    writingStyle: config.writing_style,
+    language: config.language,
+    model,
+  });
+  const dir = cacheDirFor(config.projectRoot, slug);
+  const outputPath = path.join(dir, `image-${cacheKey.slice(0, 16)}.png`);
+
+  if (fs.existsSync(outputPath)) {
+    return { paths: [outputPath], cached: true };
+  }
+
+  if (dryRun) {
+    return { paths: [outputPath], dryRun: true };
+  }
+
+  fs.mkdirSync(dir, { recursive: true });
+  invokeMultixImage({ prompt: imageAiPrompt, model, outputPath, env });
+  return { paths: [outputPath], cached: false };
+}
+
+function main() {
+  let values;
+  try {
+    ({ values } = parseCliArgs(process.argv.slice(2)));
+  } catch (error) {
+    console.error(`[generate-image] invalid arguments: ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (values.help) {
+    console.error(
+      'Usage: node generate-image.cjs --image <path-or-glob>... | --image-ai <prompt> [--journal-file <path>] [--project-root <path>] [--dry-run] [--json]'
+    );
+    return;
+  }
+
+  if (values.image.length === 0 && !values['image-ai']) {
+    console.error('[generate-image] pass --image <path-or-glob> or --image-ai <prompt>');
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const result = generateImages({
+      imageArgs: values.image,
+      imageAiPrompt: values['image-ai'],
+      journalFile: values['journal-file'] ? path.resolve(values['journal-file']) : undefined,
+      projectRoot: values['project-root'],
+      dryRun: values['dry-run'],
+    });
+    if (values.json) {
+      console.log(JSON.stringify(result));
+    } else {
+      console.error(result.paths.join('\n'));
+    }
+  } catch (error) {
+    console.error(`[generate-image] ${redactSecrets(error.message)}`);
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  TEMPLATE_VERSION,
+  DEFAULT_IMAGE_MODEL,
+  buildCacheKey,
+  generateImages,
+};