claude-dev-env 7.2.1 → 7.4.0

package/bin/pstack.mjs

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const bundledLockPath = join(packageRoot, 'scripts', 'pstack.lock.json');
+const hosts = ['claude', 'codex', 'cursor'];
+const digest = value => createHash('sha256').update(value).digest('hex');
+const readJson = path => JSON.parse(readFileSync(path, 'utf8'));
+const json = value => JSON.stringify(value, null, 2) + '\n';
+const entryExists = path => { try { lstatSync(path); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; } };
+
+export function validateLock(lock) {
+    if (lock?.schemaVersion !== 1 || lock?.adapterVersion !== 1
+        || lock.repository !== 'https://github.com/cursor/plugins.git'
+        || !/^[0-9a-f]{40}$/.test(lock.commit ?? '')
+        || JSON.stringify(lock.components) !== JSON.stringify(['pstack', 'cursor-team-kit'])) {
+        throw new Error('Unsupported pstack lock. Update claude-dev-env for a newer adapter.');
+    }
+    const required = { pstack: ['poteto-mode'], 'cursor-team-kit': ['deslop', 'control-cli', 'control-ui'] };
+    for (const [component, names] of Object.entries(required)) {
+        const declared = lock.requiredSkills?.[component];
+        if (!Array.isArray(declared) || declared.some(name => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
+            || names.some(name => !declared.includes(name))) throw new Error(`Invalid ${component} dependencies`);
+    }
+    return lock;
+}
+
+function filesUnder(root) {
+    return readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap(entry => {
+        const path = join(root, entry.name);
+        if (entry.isSymbolicLink()) throw new Error(`Upstream symlinks require review: ${path}`);
+        if (entry.isDirectory()) return filesUnder(path);
+        if (!entry.isFile()) throw new Error(`Unsupported upstream file: ${path}`);
+        return [path];
+    });
+}
+
+function runGit(args, cwd) {
+    return execFileSync('git', args, {
+        cwd, encoding: 'utf8', timeout: 40000, maxBuffer: 16 * 1024 * 1024,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+}
+
+export function fetchUpstream(lock, destination) {
+    mkdirSync(destination, { recursive: true });
+    runGit(['init', '--quiet'], destination);
+    runGit(['config', 'core.autocrlf', 'false'], destination);
+    runGit(['config', 'core.hooksPath', join(destination, '.disabled-hooks')], destination);
+    runGit(['remote', 'add', 'origin', lock.repository], destination);
+    runGit(['config', 'core.sparseCheckout', 'true'], destination);
+    writeFileSync(join(destination, '.git', 'info', 'sparse-checkout'), '/pstack/\n/cursor-team-kit/\n/LICENSE\n');
+    runGit(['fetch', '--quiet', '--depth=1', '--filter=blob:none', 'origin', lock.commit], destination);
+    if (runGit(['rev-parse', 'FETCH_HEAD'], destination) !== lock.commit) throw new Error('Upstream commit mismatch');
+    runGit(['checkout', '--quiet', '--detach', 'FETCH_HEAD'], destination);
+}
+
+function adapterFiles(root) {
+    const adapters = join(root, 'scripts', 'pstack-adapters');
+    return Object.fromEntries([
+        ...['common.md', ...hosts.map(host => `host-${host}.md`), 'create-skill.md'].map(name => [name, join(adapters, name)]),
+        ...['pstack-host-mapping.md', 'pstack-models.md'].map(name => [name, join(root, 'rules', name)]),
+        ['select_pstack_models.mjs', join(root, 'scripts', 'select_pstack_models.mjs')],
+    ].map(([name, path]) => [name, readFileSync(path, 'utf8')]));
+}
+
+function adaptSkill(text, name, releaseRoot, skillRoot) {
+    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/);
+    if (!match || !/^description:\s*\S/m.test(match[1])) throw new Error(`Missing skill metadata: ${name}`);
+    const frontmatter = match[1].replace(/^name:.*$/m, `name: ${name}`);
+    if (!/^name:/m.test(frontmatter)) throw new Error(`Missing skill name: ${name}`);
+    const safeFrontmatter = frontmatter.replace(/^(?:context|agent|model):.*\r?\n?/gm, '');
+    const fork = /^context:\s*fork\s*$/m.test(frontmatter)
+        ? 'The upstream entry requests a fork. Delegate through the native host after reading the compatibility mapping.\n' : '';
+    return `---\n${safeFrontmatter}\n---\n\n## Host compatibility\n\n`
+        + `Read ${JSON.stringify(join(releaseRoot, 'compat', 'common.md'))} and the matching host file before following this workflow.\n`
+        + `Resolve this skill's relative paths from ${JSON.stringify(skillRoot)}. Read ${JSON.stringify(join(releaseRoot, 'release.json'))} for skill and agent paths.\n`
+        + fork + '\n' + match[2].trimStart();
+}
+
+export function prepareRelease(checkout, stage, finalRoot, lock, adapters) {
+    const skills = [];
+    const agents = [];
+    mkdirSync(join(stage, 'compat'), { recursive: true });
+    for (const [name, content] of Object.entries(adapters)) writeFileSync(join(stage, 'compat', name), content);
+    for (const component of lock.components) {
+        const source = join(checkout, component);
+        filesUnder(source);
+        cpSync(source, join(stage, 'upstream', component), { recursive: true });
+        cpSync(source, join(stage, 'runtime', component), { recursive: true });
+        rmSync(join(stage, 'runtime', component, '.cursor-plugin', 'plugin.json'), { force: true });
+        const skillHome = join(source, 'skills');
+        const names = readdirSync(skillHome).filter(name => existsSync(join(skillHome, name, 'SKILL.md'))).sort();
+        for (const name of lock.requiredSkills[component]) {
+            if (!names.includes(name)) throw new Error(`Missing dependency: ${component}:${name}`);
+        }
+        for (const slug of names) {
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) throw new Error(`Invalid skill directory: ${slug}`);
+            const name = `${component}-${slug}`;
+            const path = join('runtime', component, 'skills', slug);
+            const text = readFileSync(join(source, 'skills', slug, 'SKILL.md'), 'utf8');
+            writeFileSync(join(stage, path, 'SKILL.md'), adaptSkill(text, name, finalRoot, join(finalRoot, path)));
+            skills.push({ name, component, slug, path });
+        }
+        const agentHome = join(source, 'agents');
+        if (existsSync(agentHome)) {
+            for (const path of filesUnder(agentHome)) agents.push({ component, path: join('runtime', component, 'agents', relative(agentHome, path)) });
+        }
+    }
+    if (existsSync(join(checkout, 'LICENSE'))) cpSync(join(checkout, 'LICENSE'), join(stage, 'upstream', 'LICENSE'));
+    const creatorPath = join('runtime', 'cde-create-skill');
+    mkdirSync(join(stage, creatorPath), { recursive: true });
+    writeFileSync(join(stage, creatorPath, 'SKILL.md'), adapters['create-skill.md']);
+    skills.push({ name: 'cde-create-skill', component: 'cde', slug: 'create-skill', path: creatorPath });
+    const knownNames = new Set(skills.map(skill => `${skill.component}:${skill.slug}`));
+    for (const path of filesUnder(join(stage, 'upstream')).filter(path => path.endsWith('.md') && (path.includes(sep + 'skills' + sep) || path.includes(sep + 'agents' + sep)))) {
+        const references = readFileSync(path, 'utf8').matchAll(/\b(pstack|cursor-team-kit):([a-z][a-z0-9-]*)/g);
+        for (const [, component, slug] of references) {
+            if (!knownNames.has(`${component}:${slug}`)) throw new Error(`Unresolved skill dependency: ${component}:${slug}`);
+        }
+    }
+    const fileDigests = Object.fromEntries(filesUnder(stage).map(path => [relative(stage, path), digest(readFileSync(path))]));
+    const managedRoot = dirname(dirname(dirname(finalRoot)));
+    const agentsRoot = basename(managedRoot) === '.claude' ? join(dirname(managedRoot), '.agents') : managedRoot + '.agents';
+    const release = { preferencesDirectory: join(agentsRoot, 'rules'), selectorPath: join(finalRoot, 'compat', 'select_pstack_models.mjs'), schemaVersion: 1, commit: lock.commit, adapterVersion: lock.adapterVersion, skills, agents, fileDigests, verification: 'filesystem-only' };
+    writeFileSync(join(stage, 'release.json'), json(release));
+    return release;
+}
+
+function assertContained(root, path) {
+    const rel = relative(root, resolve(root, path));
+    if (isAbsolute(rel) || rel === '..' || rel.startsWith('..' + sep) || resolve(root, path) === resolve(root)) throw new Error('Invalid release path');
+    return resolve(root, path);
+}
+
+export function verifyRelease(root) {
+    const release = readJson(join(root, 'release.json'));
+    if (release.schemaVersion !== 1 || !Array.isArray(release.skills) || !release.skills.length || !release.fileDigests) throw new Error('Invalid release manifest');
+    for (const [path, hash] of Object.entries(release.fileDigests)) {
+        if (digest(readFileSync(assertContained(root, path))) !== hash) throw new Error(`Changed installed file: ${path}`);
+    }
+    for (const skill of release.skills) {
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skill.name)) throw new Error('Invalid installed skill name');
+        const path = join(assertContained(root, skill.path), 'SKILL.md');
+        if (!Object.hasOwn(release.fileDigests, relative(root, path)) || !existsSync(path)) throw new Error(`Missing entry: ${skill.name}`);
+    }
+    return release;
+}
+
+function layout(options) {
+    const root = resolve(options.root ?? (options.project ? join(options.project, '.claude') : process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude')));
+    const agents = basename(root) === '.claude' ? join(dirname(root), '.agents') : root + '.agents';
+    return { root, store: join(root, 'pstack'), skillHomes: [join(root, 'skills'), join(agents, 'skills')] };
+}
+
+function loadState(store) {
+    const path = join(store, 'installed.json');
+    return existsSync(path) ? readJson(path) : null;
+}
+
+export function verifyInstallation(options = {}) {
+    const { store } = layout(options);
+    const state = loadState(store);
+    if (!state) throw new Error('Pstack is not installed');
+    const release = verifyRelease(assertContained(join(store, 'releases'), state.release));
+    for (const [path, target] of Object.entries(state.links)) {
+        if (!lstatSync(path).isSymbolicLink() || realpathSync(path) !== realpathSync(target)) throw new Error(`Changed skill pointer: ${path}`);
+    }
+    return { ...state, skillCount: release.skills.length, verification: release.verification };
+}
+
+function publish(releaseRoot, release, homes, prior) {
+    const uniqueHomes = [...new Set(homes.map(home => { mkdirSync(home, { recursive: true }); return realpathSync(home); }))];
+    const links = Object.fromEntries(uniqueHomes.flatMap(home => release.skills.map(skill => [join(home, skill.name), join(releaseRoot, skill.path)])));
+    const paths = new Set([...Object.keys(prior?.links ?? {}), ...Object.keys(links)]);
+    const before = new Map();
+    for (const path of paths) {
+        if (entryExists(path)) {
+            if (!lstatSync(path).isSymbolicLink() || !prior?.links[path]
+                || resolve(dirname(path), readlinkSync(path)) !== resolve(prior.links[path])) {
+                throw new Error(`Keep existing unmanaged path: ${path}`);
+            }
+            before.set(path, readlinkSync(path));
+        } else before.set(path, null);
+    }
+    const restore = () => {
+        for (const [path, target] of before) {
+            if (entryExists(path)) unlinkSync(path);
+            if (target !== null) symlinkSync(target, path, process.platform === 'win32' ? 'junction' : 'dir');
+        }
+    };
+    try {
+        for (const path of paths) {
+            if (entryExists(path)) unlinkSync(path);
+            if (links[path]) symlinkSync(links[path], path, process.platform === 'win32' ? 'junction' : 'dir');
+        }
+    } catch (error) { restore(); throw error; }
+    return { links, restore };
+}
+
+function liveLeases(store) {
+    const root = join(store, 'sessions');
+    if (!existsSync(root)) return false;
+    return readdirSync(root).some(name => {
+        const pid = Number(name);
+        if (!Number.isSafeInteger(pid) || pid < 1) throw new Error('Invalid session lease');
+        try { process.kill(pid, 0); return true; } catch (error) {
+            if (error.code !== 'ESRCH') return true;
+            unlinkSync(join(root, name));
+            return false;
+        }
+    });
+}
+
+function readCentralLock(temporaryRoot) {
+    const repository = join(temporaryRoot, 'record');
+    mkdirSync(repository);
+    runGit(['init', '--quiet'], repository);
+    runGit(['fetch', '--quiet', '--depth=1', '--filter=blob:none', 'https://github.com/jl-cmd/claude-dev-env.git', 'main'], repository);
+    return JSON.parse(runGit(['show', 'FETCH_HEAD:packages/claude-dev-env/scripts/pstack.lock.json'], repository));
+}
+
+export function installPstack(options = {}, dependencies = {}) {
+    const { store, skillHomes } = layout(options);
+    mkdirSync(store, { recursive: true });
+    const lockDirectory = join(store, '.install-lock');
+    mkdirSync(lockDirectory);
+    let temporaryRoot;
+    const finish = installation => {
+        if (options.reserveSession) {
+            const sessions = join(store, 'sessions');
+            mkdirSync(sessions, { recursive: true });
+            writeFileSync(join(sessions, String(process.pid)), installation.release);
+        }
+        return installation;
+    };
+    try {
+        const prior = loadState(store);
+        if ((options.offline || liveLeases(store)) && prior) return finish({ ...verifyInstallation(options), status: 'retained' });
+        if (options.offline) throw new Error('Offline install needs an existing verified release');
+        temporaryRoot = mkdtempSync(join(store, '.prepare-'));
+        const now = dependencies.now ?? Date.now();
+        const interval = options.intervalMs ?? 3600000;
+        if (!Number.isFinite(interval) || interval < 0) throw new Error('Invalid update interval');
+        const bundled = options.lock ?? prior?.lock ?? readJson(bundledLockPath);
+        let lock = bundled;
+        let checkedAt = prior?.checkedAt ?? 0;
+        if (options.refresh && (options.force || now - checkedAt >= interval)) {
+            lock = (dependencies.readCentralLock ?? readCentralLock)(temporaryRoot);
+            checkedAt = now;
+        } else if (options.refresh && prior?.lock) lock = prior.lock;
+        validateLock(lock);
+        const adapters = adapterFiles(options.packageRoot ?? packageRoot);
+        const installerSource = readFileSync(fileURLToPath(import.meta.url), 'utf8').replace(/\r\n/g, '\n');
+        const adapterDigest = digest(json(adapters) + installerSource);
+        const id = `${lock.commit}-${adapterDigest.slice(0, 16)}`;
+        const releaseRoot = join(store, 'releases', id);
+        mkdirSync(dirname(releaseRoot), { recursive: true });
+        if (!existsSync(releaseRoot)) {
+            const checkout = join(temporaryRoot, 'source');
+            (dependencies.fetchSource ?? fetchUpstream)(lock, checkout);
+            const stage = join(temporaryRoot, 'release');
+            prepareRelease(checkout, stage, releaseRoot, lock, adapters);
+            verifyRelease(stage);
+            renameSync(stage, releaseRoot);
+        }
+        const release = verifyRelease(releaseRoot);
+        const publication = publish(releaseRoot, release, skillHomes, prior);
+        const state = { release: id, commit: lock.commit, adapterVersion: lock.adapterVersion, adapterDigest, checkedAt, lock, links: publication.links };
+        try {
+            writeFileSync(join(store, 'installed.next.json'), json(state));
+            renameSync(join(store, 'installed.next.json'), join(store, 'installed.json'));
+        } catch (error) { publication.restore(); throw error; }
+        return finish({ ...verifyInstallation(options), status: prior?.release === id ? 'unchanged' : 'installed' });
+    } catch (error) {
+        if (!options.strict) {
+            try { return finish({ ...verifyInstallation(options), status: 'retained', warning: error.message }); } catch { }
+        }
+        throw error;
+    } finally {
+        if (temporaryRoot) rmSync(temporaryRoot, { recursive: true, force: true });
+        rmSync(lockDirectory, { recursive: true, force: true });
+    }
+}
+
+function parseArguments(args) {
+    const options = {};
+    const tailIndex = args.indexOf('--');
+    const tokens = tailIndex < 0 ? args : args.slice(0, tailIndex);
+    const forwarded = tailIndex < 0 ? [] : args.slice(tailIndex + 1);
+    for (let index = 0; index < tokens.length; index++) {
+        const flag = tokens[index];
+        if (['--offline', '--refresh', '--force', '--strict'].includes(flag)) options[flag.slice(2)] = true;
+        else if (['--root', '--project', '--host', '--lock', '--interval-ms'].includes(flag)) {
+            const argument = tokens[++index];
+            if (!argument || argument.startsWith('--')) throw new Error(`${flag} requires a value`);
+            if (flag === '--lock') options.lock = readJson(resolve(argument));
+            else if (flag === '--interval-ms') options.intervalMs = Number(argument);
+            else options[flag.slice(2)] = argument;
+        } else throw new Error(`Unknown option: ${flag}`);
+    }
+    if (options.host && !hosts.includes(options.host)) throw new Error('Host must be claude, codex, or cursor');
+    if (options.root && options.project) throw new Error('Choose --root or --project');
+    return { options, forwarded };
+}
+
+export function main(args = process.argv.slice(2)) {
+    try {
+        const [command = 'help', ...rest] = args;
+        if (['help', '--help', '-h'].includes(command)) {
+            console.log('Usage: cde-pstack <install|verify|launch|hook> [--root PATH|--project PATH] [--refresh] [--offline] [--strict] [--lock PATH] [--host claude|codex|cursor] [-- agent arguments]');
+            return 0;
+        }
+        const { options, forwarded } = parseArguments(rest);
+        if (!['install', 'verify', 'launch', 'hook'].includes(command)) throw new Error(`Unknown command: ${command}`);
+        let hookInput;
+        if (command === 'hook') {
+            hookInput = JSON.parse(readFileSync(0, 'utf8') || '{}');
+            options.project ??= process.env.CLAUDE_PROJECT_DIR || process.cwd();
+            options.offline = hookInput.source !== 'startup';
+            options.refresh = !options.offline && loadState(layout(options).store) !== null;
+        }
+        if (command === 'launch' && !options.host) throw new Error('launch requires --host');
+        if (command === 'launch') { options.refresh = !options.offline && !options.lock; options.reserveSession = true; }
+        const installation = command === 'verify' ? verifyInstallation(options) : installPstack(options);
+        if (installation.warning) console.error(`Pstack update failed; keeping ${installation.commit}: ${installation.warning}`);
+        if (command === 'hook') {
+            const { store } = layout(options);
+            const release = join(store, 'releases', installation.release);
+            console.log(json({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: `Pstack ${installation.commit} is installed. Use the immutable release recorded by session-continuity or the loaded skill entry for this session. Read common.md and host-claude.md in that release's compat directory. New sessions can use the installed inventory at ${join(release, 'release.json')}. ${installation.warning ?? ''}` } }));
+        } else if (command === 'launch') {
+            const sessions = join(layout(options).store, 'sessions');
+            const lease = join(sessions, String(process.pid));
+            try {
+                const child = spawnSync(options.host, forwarded, { stdio: 'inherit', shell: false, env: { ...process.env, CDE_PSTACK_RELEASE: join(layout(options).store, 'releases', installation.release) } });
+                if (child.error) throw child.error;
+                return child.status ?? 1;
+            } finally { unlinkSync(lease); }
+        } else console.log(json(installation));
+        return 0;
+    } catch (error) { console.error(`Pstack: ${error.message}`); return 1; }
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main();

package/bin/pstack.test.mjs

@@ -0,0 +1,289 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { installPstack, prepareRelease, validateLock, verifyInstallation, verifyRelease } from './pstack.mjs';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const baseLock = JSON.parse(readFileSync(join(packageRoot, 'scripts', 'pstack.lock.json'), 'utf8'));
+
+function put(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+}
+
+function fixture(t) {
+    const temporary = mkdtempSync(join(tmpdir(), 'cde-pstack-'));
+    t.after(() => rmSync(temporary, { recursive: true, force: true }));
+    const checkout = join(temporary, 'checkout');
+    for (const [component, names] of Object.entries(baseLock.requiredSkills)) {
+        for (const name of names) put(join(checkout, component, 'skills', name, 'SKILL.md'), `---\nname: ${name}\ndescription: Test ${name}.\n---\n\nRun ${name}.\n`);
+        put(join(checkout, component, 'LICENSE'), `${component} license\n`);
+        put(join(checkout, component, '.cursor-plugin', 'plugin.json'), JSON.stringify({ name: component, skills: './skills' }));
+    }
+    put(join(checkout, 'pstack', 'skills', 'poteto-mode', 'playbooks', 'feature.md'), 'Build a small task, delegate, and verify it.\n');
+    put(join(checkout, 'pstack', 'agents', 'poteto-agent.md'), 'Read poteto-mode and report complete findings.\n');
+    put(join(checkout, 'pstack', 'scripts', 'proof.sh'), '#!/bin/sh\nprintf proof\n');
+    chmodSync(join(checkout, 'pstack', 'scripts', 'proof.sh'), 0o755);
+    put(join(checkout, 'pstack', 'assets', 'example.png'), Buffer.from([137, 80, 78, 71, 0, 255]));
+    const project = join(temporary, 'project with spaces');
+    const options = { project, lock: structuredClone(baseLock), packageRoot };
+    const dependencies = { fetchSource: (_lock, destination) => cpSync(checkout, destination, { recursive: true }), now: 10000000 };
+    return { temporary, checkout, options, dependencies, store: join(project, '.claude', 'pstack') };
+}
+
+for (const host of ['claude', 'codex', 'cursor']) {
+    test(`clean ${host} filesystem install publishes all entry points and supporting files`, t => {
+        const f = fixture(t);
+        const result = installPstack({ ...f.options, host }, f.dependencies);
+        assert.equal(result.status, 'installed');
+        assert.equal(result.skillCount, 5);
+        assert.equal(result.commit, '27e2a62ff94f9af4b5e68435e41cdceacadb840c');
+        assert.equal(result.verification, 'filesystem-only');
+        const release = join(f.store, 'releases', result.release);
+        const expected = ['cde-create-skill', 'cursor-team-kit-control-cli', 'cursor-team-kit-control-ui', 'cursor-team-kit-deslop', 'pstack-poteto-mode'];
+        for (const home of ['.claude', '.agents']) {
+            assert.deepEqual(readdirSync(join(f.options.project, home, 'skills')).sort(), expected);
+            const entry = join(f.options.project, home, 'skills', 'pstack-poteto-mode');
+            assert.equal(realpathSync(entry), join(release, 'runtime', 'pstack', 'skills', 'poteto-mode'));
+            const text = readFileSync(join(entry, 'SKILL.md'), 'utf8');
+            assert.match(text, /name: pstack-poteto-mode/);
+            assert.ok(text.includes(JSON.stringify(join(release, 'compat', 'common.md'))));
+            assert.equal(readFileSync(join(entry, 'playbooks', 'feature.md'), 'utf8'), 'Build a small task, delegate, and verify it.\n');
+        }
+        assert.equal(existsSync(join(f.options.project, '.cursor')), false);
+        for (const component of baseLock.components) {
+            assert.equal(existsSync(join(release, 'runtime', component, '.cursor-plugin', 'plugin.json')), false);
+            assert.equal(readFileSync(join(release, 'upstream', component, '.cursor-plugin', 'plugin.json'), 'utf8'),
+                readFileSync(join(f.checkout, component, '.cursor-plugin', 'plugin.json'), 'utf8'));
+        }
+        assert.equal(readFileSync(join(release, 'upstream', 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'utf8'), readFileSync(join(f.checkout, 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'utf8'));
+        assert.deepEqual(readFileSync(join(release, 'upstream', 'pstack', 'assets', 'example.png')), Buffer.from([137, 80, 78, 71, 0, 255]));
+        assert.equal(readFileSync(join(release, 'runtime', 'pstack', 'agents', 'poteto-agent.md'), 'utf8'), 'Read poteto-mode and report complete findings.\n');
+        assert.equal(readFileSync(join(release, 'upstream', 'cursor-team-kit', 'LICENSE'), 'utf8'), 'cursor-team-kit license\n');
+        if (process.platform !== 'win32') assert.equal(statSync(join(release, 'runtime', 'pstack', 'scripts', 'proof.sh')).mode & 0o777, 0o755);
+    });
+}
+
+test('unchanged install avoids another upstream fetch', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const second = installPstack(f.options, { fetchSource: () => assert.fail('unexpected fetch') });
+    assert.equal(second.status, 'unchanged');
+    assert.equal(second.release, first.release);
+    assert.deepEqual(second.links, first.links);
+});
+
+test('changed, added, and removed skills converge while old releases remain readable', t => {
+    const f = fixture(t);
+    put(join(f.checkout, 'pstack', 'skills', 'old', 'SKILL.md'), '---\nname: old\ndescription: Old skill.\n---\nOld body.\n');
+    const before = installPstack(f.options, f.dependencies);
+    const oldRelease = join(f.store, 'releases', before.release);
+    const firstBody = readFileSync(join(oldRelease, 'runtime', 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'utf8');
+    rmSync(join(f.checkout, 'pstack', 'skills', 'old'), { recursive: true });
+    put(join(f.checkout, 'pstack', 'skills', 'new', 'SKILL.md'), '---\nname: new\ndescription: New skill.\n---\nNew body.\n');
+    put(join(f.checkout, 'pstack', 'skills', 'poteto-mode', 'playbooks', 'feature.md'), 'Changed playbook.\n');
+    const after = installPstack({ ...f.options, lock: { ...baseLock, commit: 'b'.repeat(40) } }, f.dependencies);
+    assert.equal(after.skillCount, 6);
+    for (const home of ['.claude', '.agents']) {
+        const path = join(f.options.project, home, 'skills');
+        assert.equal(existsSync(join(path, 'pstack-old')), false);
+        assert.equal(readFileSync(join(path, 'pstack-new', 'SKILL.md'), 'utf8').endsWith('New body.\n'), true);
+        assert.equal(readFileSync(join(path, 'pstack-poteto-mode', 'playbooks', 'feature.md'), 'utf8'), 'Changed playbook.\n');
+    }
+    assert.equal(readFileSync(join(oldRelease, 'runtime', 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'utf8'), firstBody);
+});
+
+test('missing required dependency retains the previous complete installation', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const priorBytes = readFileSync(join(f.store, 'installed.json'), 'utf8');
+    rmSync(join(f.checkout, 'cursor-team-kit', 'skills', 'control-ui'), { recursive: true });
+    const result = installPstack({ ...f.options, lock: { ...baseLock, commit: 'c'.repeat(40) } }, f.dependencies);
+    assert.equal(result.status, 'retained');
+    assert.match(result.warning, /Missing dependency: cursor-team-kit:control-ui/);
+    assert.equal(result.release, first.release);
+    assert.equal(readFileSync(join(f.store, 'installed.json'), 'utf8'), priorBytes);
+    assert.equal(verifyInstallation(f.options).skillCount, 5);
+});
+
+test('a failed first install returns failure and publishes no skills', t => {
+    const f = fixture(t);
+    assert.throws(() => installPstack(f.options, { fetchSource: () => { throw new Error('network unavailable'); } }), /network unavailable/);
+    assert.equal(existsSync(join(f.options.project, '.claude', 'skills')), false);
+    assert.equal(existsSync(join(f.store, '.install-lock')), false);
+});
+
+test('unmanaged skill collision preserves user files', t => {
+    const f = fixture(t);
+    const userFile = join(f.options.project, '.claude', 'skills', 'pstack-poteto-mode', 'SKILL.md');
+    put(userFile, 'Personal workflow\n');
+    assert.throws(() => installPstack(f.options, f.dependencies), /Keep existing unmanaged path/);
+    assert.equal(readFileSync(userFile, 'utf8'), 'Personal workflow\n');
+    assert.equal(existsSync(join(f.store, 'installed.json')), false);
+});
+
+test('existing shared skills-directory pointer is preserved', t => {
+    const f = fixture(t);
+    const agents = join(f.options.project, '.agents', 'skills');
+    mkdirSync(agents, { recursive: true });
+    mkdirSync(join(f.options.project, '.claude'), { recursive: true });
+    symlinkSync(agents, join(f.options.project, '.claude', 'skills'), process.platform === 'win32' ? 'junction' : 'dir');
+    const before = readlinkSync(join(f.options.project, '.claude', 'skills'));
+    const result = installPstack(f.options, f.dependencies);
+    assert.equal(Object.keys(result.links).length, 5);
+    assert.equal(readlinkSync(join(f.options.project, '.claude', 'skills')), before);
+});
+
+test('offline reuse checks installed bytes and rejects corruption', t => {
+    const f = fixture(t);
+    const result = installPstack(f.options, f.dependencies);
+    assert.equal(installPstack({ ...f.options, offline: true }).release, result.release);
+    put(join(f.store, 'releases', result.release, 'runtime', 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'corrupted');
+    assert.throws(() => installPstack({ ...f.options, offline: true }), /Changed installed file/);
+});
+
+test('unknown namespaced upstream dependency requires adapter review', t => {
+    const f = fixture(t);
+    put(join(f.checkout, 'pstack', 'skills', 'poteto-mode', 'reference.md'), 'Invoke cursor-team-kit:missing-skill.\n');
+    assert.throws(() => installPstack(f.options, f.dependencies), /Unresolved skill dependency/);
+});
+
+test('source symlinks are rejected before publication', t => {
+    const f = fixture(t);
+    const outside = join(f.temporary, 'outside-source');
+    mkdirSync(outside);
+    put(join(outside, 'personal.txt'), 'Retain this file.');
+    const dependencies = { ...f.dependencies, fetchSource: (lock, destination) => {
+        f.dependencies.fetchSource(lock, destination);
+        const link = join(destination, 'pstack', 'escape');
+        symlinkSync(outside, link, process.platform === 'win32' ? 'junction' : 'dir');
+        assert.equal(lstatSync(link).isSymbolicLink(), true);
+    } };
+    assert.throws(() => installPstack(f.options, dependencies), /symlinks require review/);
+    assert.equal(readFileSync(join(outside, 'personal.txt'), 'utf8'), 'Retain this file.');
+});
+
+test('update checks use the shared record and respect the interval', t => {
+    const f = fixture(t);
+    const shared = { ...baseLock, commit: 'd'.repeat(40) };
+    let calls = 0;
+    const dependencies = { ...f.dependencies, readCentralLock: () => { calls++; return shared; } };
+    const first = installPstack({ ...f.options, refresh: true }, dependencies);
+    assert.equal(first.commit, 'd'.repeat(40));
+    const second = installPstack({ ...f.options, refresh: true }, { ...dependencies, now: dependencies.now + 100 });
+    assert.equal(second.commit, 'd'.repeat(40));
+    assert.equal(calls, 1);
+    installPstack({ ...f.options, refresh: true }, { ...dependencies, now: dependencies.now + 3600001 });
+    assert.equal(calls, 2);
+});
+
+test('failed shared-record refresh retains and reports the previous revision', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const result = installPstack({ ...f.options, refresh: true }, { ...f.dependencies, readCentralLock: () => { throw new Error('record unavailable'); } });
+    assert.equal(result.release, first.release);
+    assert.equal(result.warning, 'record unavailable');
+});
+
+test('an active launcher lease defers updating shared instructions', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    put(join(f.store, 'sessions', String(process.pid)), first.release);
+    const result = installPstack({ ...f.options, lock: { ...baseLock, commit: 'e'.repeat(40) } }, { fetchSource: () => assert.fail('updated during an active session') });
+    assert.equal(result.status, 'retained');
+    assert.equal(result.release, first.release);
+});
+
+test('unsupported lock input fails before source fetch', t => {
+    const f = fixture(t);
+    for (const change of [{ commit: 'main' }, { adapterVersion: 2 }, { repository: 'https://example.test/repo' }, { components: ['../outside'] }, { requiredSkills: {} }]) {
+        assert.throws(() => installPstack({ ...f.options, lock: { ...baseLock, ...change } }, { fetchSource: () => assert.fail('unexpected fetch') }));
+    }
+    assert.equal(validateLock(baseLock), baseLock);
+});
+
+test('CLI exposes deterministic verification and rejects unknown flags', t => {
+    const f = fixture(t);
+    installPstack(f.options, f.dependencies);
+    const command = join(packageRoot, 'bin', 'pstack.mjs');
+    const verified = spawnSync(process.execPath, [command, 'verify', '--project', f.options.project], { encoding: 'utf8' });
+    assert.equal(verified.status, 0, verified.stderr);
+    assert.equal(JSON.parse(verified.stdout).skillCount, 5);
+    const invalid = spawnSync(process.execPath, [command, 'install', '--host', 'unknown'], { encoding: 'utf8' });
+    assert.equal(invalid.status, 1);
+    assert.match(invalid.stderr, /Host must be/);
+    const help = spawnSync(process.execPath, [command, '--help'], { encoding: 'utf8' });
+    assert.equal(help.status, 0);
+    assert.match(help.stdout, /cde-pstack/);
+});
+
+test('resumed Claude hook retains the cached release and emits native hook JSON', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const result = spawnSync(process.execPath, [join(packageRoot, 'bin', 'pstack.mjs'), 'hook', '--project', f.options.project], {
+        encoding: 'utf8', input: JSON.stringify({ source: 'resume' }),
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const output = JSON.parse(result.stdout);
+    assert.equal(output.hookSpecificOutput.hookEventName, 'SessionStart');
+    assert.ok(output.hookSpecificOutput.additionalContext.includes(first.commit));
+    assert.ok(output.hookSpecificOutput.additionalContext.includes('common.md'));
+});
+
+test('release validation catches missing files and escaping manifest paths', t => {
+    const f = fixture(t);
+    const result = installPstack(f.options, f.dependencies);
+    const root = join(f.store, 'releases', result.release);
+    assert.equal(verifyRelease(root).skills.length, 5);
+    const manifest = JSON.parse(readFileSync(join(root, 'release.json'), 'utf8'));
+    manifest.fileDigests['../../outside'] = 'bad';
+    put(join(root, 'release.json'), JSON.stringify(manifest));
+    assert.throws(() => verifyRelease(root), /Invalid release path/);
+});
+
+test('state-write failure restores the old published pointers', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const priorBytes = readFileSync(join(f.store, 'installed.json'), 'utf8');
+    mkdirSync(join(f.store, 'installed.next.json'));
+    const result = installPstack({ ...f.options, lock: { ...baseLock, commit: 'f'.repeat(40) } }, f.dependencies);
+    assert.equal(result.status, 'retained');
+    assert.equal(result.release, first.release);
+    assert.equal(readFileSync(join(f.store, 'installed.json'), 'utf8'), priorBytes);
+    assert.equal(verifyInstallation(f.options).commit, first.commit);
+});
+
+test('npm-style linked CLI runs its entry point', t => {
+    const f = fixture(t);
+    if (process.platform === 'win32') return;
+    const link = join(f.temporary, 'cde-pstack');
+    symlinkSync(join(packageRoot, 'bin', 'pstack.mjs'), link);
+    const result = spawnSync(process.execPath, [link, '--help'], { encoding: 'utf8' });
+    assert.equal(result.status, 0);
+    assert.match(result.stdout, /Usage: cde-pstack/);
+});
+
+test('session reservation is recorded before install releases its lock', t => {
+    const f = fixture(t);
+    const result = installPstack({ ...f.options, reserveSession: true }, f.dependencies);
+    assert.equal(readFileSync(join(f.store, 'sessions', String(process.pid)), 'utf8'), result.release);
+    assert.equal(existsSync(join(f.store, '.install-lock')), false);
+});
+
+
+test('a changed installer creates a fresh generation for the same upstream pin', async t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const copied = join(f.temporary, 'updated-installer', 'bin', 'pstack.mjs');
+    put(copied, readFileSync(join(packageRoot, 'bin', 'pstack.mjs'), 'utf8') + '\n');
+    const updated = await import(pathToFileURL(copied).href);
+    const second = updated.installPstack(f.options, f.dependencies);
+    assert.equal(second.commit, first.commit);
+    assert.notEqual(second.adapterDigest, first.adapterDigest);
+    assert.notEqual(second.release, first.release);
+    assert.equal(verifyInstallation(f.options).release, second.release);
+});

package/package.json

@@ -1,10 +1,11 @@
 {
     "name": "claude-dev-env",
-    "version": "7.2.1",
+    "version": "7.4.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
         "claude-dev-env": "bin/install.mjs",
+        "cde-pstack": "bin/pstack.mjs",
         "codex-compat": "bin/codex-compat.mjs",
         "cde": "bin/cde.mjs"
     },