github/awesome-copilot / skills/webmcpify
webmcpify
VerifiedWebMCP agent skill for curated core coverage or route-by-route parity — inventory an existing web app, integrate approved tools, then inspect, verify and heal them in a real browser. Use for "webmcpify", "add WebMCP", or "expose app actions to AI agents".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 31.3 KB |
| references/discovery.md | markdown | 8.5 KB |
| references/heal.md | markdown | 8.3 KB |
| references/integrate.md | markdown | 10.7 KB |
| references/inventory.md | markdown | 9.9 KB |
| references/native-compatibility.md | markdown | 5.3 KB |
| references/reverify.md | markdown | 11.3 KB |
| references/runtime.md | markdown | 8.7 KB |
| references/security.md | markdown | 5.0 KB |
| references/verify.md | markdown | 15.4 KB |
| references/workbench.md | markdown | 5.0 KB |
| scripts/workbench.mjs | script | 5.6 KB |
| templates/mutation-journal.js | script | 22.3 KB |
| templates/mutation-journal.ts | script | 25.8 KB |
| templates/webmcp-compat.js | script | 2.5 KB |
| templates/webmcp-jsx.d.ts | script | 2.3 KB |
| templates/webmcp-workbench.js | script | 37.9 KB |
| templates/webmcp.d.ts | script | 6.1 KB |
| templates/webmcp.spec.ts | script | 18.9 KB |
| templates/webmcpify.js | script | 12.0 KB |
| templates/webmcpify.ts | script | 12.5 KB |
| templates/well-known-webmcp.json | config | 1.2 KB |
| tests/README.md | markdown | 1.3 KB |
| tests/workbench-cli.test.mjs | script | 4.5 KB |
| tests/workbench.test.mjs | script | 5.4 KB |
templates/mutation-journal.ts
View on GitHub/*!
* webmcpify durable mutation journal helper
*
* MIT License
* Copyright (c) 2026 Jonas Tüchler
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
import { spawn, type ChildProcess } from 'node:child_process';
import { createHash, randomUUID } from 'node:crypto';
import { constants } from 'node:fs';
import { lstat, open, readFile, realpath, rename, rm, stat, type FileHandle } from 'node:fs/promises';
import { hostname } from 'node:os';
import { basename, dirname, join } from 'node:path';
type JsonObject = Record<string, unknown>;
export interface MutationExecution {
executionId: string;
tool: string;
contractRevision: number;
origin: string;
role: string;
fixtureRevision: string;
argumentsFingerprint: string;
startedAt: string;
state: 'started' | 'reconciled';
evidence: string;
parentExecutionId?: string;
outcome?: string;
reconciledAt?: string;
}
export interface BeforeDispatchInput {
/** Tool/action being dispatched. */
tool: string;
/** Manifest tool that owns the journal; defaults to `tool`. */
manifestTool?: string;
contractRevision: number;
origin: string;
role: string;
fixtureRevision: string;
arguments: unknown;
evidence: string;
/** Set only for a cleanup of this unresolved parent execution. */
parentExecutionId?: string;
}
export interface SettlementInput {
outcome: string;
evidence: string;
reconciledAt?: string;
}
export interface OpenMutationJournalOptions {
manifestPath: string;
/** Optional bounded acquisition time; omitted means wait until ownership is available. */
timeoutMs?: number;
}
interface ManifestTool extends JsonObject {
id?: string;
status?: string;
verifiedAgainst?: unknown;
mutationExecutions?: MutationExecution[];
}
interface Manifest extends JsonObject {
mutationLockIdentity?: string;
tools: ManifestTool[];
}
interface LockCandidate {
command: string;
args(): string[];
probeArgs(): string[];
busyExitCode: number;
}
interface LockIdentity {
dev: number;
ino: number;
}
const LOCK_CANDIDATES: LockCandidate[] = [
{
command: 'flock',
// fd 3 is inherited from the already verified parent handle. This prevents
// a pathname swap between validation and advisory-lock acquisition. flock's
// descriptor lock belongs to the shared open-file description, so it stays
// held by this runner after the short acquisition subprocess exits.
args: () => ['--exclusive', '3'],
probeArgs: () => ['--exclusive', '--nonblock', '3'],
busyExitCode: 1,
},
{
command: 'lockf',
// macOS/FreeBSD lockf's descriptor form uses BSD flock(2) locking and
// implies -k, so it neither opens by pathname nor removes the sidecar.
args: () => ['-s', '3'],
probeArgs: () => ['-s', '-t', '0', '3'],
busyExitCode: 75,
},
];
function requireText(value: string, label: string): string {
if (!value.trim()) throw new Error(`${label} must be a non-empty string`);
return value;
}
function canonicalJson(value: unknown): string {
const json = JSON.stringify(value);
if (json === undefined) throw new Error('mutation arguments must be JSON-serializable');
const parsed = JSON.parse(json) as unknown;
const serialize = (item: unknown): string => {
if (Array.isArray(item)) return `[${item.map(serialize).join(',')}]`;
if (item && typeof item === 'object') {
return `{${Object.keys(item as JsonObject)
.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
.map((key) => `${JSON.stringify(key)}:${serialize((item as JsonObject)[key])}`)
.join(',')}}`;
}
return JSON.stringify(item);
};
return serialize(parsed);
}
export function fingerprintArguments(value: unknown): string {
return `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
}
type OwnedStep = <T>(operation: () => Promise<T>) => Promise<T>;
async function syncDirectory(path: string, step: OwnedStep): Promise<void> {
const handle = await step(() => open(path, 'r'));
try {
await step(() => handle.sync());
} finally {
await handle.close();
}
}
async function durableReplace(manifestPath: string, manifest: Manifest, step: OwnedStep): Promise<void> {
const directory = dirname(manifestPath);
const temporary = join(directory, `.${basename(manifestPath)}.${process.pid}.${randomUUID()}.tmp`);
const mode = (await step(() => stat(manifestPath))).mode & 0o777;
let handle;
try {
handle = await step(() => open(temporary, 'wx', mode));
await step(() => handle!.writeFile(`${JSON.stringify(manifest, null, 2)}\n`, 'utf8'));
await step(() => handle!.sync());
await step(() => handle!.close());
handle = undefined;
await step(() => rename(temporary, manifestPath));
await syncDirectory(directory, step);
} catch (error) {
await handle?.close().catch(() => undefined);
await rm(temporary, { force: true }).catch(() => undefined);
throw error;
}
}
async function readManifest(manifestPath: string): Promise<Manifest> {
const value = JSON.parse(await readFile(manifestPath, 'utf8')) as Partial<Manifest>;
if (!Array.isArray(value.tools)) throw new Error(`manifest has no tools array: ${manifestPath}`);
return value as Manifest;
}
function unresolvedEntries(manifest: Manifest): MutationExecution[] {
validateJournals(manifest);
return manifest.tools.flatMap((tool) => tool.mutationExecutions!
.filter((entry) => entry.state === 'started'));
}
function validateJournals(manifest: Manifest): void {
const toolIds = new Set<string>();
const executions = new Map<string, { entry: MutationExecution; owner: ManifestTool }>();
for (const [toolIndex, tool] of manifest.tools.entries()) {
if (!tool || typeof tool !== 'object' || Array.isArray(tool)) {
throw new Error(`manifest tool ${toolIndex} must be an object`);
}
const toolId = requireText(typeof tool.id === 'string' ? tool.id : '', `manifest tool ${toolIndex} id`);
if (toolIds.has(toolId)) throw new Error(`duplicate manifest tool id: ${toolId}`);
toolIds.add(toolId);
if (!Array.isArray(tool.mutationExecutions)) {
throw new Error(`mutationExecutions must be an array for manifest tool: ${toolId}`);
}
for (const [entryIndex, candidate] of tool.mutationExecutions.entries()) {
if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
throw new Error(`mutation execution ${toolId}[${entryIndex}] must be an object`);
}
const entry = candidate as MutationExecution;
const label = `mutation execution ${toolId}[${entryIndex}]`;
requireText(typeof entry.executionId === 'string' ? entry.executionId : '', `${label} executionId`);
requireText(typeof entry.tool === 'string' ? entry.tool : '', `${label} tool`);
if (!Number.isInteger(entry.contractRevision) || entry.contractRevision < 1) {
throw new Error(`${label} contractRevision must be a positive integer`);
}
for (const field of ['origin', 'role', 'fixtureRevision', 'argumentsFingerprint', 'startedAt', 'evidence'] as const) {
requireText(typeof entry[field] === 'string' ? entry[field] : '', `${label} ${field}`);
}
if (entry.state !== 'started' && entry.state !== 'reconciled') {
throw new Error(`${label} has unknown state: ${String(entry.state)}`);
}
if (entry.parentExecutionId !== undefined) {
requireText(typeof entry.parentExecutionId === 'string' ? entry.parentExecutionId : '', `${label} parentExecutionId`);
}
if (entry.state === 'reconciled') {
requireText(typeof entry.outcome === 'string' ? entry.outcome : '', `${label} outcome`);
requireText(typeof entry.reconciledAt === 'string' ? entry.reconciledAt : '', `${label} reconciledAt`);
}
if (executions.has(entry.executionId)) {
throw new Error(`duplicate mutation executionId: ${entry.executionId}`);
}
executions.set(entry.executionId, { entry, owner: tool });
}
}
for (const { entry, owner } of executions.values()) {
if (!entry.parentExecutionId) continue;
const parent = executions.get(entry.parentExecutionId);
if (!parent || parent.owner !== owner || parent.entry.parentExecutionId) {
throw new Error(`invalid parentExecutionId for mutation execution: ${entry.executionId}`);
}
}
}
async function migrateManifest(
manifestPath: string,
manifest: Manifest,
lockIdentity: string,
step: OwnedStep,
): Promise<Manifest> {
let changed = false;
if (!Object.hasOwn(manifest, 'mutationLockIdentity')) {
manifest.mutationLockIdentity = lockIdentity;
changed = true;
} else if (manifest.mutationLockIdentity !== lockIdentity) {
throw new Error('manifest mutationLockIdentity does not match the locked sidecar');
}
for (const [toolIndex, tool] of manifest.tools.entries()) {
if (!tool || typeof tool !== 'object' || Array.isArray(tool)) {
throw new Error(`manifest tool ${toolIndex} must be an object`);
}
if (!Object.hasOwn(tool, 'mutationExecutions')) {
tool.mutationExecutions = [];
tool.verifiedAgainst = null;
if (tool.status === 'verified') tool.status = 'integrated';
changed = true;
}
}
validateJournals(manifest);
if (changed) await durableReplace(manifestPath, manifest, step);
return manifest;
}
async function writeOwnerMetadata(handle: FileHandle, metadata: JsonObject, step: OwnedStep): Promise<void> {
const serialized = `${JSON.stringify(metadata)}\n`;
await step(() => handle.truncate(0));
await step(() => handle.write(serialized, 0, 'utf8').then(() => undefined));
await step(() => handle.sync());
}
async function readOwnerMetadata(handle: FileHandle, step: OwnedStep): Promise<JsonObject> {
const size = (await step(() => handle.stat())).size;
if (size === 0) return {};
const buffer = Buffer.alloc(size);
const { bytesRead } = await step(() => handle.read(buffer, 0, size, 0));
let value: unknown;
try {
value = JSON.parse(buffer.subarray(0, bytesRead).toString('utf8'));
} catch {
throw new Error('manifest.lock contains malformed owner metadata');
}
if (!value || typeof value !== 'object' || Array.isArray(value)) {
throw new Error('manifest.lock owner metadata must be an object');
}
return value as JsonObject;
}
async function openLockFile(lockPath: string): Promise<{ handle: FileHandle; identity: LockIdentity }> {
const handle = await open(lockPath, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
try {
const info = await handle.stat();
if (!info.isFile() || info.nlink !== 1) {
throw new Error('manifest.lock must be a regular file with exactly one link');
}
const pathInfo = await lstat(lockPath);
if (!pathInfo.isFile() || pathInfo.isSymbolicLink() || pathInfo.nlink !== 1
|| pathInfo.dev !== info.dev || pathInfo.ino !== info.ino) {
throw new Error('manifest.lock identity changed while opening');
}
return { handle, identity: { dev: info.dev, ino: info.ino } };
} catch (error) {
await handle.close().catch(() => undefined);
throw error;
}
}
async function runLockCommand(
candidate: LockCandidate,
args: string[],
lockHandle: FileHandle,
lockPath: string,
timeoutMs?: number,
): Promise<{ code: number | null; signal: NodeJS.Signals | null; stderr: string }> {
const child = spawn(candidate.command, args, {
detached: true,
stdio: ['ignore', 'ignore', 'pipe', lockHandle.fd],
});
let stderr = '';
child.stderr?.setEncoding('utf8');
child.stderr?.on('data', (chunk) => { stderr += chunk; });
const exit = waitForChildExit(child);
let timer: NodeJS.Timeout | undefined;
const timedOut = Symbol('timed-out');
const result = await (timeoutMs === undefined
? exit
: Promise.race([
exit,
new Promise<typeof timedOut>((resolve) => { timer = setTimeout(() => resolve(timedOut), timeoutMs); }),
]));
if (timer) clearTimeout(timer);
if (result === timedOut) {
try {
process.kill(-child.pid!, 'SIGTERM');
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error;
}
await exit.catch(() => undefined);
throw new Error(`timed out after ${timeoutMs}ms waiting for ${lockPath}`);
}
return { ...result, stderr };
}
async function verifyLockHeld(
candidate: LockCandidate,
lockPath: string,
identity: LockIdentity,
): Promise<void> {
const probe = await openLockFile(lockPath);
try {
if (probe.identity.dev !== identity.dev || probe.identity.ino !== identity.ino) {
throw new Error('manifest.lock identity changed after lock acquisition');
}
const result = await runLockCommand(candidate, candidate.probeArgs(), probe.handle, lockPath);
if (result.code !== candidate.busyExitCode) {
throw new Error(
`${candidate.command} descriptor lock did not remain held by the runner `
+ `(${result.code ?? result.signal ?? 'unknown'}): ${result.stderr.trim()}`,
);
}
} finally {
await probe.handle.close().catch(() => undefined);
}
}
async function acquireLock(
lockHandle: FileHandle,
lockPath: string,
lockIdentity: LockIdentity,
timeoutMs?: number,
): Promise<LockCandidate> {
const unavailable: string[] = [];
for (const candidate of LOCK_CANDIDATES) {
try {
const result = await runLockCommand(candidate, candidate.args(), lockHandle, lockPath, timeoutMs);
if (result.code !== 0) {
throw new Error(
`${candidate.command} exited before lock acquisition `
+ `(${result.code ?? result.signal ?? 'unknown'}): ${result.stderr.trim()}`,
);
}
await verifyLockHeld(candidate, lockPath, lockIdentity);
return candidate;
} catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
unavailable.push(candidate.command);
continue;
}
throw error;
}
}
throw new Error(
`mutation verification is not available: no supported advisory-lock command (${unavailable.join(', ')})`,
);
}
function waitForChildExit(
child: ChildProcess,
): Promise<{ code: number | null; signal: NodeJS.Signals | null }> {
if (child.exitCode !== null || child.signalCode !== null) {
return Promise.resolve({ code: child.exitCode, signal: child.signalCode });
}
return new Promise((resolve, reject) => {
const cleanup = () => {
child.off('error', onError);
child.off('exit', onExit);
};
const onError = (error: Error) => { cleanup(); reject(error); };
const onExit = (code: number | null, signal: NodeJS.Signals | null) => {
cleanup();
resolve({ code, signal });
};
child.once('error', onError);
child.once('exit', onExit);
if (child.exitCode !== null || child.signalCode !== null) {
onExit(child.exitCode, child.signalCode);
}
});
}
export class MutationJournal {
readonly manifestPath: string;
readonly lockPath: string;
readonly ownerToken: string;
readonly lockBackend: string;
#lockHandle: FileHandle | undefined;
#lockIdentity: LockIdentity;
#stableLockIdentity = '';
#closed = false;
#unresolved: MutationExecution[];
private constructor(
manifestPath: string,
lockPath: string,
ownerToken: string,
lockHandle: FileHandle,
lockIdentity: LockIdentity,
lockBackend: string,
unresolved: MutationExecution[],
) {
this.manifestPath = manifestPath;
this.lockPath = lockPath;
this.ownerToken = ownerToken;
this.lockBackend = lockBackend;
this.#lockHandle = lockHandle;
this.#lockIdentity = lockIdentity;
this.#unresolved = unresolved;
}
static async open(options: OpenMutationJournalOptions): Promise<MutationJournal> {
const manifestPath = await realpath(options.manifestPath);
const manifestDirectory = dirname(manifestPath);
const lockPath = join(manifestDirectory, 'manifest.lock');
const { handle: lockHandle, identity: lockIdentity } = await openLockFile(lockPath);
let journal: MutationJournal | undefined;
const ownerToken = randomUUID();
try {
const candidate = await acquireLock(lockHandle, lockPath, lockIdentity, options.timeoutMs);
journal = new MutationJournal(
manifestPath,
lockPath,
ownerToken,
lockHandle,
lockIdentity,
candidate.command,
[],
);
const manifest = await journal.#ownedStep(() => readManifest(manifestPath));
const ownerMetadata = await readOwnerMetadata(lockHandle, journal.#ownedStep);
const manifestIdentity = manifest.mutationLockIdentity;
const sidecarIdentity = ownerMetadata.lockIdentity;
if (manifestIdentity !== undefined && (typeof manifestIdentity !== 'string' || !manifestIdentity.trim())) {
throw new Error('manifest mutationLockIdentity must be a non-empty string');
}
if (sidecarIdentity !== undefined && (typeof sidecarIdentity !== 'string' || !sidecarIdentity.trim())) {
throw new Error('manifest.lock lockIdentity must be a non-empty string');
}
if (manifestIdentity && !sidecarIdentity) {
throw new Error('manifest.lock lost its stable identity; refusing a replacement sidecar');
}
if (manifestIdentity && sidecarIdentity && manifestIdentity !== sidecarIdentity) {
throw new Error('manifest.lock stable identity does not match the manifest');
}
journal.#stableLockIdentity = manifestIdentity ?? sidecarIdentity as string | undefined ?? randomUUID();
await writeOwnerMetadata(lockHandle, {
lockIdentity: journal.#stableLockIdentity,
ownerToken,
host: hostname(),
pid: process.pid,
lockBackend: candidate.command,
processStartedAt: new Date(Date.now() - process.uptime() * 1_000).toISOString(),
acquiredAt: new Date().toISOString(),
}, journal.#ownedStep);
const migrated = await migrateManifest(
manifestPath,
manifest,
journal.#stableLockIdentity,
journal.#ownedStep,
);
journal.#unresolved = unresolvedEntries(migrated);
await journal.#checkOwnership();
return journal;
} catch (error) {
if (journal) await journal.#releaseLock().catch(() => undefined);
else await lockHandle.close().catch(() => undefined);
throw error;
}
}
get unresolved(): readonly MutationExecution[] {
return structuredClone(this.#unresolved);
}
async beforeDispatch(input: BeforeDispatchInput): Promise<MutationExecution> {
await this.#checkOwnership();
requireText(input.tool, 'tool');
requireText(input.origin, 'origin');
requireText(input.role, 'role');
requireText(input.fixtureRevision, 'fixtureRevision');
requireText(input.evidence, 'evidence');
if (!Number.isInteger(input.contractRevision) || input.contractRevision < 1) {
throw new Error('contractRevision must be a positive integer');
}
const manifest = await this.#ownedStep(() => readManifest(this.manifestPath));
validateJournals(manifest);
const unresolved = unresolvedEntries(manifest);
const manifestTool = input.manifestTool ?? input.tool;
const owner = manifest.tools.find((tool) => tool.id === manifestTool);
if (!owner || !Array.isArray(owner.mutationExecutions)) {
throw new Error(`manifest tool has no mutation journal: ${manifestTool}`);
}
if (input.parentExecutionId) {
const parent = unresolved.find((entry) => entry.executionId === input.parentExecutionId);
const parentOwner = manifest.tools.find((tool) =>
tool.mutationExecutions?.some((entry) => entry.executionId === input.parentExecutionId),
);
const unrelated = unresolved.filter((entry) => entry.executionId !== input.parentExecutionId);
if (!parent || parentOwner !== owner || unrelated.length > 0) {
throw new Error('cleanup dispatch is allowed only for its sole unresolved parent execution');
}
} else if (unresolved.length > 0) {
throw new Error(`mutation dispatch blocked by ${unresolved.length} unresolved execution(s)`);
}
const execution: MutationExecution = {
executionId: randomUUID(),
tool: input.tool,
contractRevision: input.contractRevision,
origin: input.origin,
role: input.role,
fixtureRevision: input.fixtureRevision,
argumentsFingerprint: fingerprintArguments(input.arguments),
startedAt: new Date().toISOString(),
state: 'started',
evidence: input.evidence,
...(input.parentExecutionId ? { parentExecutionId: input.parentExecutionId } : {}),
};
owner.mutationExecutions.push(execution);
await durableReplace(this.manifestPath, manifest, this.#ownedStep);
const stored = await this.#ownedStep(() => readManifest(this.manifestPath));
validateJournals(stored);
const persisted = stored.tools
.find((tool) => tool.id === manifestTool)
?.mutationExecutions?.find((entry) => entry.executionId === execution.executionId);
if (!persisted || JSON.stringify(persisted) !== JSON.stringify(execution)) {
throw new Error(`pre-dispatch journal entry was not durably persisted: ${execution.executionId}`);
}
this.#unresolved = unresolvedEntries(stored);
await this.#checkOwnership();
return structuredClone(execution);
}
async settle(executionId: string, input: SettlementInput): Promise<MutationExecution> {
await this.#checkOwnership();
requireText(executionId, 'executionId');
requireText(input.outcome, 'outcome');
requireText(input.evidence, 'evidence');
const manifest = await this.#ownedStep(() => readManifest(this.manifestPath));
validateJournals(manifest);
const owner = manifest.tools.find((tool) =>
tool.mutationExecutions?.some((entry) => entry.executionId === executionId),
);
const execution = owner?.mutationExecutions?.find((entry) => entry.executionId === executionId);
if (!execution) throw new Error(`mutation execution not found: ${executionId}`);
if (execution.state !== 'started') throw new Error(`mutation execution is already ${execution.state}: ${executionId}`);
if (!execution.parentExecutionId) {
const unresolvedCleanup = owner?.mutationExecutions?.find((entry) =>
entry.parentExecutionId === executionId && entry.state === 'started',
);
if (unresolvedCleanup) {
throw new Error(`mutation execution has unresolved cleanup: ${unresolvedCleanup.executionId}`);
}
}
execution.state = 'reconciled';
execution.outcome = input.outcome;
execution.reconciledAt = input.reconciledAt ?? new Date().toISOString();
execution.evidence = input.evidence;
await durableReplace(this.manifestPath, manifest, this.#ownedStep);
const stored = await this.#ownedStep(() => readManifest(this.manifestPath));
validateJournals(stored);
this.#unresolved = unresolvedEntries(stored);
await this.#checkOwnership();
return structuredClone(execution);
}
async close(): Promise<void> {
if (this.#closed) return;
let failure: unknown;
try {
if (!failure) {
await syncDirectory(dirname(this.manifestPath), this.#ownedStep);
await writeOwnerMetadata(this.#lockHandle!, {
lockIdentity: this.#stableLockIdentity,
ownerToken: this.ownerToken,
host: hostname(),
pid: process.pid,
releasedAt: new Date().toISOString(),
}, this.#ownedStep);
}
} catch (error) {
failure = error;
}
try {
await this.#releaseLock();
} catch (error) {
failure ??= error;
}
if (failure) throw failure;
}
readonly #ownedStep: OwnedStep = async <T>(operation: () => Promise<T>): Promise<T> => {
await this.#checkOwnership();
const result = await operation();
await this.#checkOwnership();
return result;
};
async #checkOwnership(): Promise<void> {
if (this.#closed || !this.#lockHandle) {
throw new Error('mutation journal is closed');
}
const [handleInfo, pathInfo] = await Promise.all([
this.#lockHandle.stat(),
lstat(this.lockPath),
]);
if (!handleInfo.isFile() || handleInfo.nlink !== 1 || !pathInfo.isFile()
|| pathInfo.isSymbolicLink() || pathInfo.nlink !== 1
|| handleInfo.dev !== this.#lockIdentity.dev || handleInfo.ino !== this.#lockIdentity.ino
|| pathInfo.dev !== this.#lockIdentity.dev || pathInfo.ino !== this.#lockIdentity.ino) {
throw new Error('mutation journal lock identity changed');
}
}
async #releaseLock(): Promise<void> {
if (this.#closed) return;
const lockHandle = this.#lockHandle;
this.#lockHandle = undefined;
let failure: unknown;
await lockHandle?.close().catch((error) => { failure ??= error; });
this.#closed = true;
if (failure) throw failure;
}
}
export async function openMutationJournal(options: OpenMutationJournalOptions): Promise<MutationJournal> {
return MutationJournal.open(options);
}
export async function withMutationJournal<T>(
options: OpenMutationJournalOptions,
callback: (journal: MutationJournal) => Promise<T>,
): Promise<T> {
const journal = await openMutationJournal(options);
try {
return await callback(journal);
} finally {
await journal.close();
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |