just-vibe 0.7.0

package/plugins/just-vibe/scripts/installer.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { readFileSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDirectRun } from './lib/entrypoint.mjs';
+import { managedSource, stageBundle, inspectManaged, validateBundle } from './lib/bundle.mjs';
+import { commandInvocation } from './lib/command.mjs';
+
+export const REPOSITORY = 'Zachshotamartin/just-vibe';
+export const MARKETPLACE = 'just-vibe';
+export const PLUGIN = 'just-vibe@just-vibe';
+const VERSION = JSON.parse(readFileSync(new URL('../.codex-plugin/plugin.json', import.meta.url))).version;
+const COMMANDS = new Set(['setup', 'update', 'uninstall', 'doctor', 'help']);
+const SCOPES = new Set(['user', 'project', 'local']);
+
+export const HELP = `just-vibe ${VERSION}
+
+Usage: just-vibe <command> [options]
+
+Commands:
+  setup       Install through the selected host's native plugin manager
+  update      Refresh this marketplace and update its installed plugin
+  uninstall   Remove this plugin; keep its marketplace and persistent data
+  doctor      Check prerequisites, marketplace source, and installation
+  help        Show this help
+
+Options:
+  --target codex|claude   Host to configure (default: codex)
+  --scope user|project|local
+                         Claude installation scope (default: user)
+  --local                Register this persistent repository checkout
+  --github               Register the GitHub repository (requires access)
+  --dry-run              Print steps without running any host commands
+  --version              Print the package version
+  --help                 Show this help
+
+Examples:
+  pnpm dlx just-vibe@latest setup
+  pnpm dlx just-vibe@latest setup --target claude
+  node bin/just-vibe.mjs setup --local --dry-run
+
+Requires Node.js 22+ and the selected host CLI with plugin support.
+Default: install bundled files into ~/.just-vibe (override JUST_VIBE_HOME).
+No GitHub access is needed for bundled installs. --github also requires Git.
+`;
+
+export function parseArgs(args) {
+  const options = { command: 'help', target: 'codex', scope: 'user', local: false, github: false, dryRun: false };
+  let commandSeen = false;
+  let scopeSeen = false;
+  const flags = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') return { ...options, command: 'help' };
+    if (arg === '--version') return { ...options, command: 'version' };
+    if (['--target', '--scope', '--local', '--github', '--dry-run'].includes(arg)) {
+      if (flags.has(arg)) throw new Error(`Duplicate option: ${arg}`);
+      flags.add(arg);
+      if (arg === '--local') options.local = true;
+      else if (arg === '--github') options.github = true;
+      else if (arg === '--dry-run') options.dryRun = true;
+      else {
+        const value = args[++i];
+        if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value.`);
+        options[arg.slice(2)] = value;
+        if (arg === '--scope') scopeSeen = true;
+      }
+    } else if (!arg.startsWith('-') && !commandSeen) {
+      if (!COMMANDS.has(arg)) throw new Error(`Unknown command: ${arg}. Run just-vibe help.`);
+      options.command = arg;
+      commandSeen = true;
+    } else throw new Error(`Unexpected argument: ${arg}`);
+  }
+  if (!['codex', 'claude'].includes(options.target)) throw new Error('--target must be codex or claude.');
+  if (!SCOPES.has(options.scope)) throw new Error('--scope must be user, project, or local.');
+  if (options.local && options.github) throw new Error('--local and --github cannot be combined.');
+  if (scopeSeen && options.target !== 'claude') throw new Error('--scope applies only to Claude Code.');
+  return options;
+}
+
+// Pass arguments separately: user input is never evaluated as shell code.
+export function execute(binary, args) {
+  const [program, parameters] = commandInvocation(binary, args);
+  const result = spawnSync(program, parameters, {
+    encoding: 'utf8', shell: false, timeout: 120_000, maxBuffer: 8 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error?.code === 'ENOENT') {
+    throw new Error(`${binary} was not found on PATH. Install it, then open a new terminal and retry.`);
+  }
+  if (result.error) throw new Error(`${binary} could not finish: ${result.error.message}`);
+  if (result.status !== 0) {
+    throw new Error(`${binary} ${args.join(' ')} failed${result.signal ? ` (${result.signal})` : ''}.\n${(result.stderr || result.stdout || '').trim()}`);
+  }
+  return result.stdout.trim();
+}
+
+function json(output, label) {
+  try { return JSON.parse(output); }
+  catch { throw new Error(`${label} did not return valid JSON. Update the host CLI and retry.`); }
+}
+
+export function sourceFor(options) {
+  if (options.github) return REPOSITORY;
+  if (!options.local) return managedSource(options.target);
+  const root = fileURLToPath(new URL('../../../', import.meta.url));
+  for (const manifest of ['.agents/plugins/marketplace.json', '.claude-plugin/marketplace.json']) {
+    try {
+      if (JSON.parse(readFileSync(resolve(root, manifest))).name !== MARKETPLACE) throw new Error();
+    } catch {
+      throw new Error('--local requires a complete just-vibe repository checkout. Use the default bundled installation or --github otherwise.');
+    }
+  }
+  return root;
+}
+
+function canonicalSource(value, local) {
+  if (typeof value !== 'string') return null;
+  if (local) {
+    try { return realpathSync(value); } catch { return resolve(value); }
+  }
+  return value.replace(/^git\+/, '').replace(/^https?:\/\/github\.com\//i, '')
+    .replace(/^git@github\.com:/i, '').replace(/\/$/, '').replace(/\.git$/, '').toLowerCase();
+}
+
+export function marketplaceMatches(entry, options, source) {
+  if (options.target === 'codex') {
+    const actual = entry.marketplaceSource;
+    if (!actual || actual.sourceType !== (options.github ? 'git' : 'local')) return false;
+    return canonicalSource(actual.source, !options.github) === canonicalSource(source, !options.github);
+  }
+  if (!options.github) {
+    return ['directory', 'local'].includes(entry.source)
+      && canonicalSource(entry.path || entry.installLocation, true) === canonicalSource(source, true);
+  }
+  return ['github', 'git'].includes(entry.source)
+    && canonicalSource(entry.repo || entry.url, false) === canonicalSource(source, false);
+}
+
+function inventory(options, run) {
+  const host = options.target;
+  const marketplaces = json(run(host, ['plugin', 'marketplace', 'list', '--json']), `${host} marketplace list`);
+  const plugins = json(run(host, ['plugin', 'list', '--json']), `${host} plugin list`);
+  const marketList = host === 'codex' ? marketplaces.marketplaces : marketplaces;
+  const pluginList = host === 'codex' ? plugins.installed : plugins;
+  if (!Array.isArray(marketList) || !Array.isArray(pluginList)) {
+    throw new Error('Unsupported host inventory format. Update just-vibe or the host CLI; no changes were made.');
+  }
+  const matches = marketList.filter(entry => entry.name === MARKETPLACE);
+  if (matches.length > 1) throw new Error('Multiple just-vibe marketplaces found. Resolve the ambiguity in the host before retrying.');
+  const installed = pluginList.filter(entry => (entry.pluginId || entry.id) === PLUGIN);
+  if (host === 'claude' && installed.some(entry => entry.scope !== options.scope)) {
+    throw new Error('just-vibe is also installed at another Claude scope. Use that scope or resolve it with claude plugin list before proceeding.');
+  }
+  return { marketplace: matches[0], installed: installed[0] };
+}
+
+function mutationSteps(options, state, source) {
+  const host = options.target;
+  const scope = host === 'claude' ? ['--scope', options.scope] : [];
+  const steps = [];
+  if (options.command === 'uninstall') {
+    if (state.installed) steps.push(host === 'codex'
+      ? ['plugin', 'remove', PLUGIN]
+      : ['plugin', 'uninstall', PLUGIN, ...scope, '--keep-data']);
+    return steps;
+  }
+  if (options.command === 'doctor') return steps;
+  if (!state.marketplace) steps.push(['plugin', 'marketplace', 'add', source]);
+  else if (options.command === 'update' && (options.github || host === 'claude')) {
+    steps.push(['plugin', 'marketplace', host === 'codex' ? 'upgrade' : 'update', MARKETPLACE]);
+  }
+  if (!state.installed || options.command === 'update') {
+    steps.push(host === 'codex' ? ['plugin', 'add', PLUGIN]
+      : ['plugin', state.installed ? 'update' : 'install', PLUGIN, ...scope]);
+  } else if (state.installed.enabled === false) {
+    steps.push(host === 'claude' ? ['plugin', 'enable', PLUGIN, ...scope] : ['plugin', 'add', PLUGIN]);
+  }
+  return steps;
+}
+
+function display(host, args) {
+  return [host, ...args].map(arg => /^[a-zA-Z0-9_./:@+-]+$/.test(arg) ? arg : JSON.stringify(arg)).join(' ');
+}
+
+export function install(options, { run = execute, log = console.log, source = sourceFor(options), prepare = stageBundle } = {}) {
+  if (options.dryRun) {
+    log('Dry run — no commands executed; installed state has not been inspected.');
+    log(`Target: ${options.target}${options.target === 'claude' ? ` (${options.scope} scope)` : ''}`);
+    log(`Expected marketplace source: ${source}`);
+    log('Preflight: host CLI, native plugin subcommands, marketplace and plugin inventory.');
+    if (!options.github && !options.local && ['setup', 'update'].includes(options.command)) log(`Copy bundled plugin files to ${source} after preflight (setup preserves an existing copy; update replaces it).`);
+    if (options.command === 'doctor') log('Inspect installation and report health.');
+    else if (options.command === 'uninstall') {
+      for (const args of mutationSteps(options, { installed: {} }, source)) log(display(options.target, args));
+      log('Only runs if installed. Marketplace and persistent plugin data are retained.');
+    } else {
+      log('If missing, register the marketplace and install the plugin:');
+      for (const args of mutationSteps({ ...options, command: 'setup' }, {}, source)) log(display(options.target, args));
+      if (options.command === 'update') {
+        log('If already installed, refresh only this marketplace and update this plugin:');
+        for (const args of mutationSteps(options, { marketplace: {}, installed: {} }, source)) log(display(options.target, args));
+      } else log('Already installed: leave it unchanged (or enable it if disabled). Use update for a new version.');
+    }
+    return;
+  }
+
+  const host = options.target;
+  if (options.github) log(run('git', ['--version']));
+  log(run(host, ['--version']));
+  // Complete preflight, including command support, before the first mutation.
+  const state = inventory(options, run);
+  if (state.marketplace && !marketplaceMatches(state.marketplace, options, source)) {
+    throw new Error('A marketplace named just-vibe already points to a different or unrecognized source. No changes were made. Use --github for an existing GitHub installation or --local for a checkout. To change channels, uninstall using the old flag and remove its marketplace with the host CLI first.');
+  }
+  if (state.installed && !state.marketplace) {
+    throw new Error('just-vibe is installed without its expected marketplace. Repair its source in the host CLI before continuing.');
+  }
+  if (options.command === 'doctor') {
+    if (!state.marketplace || !state.installed) throw new Error('just-vibe is not fully installed. Run setup for this target.');
+    if (state.installed.enabled === false) throw new Error('just-vibe is installed but disabled. Run setup to enable it.');
+    if (!options.github && !options.local) {
+      if (!inspectManaged(source)) throw new Error('Managed marketplace files are missing. Run setup to restore them.');
+      const version = validateBundle(source);
+      if (state.installed.version !== version) throw new Error(`Installed plugin version differs from the managed source (${version}). Run update to finish applying it.`);
+    }
+    log(`Healthy: ${PLUGIN}${state.installed.version ? ` v${state.installed.version}` : ''}.`);
+    return;
+  }
+  const steps = mutationSteps(options, state, source);
+  for (const args of steps) run(host, [...args.slice(0, args[1] === 'marketplace' ? 3 : 2), '--help']);
+  let expectedVersion;
+  if (!options.github && !options.local && ['setup', 'update'].includes(options.command)) {
+    const version = prepare(source, { replace: options.command === 'update' });
+    expectedVersion = version;
+    log(`Bundled source: v${version} at ${source}.`);
+  }
+  for (const args of steps) {
+    log(`> ${display(host, args)}`);
+    try {
+      const output = run(host, args);
+      if (output) log(output);
+    } catch (error) {
+      throw new Error(`${error.message}\nStopped at this step. Earlier native steps may have completed; no unrelated settings were changed. Fix the error and rerun the command.`);
+    }
+  }
+  const final = inventory(options, run);
+  if (options.command === 'uninstall') {
+    if (final.installed) throw new Error('The host still reports just-vibe installed; inspect its plugin list.');
+    log('just-vibe is uninstalled. Marketplace registration and persistent plugin data were retained.');
+  } else {
+    if (!final.marketplace || !marketplaceMatches(final.marketplace, options, source)
+        || !final.installed || final.installed.enabled === false) {
+      throw new Error('The host did not report an enabled just-vibe installation. Run doctor and inspect the host plugin list.');
+    }
+    if (expectedVersion && final.installed.version !== expectedVersion) throw new Error(`Host still reports v${final.installed.version || 'unknown'} instead of bundled v${expectedVersion}. Run update and inspect its plugin list.`);
+    log(`Ready: ${PLUGIN}. Start a new conversation to load the skills.`);
+  }
+}
+
+export function main(args, dependencies = {}) {
+  const log = dependencies.log || console.log;
+  const error = dependencies.error || console.error;
+  try {
+    const options = parseArgs(args);
+    if (options.command === 'help') { log(HELP); return 0; }
+    if (options.command === 'version') { log(VERSION); return 0; }
+    if (Number(process.versions.node.split('.')[0]) < 22) throw new Error('Node.js 22 or newer is required.');
+    install(options, dependencies);
+    return 0;
+  } catch (failure) {
+    error(`just-vibe: ${failure.message}`);
+    return 1;
+  }
+}
+
+if (isDirectRun(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/plugins/just-vibe/scripts/lib/automation.mjs

@@ -0,0 +1,142 @@
+import { existsSync, mkdirSync, openSync, closeSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, relative, extname, resolve, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { atomicJson, digest, within, readJson, projectRoot, fingerprint, privateName } from './storage.mjs';
+import { gitRead } from './project.mjs';
+import { runCommand, redact } from './process.mjs';
+
+const configPath = '.just-vibe/automation.json';
+function validate(config) {
+  if (!config || config.schemaVersion !== 1 || typeof config.enabled !== 'boolean' || typeof config.saveSummary !== 'boolean'
+      || !Array.isArray(config.checks) || !Array.isArray(config.formatters) || config.checks.length + config.formatters.length > 4
+      || Object.keys(config).some(k => !['schemaVersion', 'revision', 'enabled', 'saveSummary', 'checks', 'formatters'].includes(k))) throw Error('Invalid automation configuration.');
+  const names = new Set();
+  for (const [kind, list] of [['check', config.checks], ['formatter', config.formatters]]) for (const item of list) {
+    if (!item || typeof item.name !== 'string' || !/^[a-z0-9-]{1,64}$/.test(item.name) || names.has(item.name)
+        || !Array.isArray(item.command) || !item.command.length || item.command.length > 40 || item.command.some(v => typeof v !== 'string' || !v || v.includes('\0') || v.length > 2000)
+        || !Number.isInteger(item.timeoutMs) || item.timeoutMs < 100 || item.timeoutMs > 15000
+        || !Array.isArray(item.extensions) || item.extensions.some(v => !/^\.[a-z0-9]+$/.test(v))
+        || Object.keys(item).some(k => !['name', 'command', 'timeoutMs', 'extensions'].includes(k))) throw Error('Automation entries require unique names, argv commands, extensions and a 100–15000 ms timeout.');
+    if (kind === 'formatter' && item.command.filter(v => v === '{file}').length !== 1) throw Error('A formatter must include exactly one {file} argument.');
+    if (kind === 'check' && item.command.some(v => v.includes('{file}'))) throw Error('Stop checks cannot use a file placeholder.');
+    names.add(item.name);
+  }
+  return config;
+}
+function config(root) {
+  const path = within(root, configPath);
+  return existsSync(path) ? validate(readJson(path)) : null;
+}
+function trustDirectory(home) {
+  const root = home || process.env.JUST_VIBE_HOME || join(homedir(), '.just-vibe');
+  mkdirSync(root, { recursive: true });
+  return projectRoot(root);
+}
+function trustPath(root) { return `automation-trust/${digest(projectRoot(root))}.json`; }
+function trustRecord(root, home) {
+  const base = home || process.env.JUST_VIBE_HOME || join(homedir(), '.just-vibe');
+  if (!existsSync(base)) return null;
+  const path = within(base, trustPath(root));
+  return existsSync(path) ? readJson(path) : null;
+}
+const configHash = c => digest(JSON.stringify(c));
+
+export function manageHooks(root, operation, payload = {}, { home } = {}) {
+  root = projectRoot(root);
+  const current = config(root);
+  if (operation === 'configure') {
+    validate(payload);
+    if (!Number.isInteger(payload.revision) || payload.revision < 0) throw Error('Supply current revision, or 0 for a new configuration.');
+    return atomicJson(root, configPath, payload, payload.revision);
+  }
+  if (operation === 'status') return { configuration: current, trusted: Boolean(current && trustRecord(root, home)?.configHash === configHash(current)), note: 'Host hook support and native trust are separate. Configuration alone never enables command execution.' };
+  if (operation === 'trust') {
+    if (!current) throw Error('Configure this project before trusting its commands.');
+    const base = trustDirectory(home), previous = trustRecord(root, base);
+    return atomicJson(base, trustPath(root), { schemaVersion: 1, root, configHash: configHash(current), trustedAt: new Date().toISOString() }, previous?.revision || 0);
+  }
+  if (operation === 'untrust') {
+    const previous = trustRecord(root, home);
+    if (previous) unlinkSync(within(trustDirectory(home), trustPath(root)));
+    return { trusted: false };
+  }
+  if (operation === 'disable') {
+    if (!current) return { enabled: false };
+    return atomicJson(root, configPath, { ...current, enabled: false }, current.revision);
+  }
+  if (operation === 'recover') {
+    const lock = within(root, '.just-vibe/automation/active.lock');
+    if (!existsSync(lock)) return { recovered: false };
+    const owner = readJson(lock);
+    if (!Number.isInteger(owner.pid) || owner.pid < 1) throw Error('Invalid lock owner; inspect the lock manually.');
+    try { process.kill(owner.pid, 0); throw Error('Automation owner is still running.'); }
+    catch (error) { if (error.code !== 'ESRCH') throw error; }
+    unlinkSync(lock);
+    return { recovered: true };
+  }
+  throw Error(`Unknown hooks operation: ${operation}`);
+}
+
+function touchedFiles(event) {
+  const direct = event.tool_input?.file_path || event.tool_input?.path;
+  if (typeof direct === 'string') return [direct];
+  if (event.tool_name === 'apply_patch') return [...String(event.tool_input?.command || '').matchAll(/^\*\*\* (?:Add|Update) File: (.+)$/gm)].map(m => m[1]);
+  return [];
+}
+
+export async function handleHook(event, { home, run = runCommand } = {}) {
+  if (!event || !['Stop', 'PostToolUse'].includes(event.hook_event_name) || typeof event.cwd !== 'string') return { skipped: 'unsupported-event' };
+  // Use the exact configured project, or its Git root when launched in a subdirectory.
+  let root = projectRoot(event.cwd);
+  if (!existsSync(within(root, configPath))) root = gitRead(root, ['rev-parse', '--show-toplevel']) || root;
+  const selected = config(root);
+  if (!selected?.enabled) return { skipped: 'disabled' };
+  if (trustRecord(root, home)?.configHash !== configHash(selected)) return { skipped: 'untrusted', message: 'just-vibe automation configuration changed or is untrusted. Review it with hooks status, then use hooks trust if intended.' };
+  if (event.stop_hook_active) return { skipped: 'stop-loop' };
+  const directory = within(root, '.just-vibe/automation'); mkdirSync(directory, { recursive: true });
+  const lock = join(directory, 'active.lock'); let handle;
+  try { handle = openSync(lock, 'wx', 0o600); writeFileSync(handle, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })); } catch { return { skipped: 'busy' }; }
+  try {
+    const snapshot = fingerprint(root), key = event.hook_event_name === 'Stop' ? 'stop' : 'edit';
+    const statePath = `.just-vibe/automation/${key}.json`, path = within(root, statePath);
+    const previous = existsSync(path) ? readJson(path) : null;
+    const candidates = key === 'edit' ? touchedFiles(event).map(file => within(root, resolve(projectRoot(event.cwd), isAbsolute(file) ? relative(resolve(event.cwd), file) : file))) : [];
+    const inputHash = digest(JSON.stringify({ snapshot, config: configHash(selected), candidates }));
+    const results = [];
+    if (snapshot.partial || previous?.inputHash !== inputHash) {
+      const deadline = Date.now() + 20000;
+      if (key === 'stop') {
+        for (const check of selected.checks) {
+          const time = Math.min(check.timeoutMs, deadline - Date.now());
+          if (time <= 0) { results.push({ name: check.name, result: 'skipped', reason: 'Total hook time budget exhausted' }); continue; }
+          const result = await run(check.command, { cwd: root, timeoutMs: time, maxBytes: 64000 });
+          results.push({ name: check.name, result: result.status === 0 && !result.error && !result.timedOut && !result.truncated ? 'passed' : 'failed', exitCode: result.status, timedOut: result.timedOut, truncated: result.truncated, output: redact(result.error || result.stderr || result.stdout).slice(-2000) });
+        }
+      } else {
+        const staged = gitRead(root, ['diff', '--cached', '--name-only', '-z']);
+        for (const file of candidates.slice(0, 10)) {
+          if (!existsSync(file) || privateName(file.split(/[\\/]/).pop())) continue;
+          const rel = relative(root, file).replaceAll('\\', '/');
+          for (const formatter of selected.formatters.filter(f => !f.extensions.length || f.extensions.includes(extname(file)))) {
+            if (staged === null || staged.split('\0').includes(rel)) { results.push({ name: formatter.name, file: rel, result: 'skipped', reason: 'Cannot safely format a staged file or a file without Git index evidence' }); continue; }
+            const time = Math.min(formatter.timeoutMs, deadline - Date.now());
+            if (time <= 0) { results.push({ name: formatter.name, result: 'skipped', reason: 'Total hook time budget exhausted' }); continue; }
+            const result = await run(formatter.command.map(arg => arg === '{file}' ? file : arg), { cwd: root, timeoutMs: time, maxBytes: 64000 });
+            results.push({ name: formatter.name, file: rel, result: result.status === 0 && !result.error && !result.timedOut && !result.truncated ? 'passed' : 'failed', output: redact(result.error || result.stderr || result.stdout).slice(-2000) });
+          }
+        }
+      }
+      // A formatter intentionally changes its input. A check must not certify a later tree.
+      const finalSnapshot = fingerprint(root);
+      const changedDuringChecks = key === 'stop' && JSON.stringify(snapshot) !== JSON.stringify(finalSnapshot);
+      if (changedDuringChecks) for (const result of results) if (result.result === 'passed') { result.result = 'stale'; result.reason = 'Project changed while checks ran; verify the current tree.'; }
+      atomicJson(root, statePath, { schemaVersion: 1, inputHash: key === 'edit' ? digest(JSON.stringify({ snapshot: finalSnapshot, config: configHash(selected), candidates })) : inputHash, observedAt: new Date().toISOString(), changedDuringChecks, results }, previous?.revision || 0);
+    }
+    if (key === 'stop' && selected.saveSummary) {
+      const file = '.just-vibe/automation/continuation.json', previousSummary = existsSync(within(root, file)) ? readJson(within(root, file)) : null;
+      const summary = redact(event.last_assistant_message || '').slice(0, 6000);
+      if (previousSummary?.summary !== summary || previousSummary?.snapshot?.content !== snapshot.content || previousSummary?.snapshot?.head !== snapshot.head) atomicJson(root, file, { schemaVersion: 1, kind: 'automatic-continuation', observedAt: new Date().toISOString(), snapshot: fingerprint(root), summary, note: 'Last response and filesystem identity only; verify task state and checks before continuing.' }, previousSummary?.revision || 0);
+    }
+    return { results, ...(results.some(r => ['failed', 'stale'].includes(r.result)) ? { message: `just-vibe checks need attention: ${results.filter(r => ['failed', 'stale'].includes(r.result)).map(r => `${r.name} (${r.result})`).join(', ')}. See .just-vibe/automation/${key}.json.` } : {}) };
+  } finally { closeSync(handle); unlinkSync(lock); }
+}

package/plugins/just-vibe/scripts/lib/bundle.mjs

@@ -0,0 +1,100 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export const packageRoot = fileURLToPath(new URL('../../../../', import.meta.url));
+const marker = '.just-vibe-managed.json';
+const assets = ['plugins/just-vibe', '.agents/plugins/marketplace.json', '.claude-plugin/marketplace.json'];
+
+export function managedSource(target, env = process.env) {
+  return resolve(env.JUST_VIBE_HOME || join(homedir(), '.just-vibe'), 'marketplaces', target);
+}
+
+export function validateBundle(root) {
+  for (const name of ['.agents/plugins/marketplace.json', '.claude-plugin/marketplace.json']) {
+    const manifest = JSON.parse(readFileSync(join(root, name), 'utf8'));
+    const plugin = manifest.plugins?.[0];
+    if (manifest.name !== 'just-vibe' || manifest.plugins.length !== 1 || plugin.name !== 'just-vibe'
+        || (typeof plugin.source === 'string' ? plugin.source : plugin.source.path) !== './plugins/just-vibe') {
+      throw new Error('Invalid bundled marketplace.');
+    }
+  }
+  const versions = ['codex', 'claude'].map(host => {
+    const manifest = JSON.parse(readFileSync(join(root, `plugins/just-vibe/.${host}-plugin/plugin.json`), 'utf8'));
+    if (manifest.name !== 'just-vibe' || !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(manifest.version)) throw new Error('Invalid bundled plugin.');
+    return manifest.version;
+  });
+  if (versions[0] !== versions[1]) throw new Error('Bundled plugin versions disagree.');
+  const catalog = JSON.parse(readFileSync(join(root, 'plugins/just-vibe/catalog/commands.json'), 'utf8'));
+  for (const command of catalog.commands) {
+    if (!/^[a-z0-9-]+$/.test(command.id)
+        || !existsSync(join(root, `plugins/just-vibe/skills/${command.id}/SKILL.md`))) throw new Error('Incomplete bundled skills.');
+  }
+  if (!existsSync(join(root, 'plugins/just-vibe/scripts/toolkit.mjs'))) throw new Error('Missing bundled runtime.');
+  return versions[0];
+}
+
+export function inspectManaged(root) {
+  let stat;
+  try { stat = lstatSync(root); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  if (stat.isSymbolicLink()) throw new Error(`Refusing to replace a symlink at ${root}.`);
+  let data;
+  try { data = JSON.parse(readFileSync(join(root, marker), 'utf8')); } catch {}
+  if (data?.owner !== 'just-vibe' || data.schemaVersion !== 1) {
+    throw new Error(`Directory is not managed by just-vibe: ${root}. Choose another JUST_VIBE_HOME; no files were replaced.`);
+  }
+  return data;
+}
+
+function rejectLinks(path) {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) throw new Error(`Unsupported bundled file: ${path}`);
+  if (stat.isDirectory()) for (const name of readdirSync(path)) rejectLinks(join(path, name));
+}
+
+// Only the explicit package payload is copied. A failed copy leaves the previous source intact.
+// Retain a valid managed copy on host failure so the same operation can be retried.
+export function stageBundle(destination, { root = packageRoot, replace = false } = {}) {
+  const existing = inspectManaged(destination);
+  if (existing && !replace) { validateBundle(destination); return existing.version; }
+  let version;
+  try { version = validateBundle(root); }
+  catch (error) {
+    throw new Error(`A complete npm package is needed to install/update the bundled source. Run pnpm dlx just-vibe@latest ${replace ? 'update' : 'setup'}. ${error.message}`);
+  }
+  for (const asset of assets) rejectLinks(join(root, asset));
+  mkdirSync(dirname(destination), { recursive: true });
+  const lock = `${destination}.lock`;
+  try { mkdirSync(lock); }
+  catch { throw new Error(`Another installation may be running (${lock}). Retry after it finishes. If it was interrupted, inspect and remove only that lock directory.`); }
+  let staging;
+  let backup;
+  let committed = false;
+  try {
+    // Recheck ownership while holding the copy lock.
+    inspectManaged(destination);
+    staging = mkdtempSync(join(dirname(destination), '.just-vibe-stage-'));
+    for (const asset of assets) {
+      mkdirSync(dirname(join(staging, asset)), { recursive: true });
+      cpSync(join(root, asset), join(staging, asset), { recursive: true, dereference: false });
+    }
+    if (existsSync(join(root, 'LICENSE'))) cpSync(join(root, 'LICENSE'), join(staging, 'LICENSE'));
+    validateBundle(staging);
+    writeFileSync(join(staging, marker), `${JSON.stringify({ schemaVersion: 1, owner: 'just-vibe', version })}\n`);
+    if (existsSync(destination)) {
+      backup = `${staging}-previous`;
+      renameSync(destination, backup);
+    }
+    try { renameSync(staging, destination); }
+    catch (error) { if (backup) { renameSync(backup, destination); backup = undefined; } throw error; }
+    staging = undefined;
+    committed = true;
+    return version;
+  } finally {
+    if (staging) rmSync(staging, { recursive: true, force: true });
+    // Never delete the recovery copy if restoring the old destination failed.
+    if (backup && committed) rmSync(backup, { recursive: true, force: true });
+    rmSync(lock, { recursive: true, force: true });
+  }
+}