@a5c-ai/babysitter-codex 0.1.6-staging.2dca8387

package/bin/postinstall.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * postinstall.js — Copies babysitter-codex skill files to ~/.codex/skills/
+ * so Codex CLI discovers the skill globally for all projects.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+const SKILL_NAME = 'babysitter-codex';
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const IS_WIN = process.platform === 'win32';
+const INSTALL_ENTRIES = [
+  { source: 'SKILL.md', required: true },
+  { source: 'AGENTS.md', required: true },
+  { source: 'README.md', required: true },
+  { source: 'agents', required: true },
+  { source: 'bin', required: true },
+  { source: '.codex', required: true },
+  { source: 'commands', required: true },
+  { source: 'scripts', required: true },
+  { source: 'babysitter.lock.json', required: true },
+];
+
+function getCodexHome() {
+  if (process.env.CODEX_HOME) return process.env.CODEX_HOME;
+  return path.join(os.homedir(), '.codex');
+}
+
+function writeFileIfChanged(filePath, contents) {
+  if (fs.existsSync(filePath)) {
+    const current = fs.readFileSync(filePath, 'utf8');
+    if (current === contents) {
+      return false;
+    }
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, contents, 'utf8');
+  return true;
+}
+
+function mergeCodexHomeConfig(codexHome) {
+  const configPath = path.join(codexHome, 'config.toml');
+  const featureLines = [
+    '[features]',
+    'codex_hooks = true',
+    'multi_agent = true',
+  ];
+
+  if (!fs.existsSync(configPath)) {
+    writeFileIfChanged(
+      configPath,
+      [
+        'approval_policy = "on-request"',
+        'sandbox_mode = "workspace-write"',
+        '',
+        ...featureLines,
+        '',
+      ].join('\n')
+    );
+    console.log(`[babysitter-codex]   wrote ${configPath}`);
+    return;
+  }
+
+  let content = fs.readFileSync(configPath, 'utf8');
+  if (!/^\s*codex_hooks\s*=.*$/m.test(content)) {
+    if (/^\[features\]\s*$/m.test(content)) {
+      content = content.replace(
+        /^\[features\]\s*$/m,
+        ['[features]', 'codex_hooks = true', 'multi_agent = true'].join('\n')
+      );
+    } else {
+      content = [content.trimEnd(), '', ...featureLines, ''].join('\n');
+    }
+  } else if (!/^\s*multi_agent\s*=.*$/m.test(content) && /^\[features\]\s*$/m.test(content)) {
+    content = content.replace(
+      /^\[features\]\s*$/m,
+      ['[features]', 'multi_agent = true'].join('\n')
+    );
+  }
+
+  if (writeFileIfChanged(configPath, content)) {
+    console.log(`[babysitter-codex]   merged ${configPath}`);
+  }
+}
+
+function shouldAutoOnboardWorkspace(skillDir) {
+  const initCwd = process.env.INIT_CWD;
+  if (!initCwd) return null;
+
+  const resolved = path.resolve(initCwd);
+  if (!fs.existsSync(resolved)) return null;
+  if (!fs.statSync(resolved).isDirectory()) return null;
+
+  const normalizedWorkspace = resolved.toLowerCase();
+  const normalizedPackageRoot = PACKAGE_ROOT.toLowerCase();
+  const normalizedSkillDir = skillDir.toLowerCase();
+  if (normalizedWorkspace === normalizedPackageRoot || normalizedWorkspace === normalizedSkillDir) {
+    return null;
+  }
+
+  return resolved;
+}
+
+function autoOnboardWorkspace(skillDir) {
+  const workspace = shouldAutoOnboardWorkspace(skillDir);
+  if (!workspace) {
+    return;
+  }
+
+  const scriptPath = path.join(skillDir, 'scripts', 'team-install.js');
+  if (!fs.existsSync(scriptPath)) {
+    console.warn('[babysitter-codex] WARNING: team-install.js is missing; skipping workspace hook onboarding');
+    return;
+  }
+
+  const result = spawnSync(process.execPath, [scriptPath, '--workspace', workspace], {
+    cwd: workspace,
+    stdio: 'pipe',
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      BABYSITTER_PACKAGE_ROOT: skillDir,
+    },
+  });
+
+  if (result.status !== 0) {
+    console.warn(`[babysitter-codex] WARNING: workspace onboarding failed for ${workspace}`);
+    if (result.stdout) console.warn(result.stdout.trim());
+    if (result.stderr) console.warn(result.stderr.trim());
+    return;
+  }
+
+  console.log(`[babysitter-codex]   onboarded workspace hooks/config at ${workspace}`);
+}
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      // Skip node_modules, .a5c, .git, and test directories
+      if (['node_modules', '.a5c', '.git', 'test', '.gitignore'].includes(entry)) continue;
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    // Codex requires SKILL.md frontmatter to begin exactly with "---".
+    // Strip UTF-8 BOM if present to avoid loader parse failures.
+    if (path.basename(src) === 'SKILL.md') {
+      const file = fs.readFileSync(src);
+      const hasBom = file.length >= 3 && file[0] === 0xef && file[1] === 0xbb && file[2] === 0xbf;
+      fs.writeFileSync(dest, hasBom ? file.subarray(3) : file);
+      return;
+    }
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function installEntry(skillDir, entry) {
+  const src = path.join(PACKAGE_ROOT, entry.source);
+  const dest = path.join(skillDir, entry.source);
+  if (!fs.existsSync(src)) {
+    if (entry.required) {
+      throw new Error(`required install payload is missing: ${src}`);
+    }
+    return false;
+  }
+  copyRecursive(src, dest);
+  console.log(`[babysitter-codex]   ${entry.source}${fs.statSync(src).isDirectory() ? '/' : ''}`);
+  return true;
+}
+
+function verifyInstalledPayload(skillDir) {
+  const missing = INSTALL_ENTRIES
+    .map((entry) => entry.source)
+    .filter((source) => !fs.existsSync(path.join(skillDir, source)));
+  if (missing.length > 0) {
+    throw new Error(`installed skill is incomplete; missing: ${missing.join(', ')}`);
+  }
+}
+
+function main() {
+  const codexHome = getCodexHome();
+  const skillDir = path.join(codexHome, 'skills', SKILL_NAME);
+
+  console.log(`[babysitter-codex] Installing skill to ${skillDir}`);
+
+  try {
+    fs.mkdirSync(skillDir, { recursive: true });
+
+    for (const entry of INSTALL_ENTRIES) {
+      installEntry(skillDir, entry);
+    }
+
+    verifyInstalledPayload(skillDir);
+    mergeCodexHomeConfig(codexHome);
+
+    if (!IS_WIN) {
+      const hookDir = path.join(skillDir, '.codex', 'hooks');
+      if (fs.existsSync(hookDir)) {
+        for (const name of fs.readdirSync(hookDir)) {
+          const hookPath = path.join(hookDir, name);
+          if (name.endsWith('.sh') && fs.statSync(hookPath).isFile()) {
+            fs.chmodSync(hookPath, 0o755);
+          }
+        }
+        console.log('[babysitter-codex]   +x hooks/*.sh');
+      }
+    }
+
+    autoOnboardWorkspace(skillDir);
+
+    console.log('[babysitter-codex] Installation complete!');
+    console.log('[babysitter-codex] Restart Codex to pick up the updated skill and hook config.');
+  } catch (err) {
+    console.error(`[babysitter-codex] Failed to install skill files: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/bin/uninstall.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * uninstall.js — Removes babysitter-codex skill files from ~/.codex/skills/
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'babysitter-codex';
+
+function getCodexHome() {
+  if (process.env.CODEX_HOME) return process.env.CODEX_HOME;
+  return path.join(os.homedir(), '.codex');
+}
+
+function main() {
+  const codexHome = getCodexHome();
+  const skillDir = path.join(codexHome, 'skills', SKILL_NAME);
+
+  if (!fs.existsSync(skillDir)) {
+    console.log('[babysitter-codex] Skill directory not found, nothing to remove.');
+    return;
+  }
+
+  try {
+    fs.rmSync(skillDir, { recursive: true, force: true });
+    console.log(`[babysitter-codex] Removed ${skillDir}`);
+    console.log('[babysitter-codex] Restart Codex to complete uninstallation.');
+  } catch (err) {
+    console.warn(`[babysitter-codex] Warning: Could not remove skill directory: ${err.message}`);
+  }
+}
+
+main();

package/commands/README.md

@@ -0,0 +1,23 @@
+# Command Docs
+
+This folder mirrors the upstream Babysitter command-doc structure for the
+Codex skill bundle and integration package. It is not evidence of a native
+Codex plugin manifest model.
+
+## Commands
+
+- [call](./call.md)
+- [yolo](./yolo.md)
+- [resume](./resume.md)
+- [plan](./plan.md)
+- [forever](./forever.md)
+- [doctor](./doctor.md)
+- [observe](./observe.md)
+- [retrospect](./retrospect.md)
+- [model](./model.md)
+- [issue](./issue.md)
+- [help](./help.md)
+- [project-install](./project-install.md)
+- [team-install](./team-install.md)
+- [user-install](./user-install.md)
+- [assimilate](./assimilate.md)

package/commands/assimilate.md

@@ -0,0 +1,27 @@
+---
+description: Assimilate external methodology/spec into babysitter process patterns.
+argument-hint: Target repo/spec/reference
+---
+
+# babysitter:assimilate
+
+## Purpose
+
+Assimilate external methodology/spec into babysitter process patterns.
+
+## Usage
+
+```text
+babysitter assimilate Target repo/spec/reference
+```
+
+## Example
+
+```text
+babysitter assimilate https://github.com/org/methodology
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/call.md

@@ -0,0 +1,30 @@
+---
+description: Start an interactive babysitter orchestration run.
+argument-hint: Specific instructions for the run
+---
+
+# babysitter:call
+
+## Purpose
+
+Start an interactive babysitter orchestration run.
+
+## Usage
+
+```text
+babysitter call Specific instructions for the run
+```
+
+## Example
+
+```text
+babysitter call implement auth with tests
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- The primary Codex plugin path is hook-first through `.codex/hooks.json` (`SessionStart`, `UserPromptSubmit`, `Stop`).
+- Low-level runtime mechanics live here and in `.codex/skills/babysitter/call/SKILL.md`, not in the top-level README or install guide.
+- The implementation should create or bind honestly, let the `Stop` hook own continuation, write value payloads to `output.json`, and post outcomes through SDK commands rather than direct `result.json` writes.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/doctor.md

@@ -0,0 +1,27 @@
+---
+description: Diagnose run/runtime health and compatibility.
+argument-hint: [run-id|mcp]
+---
+
+# babysitter:doctor
+
+## Purpose
+
+Diagnose run/runtime health and compatibility.
+
+## Usage
+
+```text
+babysitter doctor [run-id|mcp]
+```
+
+## Example
+
+```text
+babysitter doctor mcp
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/forever.md

@@ -0,0 +1,27 @@
+---
+description: Run a periodic or continuous orchestration loop.
+argument-hint: Specific instructions for recurring workflow
+---
+
+# babysitter:forever
+
+## Purpose
+
+Run a periodic or continuous orchestration loop.
+
+## Usage
+
+```text
+babysitter forever Specific instructions for recurring workflow
+```
+
+## Example
+
+```text
+babysitter forever monitor production error trends daily
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/help.md

@@ -0,0 +1,28 @@
+---
+description: Show command/process/skill/agent help.
+argument-hint: [command|process|skill|agent|methodology]
+---
+
+# babysitter:help
+
+## Purpose
+
+Show command/process/skill/agent help.
+
+## Usage
+
+```text
+babysitter help [command|process|skill|agent|methodology]
+```
+
+## Example
+
+```text
+babysitter help command doctor
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- Codex chat owns the loop through the hook model in `.codex/hooks.json`; `Stop` is the continuation owner.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/issue.md

@@ -0,0 +1,27 @@
+---
+description: Start from a GitHub issue and prepare execution/apply flow.
+argument-hint: <issue-number|url> [--repo owner/name] [--apply]
+---
+
+# babysitter:issue
+
+## Purpose
+
+Start from a GitHub issue and prepare execution/apply flow.
+
+## Usage
+
+```text
+babysitter issue <issue-number|url> [--repo owner/name] [--apply]
+```
+
+## Example
+
+```text
+babysitter issue 123 --repo owner/repo --apply
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/model.md

@@ -0,0 +1,27 @@
+---
+description: Set or show model routing policy by phase.
+argument-hint: show | clear | set <phase>=<model>
+---
+
+# babysitter:model
+
+## Purpose
+
+Set or show model routing policy by phase.
+
+## Usage
+
+```text
+babysitter model show | clear | set <phase>=<model>
+```
+
+## Example
+
+```text
+babysitter model set plan=gpt-5 execute=gpt-5-codex
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/observe.md

@@ -0,0 +1,27 @@
+---
+description: Open observer workflow for run visibility and monitoring.
+argument-hint: [watch target]
+---
+
+# babysitter:observe
+
+## Purpose
+
+Open observer workflow for run visibility and monitoring.
+
+## Usage
+
+```text
+babysitter observe [watch target]
+```
+
+## Example
+
+```text
+babysitter observe current workspace
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/plan.md

@@ -0,0 +1,27 @@
+---
+description: Plan a workflow without executing it.
+argument-hint: Specific instructions for the plan
+---
+
+# babysitter:plan
+
+## Purpose
+
+Plan a workflow without executing it.
+
+## Usage
+
+```text
+babysitter plan Specific instructions for the plan
+```
+
+## Example
+
+```text
+babysitter plan migration from monolith to services
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/project-install.md

@@ -0,0 +1,31 @@
+---
+description: Onboard babysitter into the current project.
+argument-hint: Project setup instructions
+---
+
+# babysitter:project-install
+
+## Purpose
+
+Onboard babysitter into the current project.
+
+## Usage
+
+```text
+babysitter project-install Project setup instructions
+```
+
+## Example
+
+```text
+babysitter project-install for this repository
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- Project onboarding should layer Codex config, profile, and pinned-content setup around the active process roots.
+- Do not describe project onboarding as creating a project-only process-library scope.
+- Do not document fictional hook-based continuation for Codex.
+- Keep low-level onboarding mechanics here or in the Codex skill docs, not in user-facing README copy. That includes config file writes, process-root fallback rules, and compatibility-mode behavior.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/resume.md

@@ -0,0 +1,29 @@
+---
+description: Resume an existing babysitter run/session.
+argument-hint: [selector|run-id]
+---
+
+# babysitter:resume
+
+## Purpose
+
+Resume an existing babysitter run/session.
+
+## Usage
+
+```text
+babysitter resume [selector|run-id]
+```
+
+## Example
+
+```text
+babysitter resume recent
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- Resume should continue from `.a5c/current-run.json` or the indexed run selector, then rely on the Codex `Stop` hook to continue the loop after each yield.
+- This command doc is an internal home for resume mechanics that user-facing docs should not spell out, including persisted run selection, hook-owned continuation, and honest completion-proof handling.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/retrospect.md

@@ -0,0 +1,27 @@
+---
+description: Analyze runs and propose process improvements.
+argument-hint: [run-id]
+---
+
+# babysitter:retrospect
+
+## Purpose
+
+Analyze runs and propose process improvements.
+
+## Usage
+
+```text
+babysitter retrospect [run-id]
+```
+
+## Example
+
+```text
+babysitter retrospect latest run
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/team-install.md

@@ -0,0 +1,29 @@
+---
+description: Install team-pinned runtime/content from lockfile.
+argument-hint: [--dry-run]
+---
+
+# babysitter:team-install
+
+## Purpose
+
+Install team-pinned runtime/content from lockfile.
+
+## Usage
+
+```text
+babysitter team-install [--dry-run]
+```
+
+## Example
+
+```text
+babysitter team-install
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- Team install pins content and rules for the workspace; it is not the sole process-library root.
+- This command doc is where install implementation details belong: manifest verification, lockfile handling, workspace metadata writes, and any fallback process-library behavior.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.

package/commands/user-install.md

@@ -0,0 +1,27 @@
+---
+description: Set up babysitter user profile and defaults.
+argument-hint: User setup instructions
+---
+
+# babysitter:user-install
+
+## Purpose
+
+Set up babysitter user profile and defaults.
+
+## Usage
+
+```text
+babysitter user-install User setup instructions
+```
+
+## Example
+
+```text
+babysitter user-install for backend workflows
+```
+
+## Notes
+
+- Use command phrases in Codex chat (`babysitter ...`), not custom slash commands.
+- If SDK capabilities are missing in your installed version, babysitter-codex falls back to compatibility behavior where possible.