Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.7 KB
Raw Blame
/**
 * `gbrain skillpack reference` — read-only diff lens + --apply-clean-hunks.
 *
 * Peeled from src/commands/skillpack.ts (module-size ratchet). Behavior is
 * unchanged from the façade version. Flag-registry note: this file is scanned
 * for skillpack's flag allowlist — spell foreign (non-skillpack) CLI flags
 * WITHOUT leading dashes in comments and strings.
 */

import { BundleError } from '../../core/skillpack/bundle.ts';
import {
  runReference,
  runReferenceAll,
  runReferenceApply,
} from '../../core/skillpack/reference.ts';
import { findGbrainOrDie, resolveWorkspace } from './shared.ts';
import { strictArgsRefusal } from '../../cli/strict-args.ts';
import { exitCliError } from '../../cli/cli-error.ts';

const REFERENCE_HELP =
  'gbrain skillpack reference <name> [--workspace PATH] [--apply-clean-hunks [--dry-run]] [--json]\n' +
  'gbrain skillpack reference --all [--workspace PATH] [--since <version>] [--json]\n' +
  'gbrain skillpack reference <name>|--all --update-untouched [--dry-run] ...   (see --update-untouched --help)\n\n' +
  '  <name>              Read-only diff of gbrain\'s bundle against your local copy.\n' +
  '  --update-untouched  Replace whole skills you never edited with gbrain\'s version,\n' +
  '                      journaled and restorable (gbrain skillpack restore <id>).\n' +
  '  --apply-clean-hunks Two-way merge: align non-conflicting hunks of ONE skill to\n' +
  '                      gbrain. Local edits in those hunks are overwritten; pass the\n' +
  '                      exact --dry-run flag to preview without writing.\n' +
  '  --all               Sweep over every bundled skill (read-only; never applies).\n' +
  '  --since <version>   With --all, restrict the sweep to skills whose source\n' +
  '                      changed in gbrain between <version> and HEAD. Useful\n' +
  '                      after `gbrain upgrade` to see only what moved.\n\n' +
  'Any other token, or a flag in a form this command does not read (`--dry-run=true`),\n' +
  'refuses with invalid_params before anything is touched.';

const ALL_APPLY_REFUSAL =
  'Error: --apply-clean-hunks is intentionally NOT supported with --all (a two-way merge over every\n' +
  'skill at once has no safe preview). Update path, one skill at a time:\n' +
  '  1. gbrain skillpack reference --all                  (which skills drifted)\n' +
  '  2. gbrain skillpack reference <name>                 (read the diff; keep intentional edits)\n' +
  '  3. gbrain skillpack reference <name> --apply-clean-hunks   (add --dry-run to preview first)';

