`apply`

(no submodules)

Purpose

The plugin-side apply hook. The installer host owns the actual transactional materialisation (staged-tmp + atomic-rename + journal-based rollback); this hook's only job is to inspect the planned ops and return an AgentSkillsHandle summarising what was installed so postInstall can render a meaningful summary line.

Features

Counts write ops to derive the installed count.
Echoes back the resolved targetDir so postInstall doesn't need to re-derive it from ops or answers.
Pure pass-through — no fs I/O, no side effects.

Basic Example

import { apply } from "@suaveplan/install-agent-skills";

const handle = await apply(ops, ctx, ".suaveplan/skills");
console.log(`installed: ${handle.installed}`);

Advanced Example

import { apply } from "@suaveplan/install-agent-skills";
import type { FileOp, InstallerContext } from "@suaveplan/installer";

async function dryRunSummary(
    ops: ReadonlyArray<FileOp>,
    ctx: InstallerContext,
    targetDir: string
): Promise<string> {
    const handle = await apply(ops, ctx, targetDir);
    return `dry-run plan: ${handle.installed} files would land in ${handle.targetDir}`;
}

API Reference

apply(ops, ctx, targetDir): Promise<AgentSkillsHandle> — pure function returning { installed, targetDir }.

Implementation Notes

Apply is intentionally trivial because the installer host enforces transactional semantics via its own applyOps — every FileOp returned from plan is materialised through staged-tmp + atomic-rename with a journal-based rollback, so plugin-side apply does not need to perform any I/O. Plugin authors who need to perform side effects beyond what FileOp can express should do so in postInstall (where the host has already committed the apply transaction) rather than reaching into apply directly — that keeps rollback-on-failure semantics intact. The targetDir argument is threaded through from plugin.ts which extracts it from the index patch op so we don't lose it across the plan/apply boundary.

2.1 KiB Raw Blame History

apply