@hiveku-apps/sync 0.2.0 → 0.3.1

package/README.md

@@ -78,6 +78,46 @@ narrowed tool list. Available: `full`, `sales`, `marketing`, `helpdesk`,
 `pm`, `dev`. Change `HIVEKU_PROFILE` in `.env` and reload the MCP server
 in your editor to switch.
 
+## Codex (OpenAI) support
+
+By default `init` scaffolds a Claude Code folder (`.mcp.json` + `CLAUDE.md`). Add
+`--codex` to also write the Codex-native equivalents so the same folder works
+from the **Codex CLI / IDE extension / ChatGPT desktop**:
+
+```bash
+# Scaffold with the Codex lane too:
+hiveku-sync init acme-corp --codex
+
+# Or retrofit an existing account folder (run after `pull` to include the
+# account's latest skills/commands):
+cd acme-corp && hiveku-sync codex
+```
+
+This writes, merge-safely (only Hiveku-managed regions are touched):
+
+- **`AGENTS.md`** — Codex's `CLAUDE.md` equivalent: a lean pointer to `CLAUDE.md`
+  plus the load-bearing rules (Codex caps the instruction chain at ~32 KiB).
+- **`.codex/config.toml`** — the same `core.hiveku.com/mcp` server via
+  `[mcp_servers.hiveku]`, git-ignored. Your `OLYMPUS_API_KEY` is **inlined** when
+  `.env` has it (self-contained, no env setup); otherwise it's read from the
+  `OLYMPUS_API_KEY` env var. Also wires `playwright` for visual checks.
+- **`.agents/skills/<name>/SKILL.md`** — the account's pulled `skills/` and
+  `commands/` mirrored as repo-scoped Codex skills (Codex prompts are global-only
+  and deprecated).
+
+Pass `--trust` to pre-trust the folder in `~/.codex/config.toml` (so Codex loads
+the repo config without its first-run trust prompt). Codex ignores repo-level
+approval/sandbox config, so the safe-work rules ship as instructions in
+`AGENTS.md`, not enforced permissions.
+
+> **This vs. the plugin.** For a single account, you can instead install the
+> published [Hiveku Codex plugin](https://github.com/locus2012/hiveku-codex-plugin)
+> once (`codex plugin marketplace add locus2012/hiveku-codex-plugin` then
+> `codex plugin add hiveku@hiveku`) and set
+> `HIVEKU_TOKEN`. `hiveku-sync --codex` is the self-contained, per-account route —
+> better for multi-account / CI / power-user setups, and it also brings the
+> account's own knowledge. Use one route per folder, not both.
+
 ## Coder projects — pull, ship, deploy
 
 Beyond memory/rules/skills, `hiveku-sync` can drive a Hiveku **website project**

package/bin/hiveku-sync.mjs

@@ -9,6 +9,7 @@
  */
 
 import { runInit } from '../src/init.mjs';
+import { runCodex } from '../src/init.mjs';
 import { runPull } from '../src/pull.mjs';
 import {
   runProjectsList,
@@ -69,10 +70,22 @@ const HELP = `hiveku-sync — sync a Hiveku account into a local Claude Code fol
 
 Memory/rules/skills:
   init <slug> [--profile=<name>]    Scaffold ./<slug>/ with .env, .mcp.json,
-                                    CLAUDE.md, and the memory/rules/skills tree.
+              [--codex] [--trust]   CLAUDE.md, and the memory/rules/skills tree.
+                                    --codex also writes the Codex lane (AGENTS.md
+                                    + .codex/config.toml + skills); --trust
+                                    pre-trusts the folder in ~/.codex/config.toml.
   pull [--profile=<name>]           Pull memory/rules/skills via MCP into the
                                     current account folder. Reads OLYMPUS_API_KEY
                                     and OLYMPUS_BASE_URL from ./.env.
+  codex [<folder>] [--trust]        Retrofit an existing account folder with the
+                                    Codex lane (AGENTS.md + .codex/config.toml +
+                                    mirror the account's skills/commands to
+                                    .agents/skills/). Run after 'pull' to include
+                                    the latest knowledge. Complements the published
+                                    Hiveku Codex plugin (single-account users can
+                                    instead run: codex plugin marketplace add
+                                    locus2012/hiveku-codex-plugin, then:
+                                    codex plugin add hiveku@hiveku).
 
 Coder projects:
   projects                          List the account's coder projects.
@@ -132,6 +145,8 @@ async function main() {
         slug,
         parentDir: flags['parent'],
         profile: flags['profile'] || 'full',
+        codex: !!flags['codex'],
+        trust: !!flags['trust'],
       });
       console.log(`Initialized ${result.folder}`);
       console.log(`  profile: ${result.profile}`);
@@ -141,9 +156,33 @@ async function main() {
       if (result.workspaceAdded) {
         console.log(`  workspace: added entry to hiveku.code-workspace`);
       }
+      if (result.codex) {
+        console.log(`  codex: wrote AGENTS.md + .codex/config.toml (git-ignored)`);
+        console.log(
+          result.codex.inlinedKey
+            ? `    MCP auth: inlined your OLYMPUS_API_KEY`
+            : `    MCP auth: reads the OLYMPUS_API_KEY env var — after pasting your key into .env, run \`hiveku-sync codex\` to inline it, or \`export OLYMPUS_API_KEY=...\``,
+        );
+        if (result.codex.trust === 'added') console.log(`    trust: pre-trusted this folder in ~/.codex/config.toml`);
+      }
       console.log(`  then: cd ${result.folder} && hiveku-sync pull`);
       break;
     }
