Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

9.6 KB
Raw Blame
/**
 * Skill distribution: the npm user path (scripts/sync-skills.js).
 *
 * The skill an agent loads is a copy in an agent home, so a stale copy teaches a
 * contract the server no longer produces. These tests drive the sync against a
 * fake HOME and a fake bundle and pin: the stamp, the hash that ignores the
 * stamp, install / refresh / keep-an-edited-copy / leave-a-symlink, and that
 * status mode writes nothing.
 */

import { describe, test, beforeEach, afterEach } from 'node:test';
import * as assert from 'node:assert';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';

// eslint-disable-next-line @typescript-eslint/no-require-imports
const sync = require('../../scripts/sync-skills') as {
  syncSkills: (opts: { force?: boolean; check?: boolean; bundledDir: string }) => Outcome;
  formatReport: (outcome: Outcome) => string[];
  isOutOfDate: (result: Result) => boolean;
  contentHash: (dir: string) => string;
  stampSkill: (dir: string, version: string) => { version: string; contentHash: string };
  readStamp: (dir: string) => { version: string; contentHash: string } | null;
};

interface Result {
  target: string;
  state: string;
  action: string;
  installed: { version: string; contentHash: string } | null;
}
interface Outcome {
  bundle: { dir: string; version: string; contentHash: string };
  results: Result[];
}

const skillMd = (body: string) =>
  `---\nname: pinchtab\ndescription: "browser control"\nmetadata:\n  openclaw:\n    requires:\n      bins:\n        - pinchtab\n---\n\n${body}\n`;

let root: string;
let savedHome: string | undefined;

function writeBundle(name: string, body: string, version: string): string {
  const dir = path.join(root, name);
  fs.mkdirSync(path.join(dir, 'references'), { recursive: true });
  fs.writeFileSync(path.join(dir, 'SKILL.md'), skillMd(body));
  fs.writeFileSync(path.join(dir, 'references', 'commands.md'), `# commands\n${body}\n`);
  sync.stampSkill(dir, version);
  return dir;
}

function claudeSkillDir(): string {
  const skills = path.join(root, 'home', '.claude', 'skills');
  fs.mkdirSync(skills, { recursive: true });
  return path.join(skills, 'pinchtab');
}

function only(outcome: Outcome): Result {
  assert.strictEqual(outcome.results.length, 1, JSON.stringify(outcome.results));
  return outcome.results[0];
}

beforeEach(() => {
  root = fs.mkdtempSync(path.join(os.tmpdir(), 'pinchtab-skill-sync-'));
  savedHome = process.env.HOME;
  process.env.HOME = path.join(root, 'home');
  fs.mkdirSync(process.env.HOME, { recursive: true });
});

afterEach(() => {
  process.env.HOME = savedHome;
  fs.rmSync(root, { recursive: true, force: true });
});

describe('the version stamp', () => {
  test('lands under metadata and hashes the content it is not part of', () => {
    const dir = writeBundle('bundle', 'click navigates: OK navigated', '1.2.3');
    const stamped = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8');
    assert.match(
      stamped,
      /^metadata:\n {2}pinchtab:\n {4}version: 1\.2\.3\n {4}contentHash: sha256:[0-9a-f]{64}\n {2}openclaw:/m
    );
    assert.deepStrictEqual(sync.readStamp(dir), {
      version: '1.2.3',
      contentHash: sync.contentHash(dir),
    });

    const restamped = sync.stampSkill(dir, '9.9.9');
    assert.strictEqual(
      restamped.contentHash,
      sync.contentHash(dir),
      'restamping must not move the hash'
    );
    assert.strictEqual(sync.readStamp(dir)?.version, '9.9.9');
  });

  test('is added to a frontmatter with no metadata block', () => {
    const dir = path.join(root, 'bare');
    fs.mkdirSync(dir);
    fs.writeFileSync(path.join(dir, 'SKILL.md'), '---\nname: pinchtab\n---\n\nbody\n');
    sync.stampSkill(dir, '0.1.0');
    assert.deepStrictEqual(sync.readStamp(dir), {
      version: '0.1.0',
      contentHash: sync.contentHash(dir),
    });
    assert.match(
      fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8'),
      /^---\nname: pinchtab\nmetadata:\n {2}pinchtab:\n/
    );
  });

  test('changes with any file in the tree, not just SKILL.md', () => {
    const dir = writeBundle('bundle', 'v1', '1.0.0');
    const before = sync.contentHash(dir);
    fs.appendFileSync(path.join(dir, 'references', 'commands.md'), 'nav --timeout <seconds>\n');
    assert.notStrictEqual(sync.contentHash(dir), before);
  });
});

describe('pinchtab skill update', () => {
  test('detects nothing when no agent home exists', () => {
    const bundledDir = writeBundle('bundle', 'v1', '1.0.0');
    const outcome = sync.syncSkills({ bundledDir });
    assert.deepStrictEqual(outcome.results, []);
    assert.match(sync.formatReport(outcome).join('\n'), /no agent skill directories detected/);
  });

  test('installs into a detected home and the copy carries the bundled stamp', () => {
    const bundledDir = writeBundle('bundle', 'v1', '1.0.0');
    const target = claudeSkillDir();
    const result = only(sync.syncSkills({ bundledDir }));
    assert.strictEqual(result.action, 'installed');
    assert.deepStrictEqual(sync.readStamp(target), sync.readStamp(bundledDir));
    assert.strictEqual(
      fs.readFileSync(path.join(target, 'references', 'commands.md'), 'utf8'),
      '# commands\nv1\n'
    );
    assert.strictEqual(only(sync.syncSkills({ bundledDir })).action, 'unchanged');
  });

  test('refreshes an untouched copy of an older bundle and drops files the new bundle removed', () => {
    const target = claudeSkillDir();
    only(sync.syncSkills({ bundledDir: writeBundle('old', 'treat 409 as success', '0.9.0') }));
    fs.writeFileSync(path.join(target, 'references', 'gone.md'), 'obsolete\n');
    const stale = sync.stampSkill(target, '0.9.0');
    assert.strictEqual(sync.readStamp(target)?.contentHash, stale.contentHash);

    const bundledDir = writeBundle('new', 'OK navigated; JSON adds refsStale', '1.0.0');
    const result = only(sync.syncSkills({ bundledDir }));
    assert.strictEqual(result.state, 'stale');
    assert.strictEqual(result.action, 'updated');
    assert.strictEqual(result.installed?.version, '0.9.0');
    assert.match(fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8'), /refsStale/);
    assert.ok(!fs.existsSync(path.join(target, 'references', 'gone.md')));
    assert.match(
      sync.formatReport(sync.syncSkills({ bundledDir, check: true })).join('\n'),
      /current \(1\.0\.0\)/
    );
  });

  test('keeps a copy the user edited, says so, and replaces it only under --force', () => {
    const bundledDir = writeBundle('bundle', 'v1', '1.0.0');
    const target = claudeSkillDir();
    only(sync.syncSkills({ bundledDir }));
    fs.appendFileSync(path.join(target, 'SKILL.md'), '\nMy own note.\n');
    const newer = writeBundle('newer', 'v2', '1.1.0');

    const keptOutcome = sync.syncSkills({ bundledDir: newer });
    const kept = only(keptOutcome);
    assert.strictEqual(kept.state, 'edited');
    assert.strictEqual(kept.action, 'kept');
    assert.match(fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8'), /My own note/);
    assert.match(
      sync.formatReport(keptOutcome).join('\n'),
      /edited locally since 1\.0\.0.*--force/
    );

    const forced = only(sync.syncSkills({ bundledDir: newer, force: true }));
    assert.strictEqual(forced.action, 'updated');
    assert.doesNotMatch(fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8'), /My own note/);
    assert.strictEqual(sync.readStamp(target)?.version, '1.1.0');
  });

  test('keeps an unversioned copy that differs, since it cannot tell edited from stale', () => {
    const target = claudeSkillDir();
    fs.mkdirSync(target, { recursive: true });
    fs.writeFileSync(path.join(target, 'SKILL.md'), skillMd('treat 409 as success'));
    const result = only(sync.syncSkills({ bundledDir: writeBundle('bundle', 'v1', '1.0.0') }));
    assert.strictEqual(result.state, 'unversioned');
    assert.strictEqual(result.action, 'kept');
    assert.ok(sync.isOutOfDate(result));
    assert.match(fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8'), /409/);
  });

  test('never writes through a symlink, which is the developer path', () => {
    const checkout = writeBundle('checkout', 'edited live', '1.0.0');
    const target = claudeSkillDir();
    fs.symlinkSync(checkout, target);
    const result = only(
      sync.syncSkills({ bundledDir: writeBundle('bundle', 'v2', '2.0.0'), force: true })
    );
    assert.strictEqual(result.state, 'symlink');
    assert.strictEqual(result.action, 'unchanged');
    assert.ok(fs.lstatSync(target).isSymbolicLink());
    assert.match(fs.readFileSync(path.join(checkout, 'SKILL.md'), 'utf8'), /edited live/);
  });
});

describe('pinchtab skill status', () => {
  test('reports a stale copy without touching it', () => {
    const target = claudeSkillDir();
    only(sync.syncSkills({ bundledDir: writeBundle('old', 'v1', '0.9.0') }));
    const before = fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8');
    const outcome = sync.syncSkills({ bundledDir: writeBundle('new', 'v2', '1.0.0'), check: true });
    const result = only(outcome);
    assert.strictEqual(result.state, 'stale');
    assert.strictEqual(result.action, 'checked');
    assert.ok(sync.isOutOfDate(result));
    assert.strictEqual(fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8'), before);
    assert.match(
      sync.formatReport(outcome).join('\n'),
      /stale 0\.9\.0; run: pinchtab skill update/
    );
  });

  test('a bundle without a stamp reads as the dev version', () => {
    const dir = path.join(root, 'src');
    fs.mkdirSync(dir);
    fs.writeFileSync(path.join(dir, 'SKILL.md'), skillMd('from a checkout'));
    const outcome = sync.syncSkills({ bundledDir: dir, check: true });
    assert.strictEqual(outcome.bundle.version, 'dev');
    assert.strictEqual(outcome.bundle.contentHash, sync.contentHash(dir));
  });
});