export async function cmdReference(args: string[]): Promise<void> {
  // Safe whole-skill update of untouched installs (its own help, flags and exit codes).
  if (args.includes('--update-untouched')) {
    const { cmdUpdateUntouched } = await import('./update.ts');
    await cmdUpdateUntouched(args);
    return;
  }
  // Harness lane (cathedral-7): diff a harness install (stub-aware,
  // three-way local_edit vs upstream_drift) instead of a workspace.
  if (args.some(a => a === '--harness' || a.startsWith('--harness='))) {
    const { cmdReferenceHarness } = await import('./harness.ts');
    await cmdReferenceHarness(args);
    return;
  }
  if (args.includes('--help') || args.includes('-h')) {
    console.log(REFERENCE_HELP);
    process.exit(0);
  }
  // #5491: a token the command would ignore (`--dry-run=true`, a typo) must
  // not reach the apply. cli.ts refuses before dispatch; this re-check keeps
  // an in-process caller on the same contract.
  const refusal = strictArgsRefusal('skillpack', ['reference', ...args]);
  if (refusal) exitCliError(refusal, 'skillpack');
  const json = args.includes('--json');
  const apply = args.includes('--apply-clean-hunks');
  const dryRun = args.includes('--dry-run');
  const all = args.includes('--all');
  let name: string | null = null;
  let workspace: string | null = null;
  let since: string | null = null;
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (a === '--workspace') {
      workspace = args[i + 1] ?? null;
      i++;
    } else if (a?.startsWith('--workspace=')) {
      workspace = a.slice('--workspace='.length) || null;
    } else if (a === '--since') {
      since = args[i + 1] ?? null;
      i++;
    } else if (a?.startsWith('--since=')) {
      since = a.slice('--since='.length) || null;
    } else if (a && !a.startsWith('--') && !name) {
      name = a;
    }
  }
  if (!all && !name) {
    console.error('Error: pass a skill name or --all.');
    process.exit(2);
  }

  const gbrainRoot = findGbrainOrDie();
  const targetWorkspace = resolveWorkspace({ workspace });

  try {
    if (apply) {
      if (all) {
        console.error(ALL_APPLY_REFUSAL);
        process.exit(2);
      }
      // Two-way merge warning fires BEFORE the apply. Goes to stderr so
      // it survives stdout redirection. Suppressed in --json mode so
      // machine consumers (CI, agent scripts) get a clean envelope; the
      // human-facing reason for the warning is documented in the JSON
      // output's `framing` field already, and the docstring on the
      // command-help covers it.
      const twoWayWarning =
        'WARNING: --apply-clean-hunks is a two-way diff against gbrain\'s CURRENT bundle.\n' +
        '         gbrain does NOT have access to the version you originally scaffolded.\n' +
        '         Hunks where your LOCAL edits differ from gbrain WILL be aligned to gbrain.\n' +
        '         If you have intentional local edits, run `gbrain skillpack reference ' + name + '`\n' +
        '         (read-only) first to inspect, OR pass --dry-run on this command.';
      if (!dryRun && !json) console.error(twoWayWarning);

      const result = runReferenceApply({ gbrainRoot, targetWorkspace, skillSlug: name!, dryRun });
      if (json) console.log(JSON.stringify(result, null, 2));
      else {
        console.log(result.framing);
        console.log(
          `reference --apply-clean-hunks: ${result.summary.totalHunksApplied} hunk(s) applied, ${result.summary.totalHunksConflicted} conflict(s)`,
        );
        for (const f of result.files) {
          if (f.status === 'identical') continue;
          console.log(`  ${f.status.padEnd(15)} ${f.target}`);
          for (const c of f.conflicts) console.log(`    ${c}`);
        }
        if (result.summary.totalHunksConflicted > 0) {
          console.log(
            '\nConflicts left in place. Run `gbrain skillpack reference ' + name + '` to inspect\nthe unified diffs and patch by hand. The conflict_missing / conflict_ambiguous\nlabels above indicate WHY the hunk could not be applied automatically.',
          );
        }
      }
      process.exit(0);
    }

    if (all) {
      const result = runReferenceAll({ gbrainRoot, targetWorkspace });
      // --since filter: keep only skills whose source changed in gbrain
      // since the given version. Falls back loudly when git can't resolve
      // the ref (tarball install, missing tag, etc).
      let sinceFilter: Set<string> | null = null;
      if (since) {
        const { changedSlugsSinceVersion } = await import('../../core/skillpack/bundle.ts');
        const slugs = changedSlugsSinceVersion(gbrainRoot, since);
        if (slugs === null) {
          console.error(
            `warn: --since '${since}' could not be resolved (no git checkout, missing tag, or git error). Falling back to full sweep.`,
          );
        } else {
          sinceFilter = new Set(slugs);
        }
      }
      const filteredSkills = sinceFilter
        ? result.skills.filter(s => sinceFilter!.has(s.slug))
        : result.skills;
      const filtered = { ...result, skills: filteredSkills };
      if (json) console.log(JSON.stringify(filtered, null, 2));
      else {
        console.log(result.framing);
        if (since && sinceFilter) {
          console.log(`(filtered to ${filteredSkills.length} skill(s) changed since ${since})`);
        }
        if (filteredSkills.length === 0) {
          console.log('  (no skills changed in the requested window)');
        }
        for (const s of filteredSkills) {
          console.log(
            `  ${s.slug.padEnd(40)} identical:${s.summary.identical} differs:${s.summary.differs} missing:${s.summary.missing}`,
          );
        }
      }
      process.exit(0);
    }

    const result = runReference({ gbrainRoot, targetWorkspace, skillSlug: name! });
    if (json) console.log(JSON.stringify(result, null, 2));
    else {
      console.log(result.framing);
      console.log(
        `reference: identical:${result.summary.identical} differs:${result.summary.differs} missing:${result.summary.missing}`,
      );
      for (const f of result.files) {
        if (f.status === 'identical') continue;
        console.log(`\n  ${f.status.padEnd(10)} ${f.target}`);
        if (f.unifiedDiff) console.log(f.unifiedDiff);
      }
      // Per-category action hints for the agent.
      if (result.summary.missing > 0 || result.summary.differs > 0) {
        console.log('\nAgent decision policy per file:');
        if (result.summary.missing > 0) {
          console.log(
            '  missing → gbrain has a file you don\'t. Usually safe to `gbrain skillpack scaffold ' + name + '` again to land it.',
          );
        }
        if (result.summary.differs > 0) {
          console.log(
            '  differs → was your local edit intentional? Keep it (gbrain is reference, not law).\n            Accidental drift? Patch by hand, or `gbrain skillpack reference ' + name + ' --apply-clean-hunks`\n            (READ the two-way merge warning in that command\'s output first).',
          );
        }
      }
    }
    process.exit(0);
  } catch (err) {
    if (err instanceof BundleError) {
      console.error(`skillpack reference: ${err.message}`);
      process.exit(2);
    }
    throw err;
  }
}