High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix(npm): stamp the shipped skill with version and content hash, report each agent copy on install, keep an edited copy, and add pinchtab skill status (PIN-286)
Luigi Agosti71ac9ae12ba0
diff --git a/README.md b/README.mdindex f6b54d53..e0d0ccad 100644--- a/README.md+++ b/README.md@@ -211,6 +211,18 @@ brew install pinchtab/tap/pinchtabnpm install -g pinchtab```+### Agent skill++The npm package ships the `pinchtab` agent skill and copies it into every agent home it detects (`~/.claude/skills`, `~/.cursor/skills`, `~/.windsurf/skills`, `~/.codex/skills`, OpenClaw) on install and upgrade, printing what it wrote. The shipped copy carries the release version and a content hash in its frontmatter, so a stale or hand-edited copy is detectable without a source checkout:++```bash+pinchtab skill status # each detected copy vs the bundled skill; exit 1 if any is stale+pinchtab skill update # install or refresh; an edited copy is kept and reported+pinchtab skill update --force # replace an edited copy+```++Inside a checkout, `scripts/install-skills.sh` symlinks the repo skills instead so edits are live; the sync never writes through a symlink.+### Platform SupportPinchTab's primary tested operator workflow is local macOS and Linux.diff --git a/internal/mcp/skill_click_contract_test.go b/internal/mcp/skill_click_contract_test.goindex d3066688..f7a57451 100644--- a/internal/mcp/skill_click_contract_test.go+++ b/internal/mcp/skill_click_contract_test.go@@ -16,6 +16,9 @@ const clickDocPath = "docs/reference/click.md"// release because only the docs were ever listed in a contract-changing card's// footprint. This guard is the answer to that: the skills are checked AGAINST the// docs, so the next contract change reds here instead of shipping stale guidance.+// It reads the working tree, so it proves the shipped source and nothing about a+// copy installed in an agent home; that half is covered by the version stamp the+// npm package writes at staging and by `pinchtab skill status` (npm/scripts/sync-skills.js).var clickContractSkills = []string{"skills/pinchtab/SKILL.md", "skills/pinchtab-mcp/SKILL.md"}// clickContractBanned are statements the contract no longer produces. An agentdiff --git a/npm/README.md b/npm/README.mdindex b541e126..d50fe0e8 100644--- a/npm/README.md+++ b/npm/README.md@@ -155,6 +155,10 @@ pinchtab --versionpinchtab --help```+### Agent skill++The package bundles the `pinchtab` agent skill, stamped with the release version and a content hash, and syncs it into detected agent homes on install and upgrade, printing what it wrote. `pinchtab skill status` reports each copy against the bundled one (exit 1 if any is stale) and `pinchtab skill update` refreshes them; a copy you edited is kept unless you pass `--force`.+### Shell CompletionAfter installing the CLI globally, you can generate shell completions:diff --git a/npm/bin/pinchtab b/npm/bin/pinchtabindex 39ab7565..79cbe99a 100755--- a/npm/bin/pinchtab+++ b/npm/bin/pinchtab@@ -25,58 +25,33 @@ function getBinaryPath() {return platform.resolveManagedBinaryPath(__dirname);}-// Handle `pinchtab skill update` at the Node.js level (no Go binary needed)+// `pinchtab skill ...` is answered at the Node.js level: the skill ships in the+// npm package, not in the Go binary.const args = process.argv.slice(2);-if (args[0] === 'skill' && (args[1] === 'update' || args[1] === 'sync')) {+if (args[0] === 'skill' && ['update', 'sync', 'status', 'list'].includes(args[1])) {+ const check = args[1] === 'status' || args[1] === 'list';try {- const { syncSkills } = require('../scripts/sync-skills');- console.log('Syncing Pinchtab skill files...\n');- const { updated, skipped } = syncSkills({ verbose: true });-- if (updated.length > 0) {- console.log(`\n✓ Updated ${updated.length} skill director${updated.length === 1 ? 'y' : 'ies'}`);- } else {- console.log('\nNo agent skill directories found to update.');- console.log('Skill directories are synced only where agents are already installed.');- }-- if (skipped.length > 0) {- console.log(`⚠ Skipped ${skipped.length} (permission errors)`);- }- } catch (err) {- console.error(`Failed to sync skills: ${err.message}`);- process.exit(1);- }- process.exit(0);-}--if (args[0] === 'skill' && args[1] === 'list') {- try {- const { getTargetSkillDirs, getBundledSkillsDir } = require('../scripts/sync-skills');- const bundled = getBundledSkillsDir();- console.log(`Bundled skills: ${fs.existsSync(bundled) ? bundled : '(not found)'}`);- console.log('\nDetected agent skill directories:');- const targets = getTargetSkillDirs();- if (targets.length === 0) {- console.log(' (none found)');- } else {- targets.forEach((t) => {- const exists = fs.existsSync(t);- console.log(` ${exists ? '●' : '○'} ${t}${exists ? '' : ' (will be created on sync)'}`);- });- }+ const { syncSkills, formatReport, isOutOfDate } = require('../scripts/sync-skills');+ const outcome = syncSkills({ check, force: args.includes('--force') });+ console.log(formatReport(outcome).join('\n'));+ const failed = outcome.results.some((r) => r.action === 'failed');+ const outOfDate = check && outcome.results.some(isOutOfDate);+ process.exit(failed || outOfDate ? 1 : 0);} catch (err) {- console.error(`Failed to list skills: ${err.message}`);+ console.error(`Failed to ${check ? 'check' : 'sync'} skills: ${err.message}`);process.exit(1);}- process.exit(0);}if (args[0] === 'skill') {console.log('Usage: pinchtab skill <command>\n');console.log('Commands:');- console.log(' update Sync bundled skill files to agent directories');- console.log(' list Show detected agent skill directories');+ console.log(+ ' status Report each detected agent copy against the bundled skill (exit 1 if any is stale)'+ );+ console.log(+ ' update [--force] Install or refresh the bundled skill in detected agent homes; --force replaces an edited copy'+ );process.exit(0);}diff --git a/npm/scripts/stage-skills.js b/npm/scripts/stage-skills.jsindex 38aedad9..8a3cfdee 100644--- a/npm/scripts/stage-skills.js+++ b/npm/scripts/stage-skills.js@@ -2,6 +2,7 @@const fs = require('fs');const path = require('path');+const { stampSkill } = require('./sync-skills');const SKILL_NAME = 'pinchtab';const sourceDir = path.join(__dirname, '..', '..', 'skills', SKILL_NAME);@@ -31,11 +32,14 @@ function stageSkills() {fs.rmSync(targetDir, { recursive: true, force: true });copyDirSync(sourceDir, targetDir);+ return stampSkill(targetDir, require('../package.json').version);}if (require.main === module) {- stageSkills();- console.log(`Staged ${SKILL_NAME} skill into npm package`);+ const stamp = stageSkills();+ console.log(+ `Staged ${SKILL_NAME} skill ${stamp.version} (${stamp.contentHash}) into npm package`+ );}module.exports = { stageSkills };diff --git a/npm/scripts/sync-skills.js b/npm/scripts/sync-skills.jsindex a573f684..befeeb39 100644--- a/npm/scripts/sync-skills.js+++ b/npm/scripts/sync-skills.js@@ -1,74 +1,143 @@#!/usr/bin/env node/**- * Syncs bundled skill files to detected agent skill directories.- * Only updates directories that already exist (doesn't create new ones).+ * The USER path for the pinchtab agent skill: copies the skill bundled in the npm+ * package into every detected agent home, and reports whether each copy matches+ * the bundled one. Runs on npm install/update (postinstall) and on+ * `pinchtab skill update`; `pinchtab skill status` reports without writing.*- * Used by:- * - postinstall (automatic on npm install/update)- * - `pinchtab skill update` (manual trigger)+ * In a source checkout use scripts/install-skills.sh instead: it symlinks the+ * repo skills so edits are reflected immediately. A symlinked target is never+ * written to here.*/+const crypto = require('crypto');const fs = require('fs');-const path = require('path');const os = require('os');+const path = require('path');const SKILL_NAME = 'pinchtab';+const DEV_VERSION = 'dev';++const stampBlock = /^ {2}pinchtab:\n {4}version: .*\n {4}contentHash: .*\n/m;+const stampFields = /^ {2}pinchtab:\n {4}version: (.*)\n {4}contentHash: (.*)\n/m;-/**- * Returns the path to the bundled skills directory inside the npm package.- */function getBundledSkillsDir() {const packagedDir = path.join(__dirname, '..', 'skills', SKILL_NAME);if (fs.existsSync(packagedDir)) {return packagedDir;}-- // In a source checkout, fall back to the repo-root skill so local development- // does not depend on prepack having staged npm/skills first.return path.join(__dirname, '..', '..', 'skills', SKILL_NAME);}-/**- * Returns candidate agent skill directories to sync to.- * Only returns paths whose parent directory already exists.- */function getTargetSkillDirs() {const home = os.homedir();-const candidates = [- // Claude Code / Claude Desktoppath.join(home, '.claude', 'skills', SKILL_NAME),- // OpenClawpath.join(home, '.openclaw', 'workspace', '.agents', 'skills', SKILL_NAME),- // Cursorpath.join(home, '.cursor', 'skills', SKILL_NAME),- // Windsurfpath.join(home, '.windsurf', 'skills', SKILL_NAME),- // Codexpath.join(home, '.codex', 'skills', SKILL_NAME),];+ return candidates.filter((dir) => fs.existsSync(path.dirname(dir)));+}- return candidates.filter((dir) => {- // Check if the parent skills directory exists- const parentDir = path.dirname(dir);- return fs.existsSync(parentDir);- });+function listFiles(dir, prefix = '') {+ const names = [];+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {+ if (entry.name === '.DS_Store') {+ continue;+ }+ const rel = prefix ? `${prefix}/${entry.name}` : entry.name;+ if (entry.isDirectory()) {+ names.push(...listFiles(path.join(dir, entry.name), rel));+ } else {+ names.push(rel);+ }+ }+ return names.sort();}-/**- * Recursively copies a directory.- */-function copyDirSync(src, dest) {- if (!fs.existsSync(dest)) {- fs.mkdirSync(dest, { recursive: true });+function stripStamp(skillMd) {+ return skillMd.replace(stampBlock, '').replace(/^metadata:\n(?=\S)/m, '');+}++function readStamp(skillDir) {+ const skillPath = path.join(skillDir, 'SKILL.md');+ if (!fs.existsSync(skillPath)) {+ return null;+ }+ const match = stampFields.exec(fs.readFileSync(skillPath, 'utf8'));+ if (!match) {+ return null;+ }+ return { version: match[1].trim(), contentHash: match[2].trim() };+}++function contentHash(skillDir) {+ const hash = crypto.createHash('sha256');+ for (const rel of listFiles(skillDir)) {+ hash.update(rel);+ hash.update('\0');+ const body = fs.readFileSync(path.join(skillDir, rel));+ hash.update(rel === 'SKILL.md' ? stripStamp(body.toString('utf8')) : body);+ hash.update('\0');+ }+ return `sha256:${hash.digest('hex')}`;+}++function stampSkill(skillDir, version) {+ const skillPath = path.join(skillDir, 'SKILL.md');+ const stamp = { version, contentHash: contentHash(skillDir) };+ const block = ` pinchtab:\n version: ${stamp.version}\n contentHash: ${stamp.contentHash}\n`;+ let body = stripStamp(fs.readFileSync(skillPath, 'utf8'));+ if (/^metadata:\n/m.test(body)) {+ body = body.replace(/^metadata:\n/m, `metadata:\n${block}`);+ } else {+ body = body.replace(/^---\n([\s\S]*?)^---\n/m, `---\n$1metadata:\n${block}---\n`);+ }+ fs.writeFileSync(skillPath, body);+ return stamp;+}++function describeBundle(bundledDir) {+ const stamp = readStamp(bundledDir);+ return {+ dir: bundledDir,+ version: stamp ? stamp.version : DEV_VERSION,+ contentHash: stamp ? stamp.contentHash : contentHash(bundledDir),+ };+}++function inspectTarget(target, bundle) {+ let stat;+ try {+ stat = fs.lstatSync(target);+ } catch {+ return { target, state: 'absent', installed: null };+ }+ if (stat.isSymbolicLink()) {+ return { target, state: 'symlink', installed: null };+ }+ const installed = readStamp(target);+ const actual = contentHash(target);+ if (actual === bundle.contentHash) {+ return { target, state: 'current', installed };+ }+ if (!installed) {+ return { target, state: 'unversioned', installed };+ }+ if (actual !== installed.contentHash) {+ return { target, state: 'edited', installed };}+ return { target, state: 'stale', installed };+}- const entries = fs.readdirSync(src, { withFileTypes: true });- for (const entry of entries) {+function copyDirSync(src, dest) {+ fs.mkdirSync(dest, { recursive: true });+ for (const entry of fs.readdirSync(src, { withFileTypes: true })) {const srcPath = path.join(src, entry.name);const destPath = path.join(dest, entry.name);-if (entry.isDirectory()) {copyDirSync(srcPath, destPath);} else {@@ -77,69 +146,116 @@ function copyDirSync(src, dest) {}}-/**- * Syncs bundled skills to all detected agent directories.- * @param {object} options- * @param {boolean} options.verbose - Print detailed output- * @returns {{ updated: string[], skipped: string[] }}- */-function syncSkills({ verbose = false } = {}) {- const bundledDir = getBundledSkillsDir();- const updated = [];- const skipped = [];-- if (!fs.existsSync(bundledDir)) {- if (verbose) {- console.error(`⚠ Bundled skills not found at ${bundledDir}`);- }- return { updated, skipped };+function replaceSkill(bundle, target) {+ fs.rmSync(target, { recursive: true, force: true });+ copyDirSync(bundle.dir, target);+ if (!readStamp(target)) {+ stampSkill(target, bundle.version);}+}- const targets = getTargetSkillDirs();+const writesFor = {+ absent: () => 'installed',+ stale: () => 'updated',+ edited: (force) => (force ? 'updated' : 'kept'),+ unversioned: (force) => (force ? 'updated' : 'kept'),+ current: () => 'unchanged',+ symlink: () => 'unchanged',+};- if (targets.length === 0) {- if (verbose) {- console.log('No agent skill directories detected. Nothing to sync.');- }- return { updated, skipped };+function syncSkills({ force = false, check = false, bundledDir = getBundledSkillsDir() } = {}) {+ if (!fs.existsSync(bundledDir)) {+ throw new Error(`bundled skill not found at ${bundledDir}`);}-- for (const target of targets) {- try {- copyDirSync(bundledDir, target);- updated.push(target);- if (verbose) {- console.log(` ✓ ${target}`);- }- } catch (err) {- skipped.push(target);- if (verbose) {- console.warn(` ✗ ${target}: ${err.message}`);+ const bundle = describeBundle(bundledDir);+ const results = getTargetSkillDirs().map((target) => {+ const found = inspectTarget(target, bundle);+ const action = check ? 'checked' : writesFor[found.state](force);+ if (action === 'installed' || action === 'updated') {+ try {+ replaceSkill(bundle, target);+ } catch (err) {+ return { ...found, action: 'failed', error: err.message };}}- }+ return { ...found, action };+ });+ return { bundle, results };+}- return { updated, skipped };+function isOutOfDate(result) {+ return result.state === 'stale' || result.state === 'edited' || result.state === 'unversioned';}-// If run directly (not required as module)-if (require.main === module) {- const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');- console.log('Syncing Pinchtab skill files...\n');- const { updated, skipped } = syncSkills({ verbose });+function shortHash(contentHash) {+ return contentHash.replace(/^sha256:/, '').slice(0, 12);+}- if (updated.length > 0) {- console.log(- `\n✓ Updated ${updated.length} skill director${updated.length === 1 ? 'y' : 'ies'}`- );- } else {- console.log('\nNo agent skill directories found to update.');- console.log('Skill directories are synced only where agents are already installed.');+function describeResult(result, bundle) {+ const from = result.installed ? result.installed.version : 'unversioned';+ switch (result.action) {+ case 'installed':+ return `installed ${bundle.version}`;+ case 'updated':+ return `updated ${from} -> ${bundle.version}`;+ case 'failed':+ return `failed: ${result.error}`;+ default:+ break;}+ switch (result.state) {+ case 'current':+ return `current (${bundle.version})`;+ case 'symlink':+ return 'symlink to a checkout; left alone (scripts/install-skills.sh manages it)';+ case 'stale':+ return `stale ${from}; run: pinchtab skill update`;+ case 'edited':+ return `edited locally since ${from}; kept. Replace it with: pinchtab skill update --force`;+ case 'unversioned':+ return 'unversioned copy that differs from the bundled skill; kept. Replace it with: pinchtab skill update --force';+ case 'absent':+ return `not installed; run: pinchtab skill update`;+ default:+ return result.state;+ }+}- if (skipped.length > 0) {- console.log(`⚠ Skipped ${skipped.length} (permission errors)`);+function formatReport({ bundle, results }) {+ const lines = [`pinchtab skill ${bundle.version} (${shortHash(bundle.contentHash)})`];+ if (results.length === 0) {+ lines.push(+ ' no agent skill directories detected; the skill is synced only where an agent is already installed'+ );+ return lines;+ }+ for (const result of results) {+ lines.push(` ${result.target}: ${describeResult(result, bundle)}`);}+ return lines;+}++if (require.main === module) {+ const argv = process.argv.slice(2);+ const outcome = syncSkills({+ force: argv.includes('--force'),+ check: argv.includes('--check'),+ });+ console.log(formatReport(outcome).join('\n'));+ const failed = outcome.results.some((r) => r.action === 'failed');+ const outOfDate = outcome.results.some(isOutOfDate);+ process.exit(failed || (argv.includes('--check') && outOfDate) ? 1 : 0);}-module.exports = { syncSkills, getTargetSkillDirs, getBundledSkillsDir };+module.exports = {+ SKILL_NAME,+ syncSkills,+ formatReport,+ isOutOfDate,+ getTargetSkillDirs,+ getBundledSkillsDir,+ contentHash,+ stampSkill,+ readStamp,+ stripStamp,+};diff --git a/npm/src/postinstall.ts b/npm/src/postinstall.tsindex fe1db5fd..7020f929 100644--- a/npm/src/postinstall.ts+++ b/npm/src/postinstall.ts@@ -3,11 +3,13 @@ import * as path from 'path';import { ensureBinary } from './download';import { getCheckoutBinaryPath } from './platform';-interface SkillSyncResult {- updated: string[];+interface SkillSync {+ syncSkills: (opts: { force?: boolean; check?: boolean }) => unknown;+ formatReport: (outcome: unknown) => string[];}-// syncBundledSkills mirrors bundled skill files into detected agent directories.+// syncBundledSkills is the npm user path for the agent skill: it writes into the+// user's agent homes as an install side effect, so it always prints what it did.// Non-fatal: a sync failure must never block the install. sync-skills is a// CommonJS script shipped alongside the package, loaded relative to the compiled// location (dist/src -> ../../scripts).@@ -15,17 +17,11 @@ function syncBundledSkills(): void {try {const syncSkillsPath = path.join(__dirname, '..', '..', 'scripts', 'sync-skills');// eslint-disable-next-line @typescript-eslint/no-require-imports- const { syncSkills } = require(syncSkillsPath) as {- syncSkills: (opts: { verbose: boolean }) => SkillSyncResult;- };- const { updated } = syncSkills({ verbose: false });- if (updated.length > 0) {- console.log(- `✓ Synced skill files to ${updated.length} agent director${updated.length === 1 ? 'y' : 'ies'}`- );- }- } catch (_err) {- // Non-fatal: skill sync failure shouldn't block install+ const { syncSkills, formatReport } = require(syncSkillsPath) as SkillSync;+ console.log(formatReport(syncSkills({})).join('\n'));+ } catch (err) {+ console.warn(`⚠ Skill sync skipped: ${err instanceof Error ? err.message : String(err)}`);+ console.warn(' Retry with: pinchtab skill update');}}diff --git a/npm/tests/skill-distribution.test.ts b/npm/tests/skill-distribution.test.tsnew file mode 100644index 00000000..83236528--- /dev/null+++ b/npm/tests/skill-distribution.test.ts@@ -0,0 +1,235 @@+/**+ * 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));+ });+});diff --git a/scripts/README.md b/scripts/README.mdindex 2143bdde..8fa30776 100644--- a/scripts/README.md+++ b/scripts/README.md@@ -39,7 +39,7 @@ Development and CI scripts for PinchTab.|--------|---------|| `doctor.sh` | Verify & setup dev environment (interactive — prompts before installing) || `install-hooks.sh` | Install git pre-commit hook |-| `install-skills.sh` | Symlink repo skills into `./.claude/skills` by default; set `CLAUDE_SKILLS_DIR=~/.claude/skills` for a global install |+| `install-skills.sh` | Developer path for the agent skills: symlink repo skills into `./.claude/skills` by default; set `CLAUDE_SKILLS_DIR=~/.claude/skills` for a global install. Users of an installed binary use `pinchtab skill update` (npm package) instead |## Testingdiff --git a/scripts/install-skills.sh b/scripts/install-skills.shindex 7afd3c55..29754a2b 100755--- a/scripts/install-skills.sh+++ b/scripts/install-skills.sh@@ -1,8 +1,13 @@#!/usr/bin/env bash-# Symlink every skill under ./skills into ./.claude/skills so Claude Code-# picks them up as repo-local skills (loaded only when CWD is inside this-# repo). Editing files under ./skills/<name>/ is reflected immediately-# because we use symlinks.+# The DEVELOPER path for the skills: symlinks every skill under ./skills into+# ./.claude/skills so Claude Code picks them up as repo-local skills (loaded+# only when CWD is inside this repo), and edits under ./skills/<name>/ are+# reflected immediately. It needs a checkout.+#+# Users of an installed binary have no checkout: the npm package ships a copy+# of the pinchtab skill and `pinchtab skill update` / `pinchtab skill status`+# (npm/scripts/sync-skills.js) manage it. That sync never writes through a+# symlink, so the two paths do not fight over one directory.## Override the target directory with CLAUDE_SKILLS_DIR=<path> if you want# to install into a different Claude home (e.g. ~/.claude/skills for a