+    case 'codex': {
+      const result = await runCodex({ folder: positional[0], trust: !!flags['trust'] });
+      console.log(`Codex lane ready in ${result.folder} (profile=${result.profile})`);
+      console.log(`  AGENTS.md + .codex/config.toml written (git-ignored).`);
+      console.log(
+        result.inlinedKey
+          ? `  MCP auth: inlined OLYMPUS_API_KEY from .env.`
+          : `  MCP auth: reads the OLYMPUS_API_KEY env var (no key found in .env to inline) — set it, or paste it into .env and re-run.`,
+      );
+      console.log(`  skills: mirrored ${result.skillsMirrored} account skill/command entr${result.skillsMirrored === 1 ? 'y' : 'ies'} into .agents/skills/.`);
+      if (result.trust === 'added') console.log(`  trust: pre-trusted this folder in ~/.codex/config.toml.`);
+      else if (result.trust === 'already') console.log(`  trust: folder already trusted.`);
+      console.log(`  verify: cd there, run \`codex mcp list\` (the hiveku row), then \`get_account_info\`.`);
+      break;
+    }
     case 'pull': {
       const summary = await runPull({ profile: flags['profile'] });
       console.log(`Pulled ${summary.total} entries (profile=${summary.profile}, base=${summary.baseUrl}):`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder, and ship projects (push/deploy/pull-env) from the terminal. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
   "type": "module",
   "license": "MIT",
@@ -8,7 +8,7 @@
   "homepage": "https://app.hiveku.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/locus2012/hiveku-sync.git"
+    "url": "git+https://github.com/locus2012/hiveku-sync.git"
   },
   "bugs": {
     "url": "https://github.com/locus2012/hiveku-sync/issues"
@@ -19,7 +19,8 @@
     "claude",
     "claude-code",
     "cli",
-    "olympus"
+    "olympus",
+    "codex"
   ],
   "bin": {
     "hiveku-sync": "bin/hiveku-sync.mjs"

package/src/codex.mjs

@@ -0,0 +1,256 @@
+/**
+ * Codex (OpenAI) support for hiveku-sync — the Codex-native equivalents of the
+ * Claude Code artifacts, so a Hiveku account folder works identically from the
+ * Codex CLI, the Codex IDE extension, and the ChatGPT desktop app (all three
+ * read the same files). Opt in with `--codex` on `init`, or run
+ * `hiveku-sync codex` in an existing folder.
+ *
+ * Writes, merge-safely (only our marked regions are rewritten; user content is
+ * preserved):
+ *   CLAUDE.md              → AGENTS.md  (lean pointer + load-bearing rules; Codex
+ *                            concatenates AGENTS.md with a ~32KiB cap, so the
+ *                            full guide stays in CLAUDE.md and AGENTS.md says to
+ *                            read it)
+ *   .mcp.json              → .codex/config.toml [mcp_servers.*] (the SAME
+ *                            core.hiveku.com/mcp server + the SAME OLYMPUS_API_KEY;
+ *                            inlined when we can resolve the key, else read from
+ *                            the OLYMPUS_API_KEY env var). git-ignored.
+ *   skill/command knowledge → .agents/skills/<name>/SKILL.md (repo-scoped; Codex
+ *                            prompts are global-only + deprecated)
+ *   permissions            → NO per-repo equivalent (Codex ignores approval/
+ *                            sandbox keys in repo config) — stated in AGENTS.md.
+ *
+ * This complements the published Hiveku Codex plugin
+ * (github.com/locus2012/hiveku-codex-plugin): the plugin ships the generic
+ * `hiveku` MCP server + doctrine skills for single-account users who install it
+ * once and set HIVEKU_TOKEN; this writes a SELF-CONTAINED per-account folder
+ * (its own MCP config + that account's own knowledge) for multi-account / CI /
+ * power-user setups. Use one route or the other per folder, not both.
+ */
+
+import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+
+import { loadDotenv, safeSlug } from './util.mjs';
+
+const AGENTS_BEGIN = '<!-- hiveku:begin -->';
+const AGENTS_END = '<!-- hiveku:end -->';
+const TOML_BEGIN = '# hiveku:begin (managed by hiveku-sync — do not edit inside)';
+const TOML_END = '# hiveku:end';
+const SKILL_STAMP = '<!-- generated-by: hiveku-sync (mirrored from account knowledge) -->';
+
+/** Replace (or append) the marked region inside existing content. */
+function upsertMarkedRegion(existing, begin, end, region) {
+  const b = existing.indexOf(begin);
+  const e = existing.indexOf(end);
+  if (b !== -1 && e !== -1 && e > b) {
+    return existing.slice(0, b) + region + existing.slice(e + end.length);
+  }
+  const sep = existing.length && !existing.endsWith('\n\n') ? (existing.endsWith('\n') ? '\n' : '\n\n') : '';
+  return existing + sep + region + '\n';
+}
+
+/** AGENTS.md — lean on purpose (Codex caps the instruction chain at ~32KiB). */
+function agentsMdRegion({ slug }) {
+  return `${AGENTS_BEGIN}
+# Hiveku — ${slug}
+
+This folder is ONE Hiveku account (${slug}). Its MCP server \`hiveku\` (configured in
+\`.codex/config.toml\`) carries this account's API key — never operate a different account from here.
+
+**FIRST ACTION every session: read \`CLAUDE.md\` in this folder.** It is the full operating guide
+(written for Claude Code, applies to you identically): account tools, department data, project
+push/deploy flows, and the work-tracking rules. Ignore only its Claude-specific file paths
+(\`.claude/*\`) — your equivalents are \`.agents/skills/*\` (the account's mirrored skills/commands,
+invoked by name) and this file.
+
+Non-negotiables (also in CLAUDE.md, restated because they are load-bearing):
+- **Verify identity before ANY write:** \`get_account_info\` must return THIS account.
+- **You are NOT the only writer.** Others push to these same projects while you work. Check what is
+  current BEFORE you start (\`project_version_log\`) and AGAIN before you push (\`project_files_status\`
+  — \`changed\` = they edited it, \`only_remote\` = they added files you lack). Before any tree-replace
+  (\`delete_missing: true\`), \`dry_run\` first and READ the would-delete list — a file you did not send
+  may be someone else's NEW work. Never blind-overwrite.
+- **Keep ALL scratch work in \`.hiveku/tmp/\`** — never \`/tmp\` (shared across accounts), your home
+  dir, or the repo root.
+- **Never ingest local agent config into a project push.** \`.codex/config.toml\`, \`.mcp.json\`, and
+  \`.env*\` carry this account's key/secrets — exclude them from every tar/bulk-save. Secrets belong in
+  \`project_secrets_*\`, never in project code. Never read or print \`.env.local\`.
+- **PM tasks are required** — create one when you start, comment as you go, complete it when done,
+  attributed to the authenticated user (\`crm_list_users\`).
+- **Every completed task ends with an "Owner update"** — 2–4 calm, plain-language sentences a busy owner
+  can skim: benefit first, no alarm vocabulary, accurate.
+- Video generation is paid + capped — \`marketing_generate_video\` with \`dry_run: true\` first.
+
+Discover tools with \`hiveku_docs_search\` / \`hiveku_docs_get\` and \`hiveku_playbooks_list\` /
+\`hiveku_playbook_get\`. Codex ignores repo-level approval/sandbox config, so the rules above are
+instructions, not enforced permissions — follow them.
+${AGENTS_END}`;
+}
+
+/** The [mcp_servers.*] region for <folder>/.codex/config.toml. */
+function codexTomlRegion({ baseUrl, profile, apiKey }) {
+  const base = baseUrl.replace(/\/+$/, '');
+  const url = profile === 'full' ? `${base}/mcp` : `${base}/mcp?profile=${encodeURIComponent(profile)}`;
+  // Prefer an inlined key (self-contained, no env setup needed; the file is
+  // git-ignored). Fall back to the OLYMPUS_API_KEY env var when we can't
+  // resolve a real key at scaffold time (e.g. `init` before the user pastes it).
+  const auth = apiKey
+    ? `http_headers = { "Authorization" = "Bearer ${apiKey}" }`
+    : `bearer_token_env_var = "OLYMPUS_API_KEY"`;
+  // default_tools_approval_mode = "approve": this folder exists so the agent
+  // can operate the account — per-call approval prompts would also auto-cancel
+  // every tool call in headless `codex exec` (CI/cron), this lane's core use.
+  // (Enum is approve|prompt; the docs' "auto" is not accepted by codex 0.131.)
+  return `${TOML_BEGIN}
+[mcp_servers.hiveku]
+url = "${url}"
+${auth}
+default_tools_approval_mode = "approve"
+
+[mcp_servers.playwright]
+command = "npx"
+args = ["-y", "@playwright/mcp@latest"]
+${TOML_END}`;
+}
+
+/** Add lines to .gitignore when missing (non-destructive). */
+async function appendGitignoreLines(folder, lines) {
+  const giPath = join(folder, '.gitignore');
+  let gi = '';
+  try {
+    gi = await readFile(giPath, 'utf8');
+  } catch {
+    /* new file */
+  }
+  const have = new Set(gi.split('\n').map((l) => l.trim()));
+  const missing = lines.filter((l) => !have.has(l));
+  if (missing.length === 0) return;
+  const sep = gi.length && !gi.endsWith('\n') ? '\n' : '';
+  await writeFile(giPath, gi + sep + missing.join('\n') + '\n', 'utf8');
+}
+
+/**
+ * Mirror the account's pulled skill + command knowledge into repo-scoped Codex
+ * skills at .agents/skills/<name>/SKILL.md. Reads the folders `hiveku-sync pull`
+ * writes (skills/, commands/). Idempotent: a skill dir without our stamp is
+ * left alone (user-authored). Returns the count written.
+ */
+export async function mirrorKnowledgeToSkills(folder) {
+  let written = 0;
+  for (const srcDir of ['skills', 'commands']) {
+    const root = join(folder, srcDir);
+    if (!existsSync(root)) continue;
+    // pull writes FLAT <type>/<slug>.md (department lives in the frontmatter,
+    // not the path) — but tolerate one level of hand-made subdirs too. Nested
+    // entries are isFile-checked so a directory named `x.md` can't crash us.
+    const files = [];
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        for (const sub of await readdir(join(root, entry.name), { withFileTypes: true })) {
+          if (sub.isFile() && sub.name.endsWith('.md')) files.push(join(root, entry.name, sub.name));
+        }
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        files.push(join(root, entry.name));
+      }
+    }
+    for (const filePath of files) {
+      const src = await readFile(filePath, 'utf8');
+      const base = filePath.split('/').pop().replace(/\.md$/, '');
+      // safeSlug: pull-written names are already slugs, but a hand-authored
+      // file like "My notes: draft.md" must not produce invalid YAML or an
+      // invalid skill dir name.
+      const name = `hiveku-${srcDir === 'commands' ? 'cmd' : 'skill'}-${safeSlug(base)}`.slice(0, 100);
+      let description = `Hiveku ${srcDir === 'commands' ? 'command' : 'skill'}: ${base}`;
+      let body = src;
+      const fm = src.match(/^---\n([\s\S]*?)\n---\n?/);
+      if (fm) {
+        const d = fm[1].match(/^description:\s*(.+)$/m);
+        if (d) description = d[1].trim().replace(/^["']|["']$/g, '');
+        body = src.slice(fm[0].length);
+      }
+      body = body.replace(/\$ARGUMENTS/g, '(the arguments the user gave after the skill name)');
+      const skillDir = join(folder, '.agents', 'skills', name);
+      const skillPath = join(skillDir, 'SKILL.md');
+      try {
+        const existing = await readFile(skillPath, 'utf8');
+        if (!existing.includes(SKILL_STAMP)) continue; // user-authored — never clobber
+      } catch {
+        /* new */
+      }
+      await mkdir(skillDir, { recursive: true });
+      const skill = `---\nname: ${name}\ndescription: ${JSON.stringify(description)}\n---\n${SKILL_STAMP}\n\n${body.trimStart()}`;
+      await writeFile(skillPath, skill, 'utf8');
+      written += 1;
+    }
+  }
+  return written;
+}
+
+/**
+ * Write/refresh the Codex scaffold for one account folder: AGENTS.md +
+ * .codex/config.toml (git-ignored) + mirror the account's knowledge to skills.
+ * Resolves OLYMPUS_API_KEY from the folder's .env / process env to inline the
+ * MCP auth when possible.
+ */
+export async function writeCodexScaffold({ folder, slug, baseUrl, profile }) {
+  // The FOLDER's .env wins over a process-level export: folder = tenant
+  // boundary, and a globally exported key for account A must never get
+  // inlined into account B's config during a retrofit. process.env is only a
+  // fallback for folders that keep no .env at all.
+  const dotenv = await loadDotenv(join(folder, '.env'));
+  const dotenvKey =
+    dotenv.OLYMPUS_API_KEY && dotenv.OLYMPUS_API_KEY !== 'olp_replace_me' ? dotenv.OLYMPUS_API_KEY : '';
+  const apiKey = dotenvKey || (existsSync(join(folder, '.env')) ? '' : process.env.OLYMPUS_API_KEY || '');
+
+  // AGENTS.md (marker-managed)
+  const agentsPath = join(folder, 'AGENTS.md');
+  let agents = '';
+  try {
+    agents = await readFile(agentsPath, 'utf8');
+  } catch {
+    /* new */
+  }
+  await writeFile(agentsPath, upsertMarkedRegion(agents, AGENTS_BEGIN, AGENTS_END, agentsMdRegion({ slug })), 'utf8');
+
+  // .codex/config.toml (marker-managed region; rest of user's config untouched)
+  const tomlPath = join(folder, '.codex', 'config.toml');
+  let toml = '';
+  try {
+    toml = await readFile(tomlPath, 'utf8');
+  } catch {
+    /* new */
+  }
+  await mkdir(dirname(tomlPath), { recursive: true });
+  await writeFile(tomlPath, upsertMarkedRegion(toml, TOML_BEGIN, TOML_END, codexTomlRegion({ baseUrl, profile, apiKey })), 'utf8');
+
+  await appendGitignoreLines(folder, ['.codex/config.toml']);
+
+  const skills = await mirrorKnowledgeToSkills(folder);
+  return { inlinedKey: !!apiKey, skillsMirrored: skills };
+}
+
+/**
+ * Pre-trust a folder in the USER-GLOBAL ~/.codex/config.toml so its repo-level
+ * .codex/config.toml (which carries the MCP server + key) loads without Codex's
+ * first-run trust prompt. Crosses a security boundary — the caller must have
+ * explicit user intent (the `--trust` flag).
+ */
+export async function preTrustFolder(folder) {
+  const cfgPath = join(homedir(), '.codex', 'config.toml');
+  let cfg = '';
+  try {
+    cfg = await readFile(cfgPath, 'utf8');
+  } catch {
+    /* none yet */
+  }
+  const abs = resolve(folder);
+  const header = `[projects."${abs}"]`;
+  if (cfg.includes(header)) return 'already';
+  await mkdir(dirname(cfgPath), { recursive: true });
+  const sep = cfg.length && !cfg.endsWith('\n') ? '\n' : '';
+  await writeFile(cfgPath, `${cfg}${sep}\n${header}\ntrust_level = "trusted"\n`, 'utf8');
+  return 'added';
+}

package/src/init.mjs

@@ -7,9 +7,10 @@
 
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 
-import { writeFileAtomic, safeSlug, TYPE_TO_FOLDER } from './util.mjs';
+import { writeFileAtomic, safeSlug, TYPE_TO_FOLDER, loadDotenv } from './util.mjs';
+import { writeCodexScaffold, preTrustFolder } from './codex.mjs';
 
 const VALID_PROFILES = ['full', 'sales', 'marketing', 'helpdesk', 'pm', 'dev'];
 const DEFAULT_BASE_URL = 'https://core.hiveku.com';
@@ -148,7 +149,7 @@ async function appendToWorkspaceFile(workspaceFilePath, folderRelPath) {
   return true;
 }
 
-export async function runInit({ slug, parentDir, profile = 'full' }) {
+export async function runInit({ slug, parentDir, profile = 'full', codex = false, trust = false }) {
   if (!slug) throw new Error('slug is required, e.g. hiveku-sync init acme-corp');
   if (!VALID_PROFILES.includes(profile)) {
     throw new Error(
@@ -190,5 +191,36 @@ export async function runInit({ slug, parentDir, profile = 'full' }) {
     `./${safe}`,
   );
 
-  return { folder, slug: safe, profile, workspaceAdded };
+  // Optional Codex lane: AGENTS.md + .codex/config.toml + knowledge→skills, so
+  // the same folder works from the Codex CLI / IDE / ChatGPT desktop too.
+  let codexResult = null;
+  if (codex) {
+    codexResult = await writeCodexScaffold({
+      folder,
+      slug: safe,
+      baseUrl: DEFAULT_BASE_URL,
+      profile,
+    });
+    if (trust) codexResult.trust = await preTrustFolder(folder);
+  }
+
+  return { folder, slug: safe, profile, workspaceAdded, codex: codexResult };
+}
+
+/**
+ * Retrofit an EXISTING account folder with the Codex lane (AGENTS.md +
+ * .codex/config.toml + knowledge→skills). Run from inside the folder, or pass
+ * one. Derives the account slug from the folder name and the profile from
+ * .env (HIVEKU_PROFILE), and inlines the real OLYMPUS_API_KEY when .env has it.
+ */
+export async function runCodex({ folder, trust = false } = {}) {
+  const target = folder ? resolve(folder) : process.cwd();
+  if (!existsSync(target)) throw new Error(`Folder not found: ${target}`);
+  const dotenv = await loadDotenv(join(target, '.env'));
+  const profile = dotenv.HIVEKU_PROFILE || 'full';
+  const baseUrl = dotenv.OLYMPUS_BASE_URL || DEFAULT_BASE_URL;
+  const slug = safeSlug(basename(target));
+  const result = await writeCodexScaffold({ folder: target, slug, baseUrl, profile });
+  if (trust) result.trust = await preTrustFolder(target);
+  return { folder: target, slug, profile, ...result };
 }