`detect`

(no submodules)

Purpose

Reports what is already present at the target skills directory. The host calls detect(ctx) before prompts run; the result feeds into the user's decision about whether to proceed, --force, or supply --only / --exclude to limit the install. Detect is read-only: it only inspects ctx.fs and never mutates state.

Features

Reports alreadyInstalled: boolean based on the target directory's presence — false means a fresh install path.
Lists existing skill directories as conflicts (excluding index.json) so the host UI can show what would be touched.
Defaults to scanning .suaveplan/skills relative to ctx.cwd; the optional second argument lets callers pre-supply a target dir from partial answers.
Tolerant of degenerate states — when listDir throws (e.g. the target is a file masquerading as a dir), returns conflicts: [] rather than propagating the error.

Basic Example

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

const result = await detect(ctx);
if (result.alreadyInstalled) {
    console.warn("Skills already installed; use --force to overwrite");
}

Advanced Example

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

const result = await detect(ctx, { targetDir: "/srv/agent/skills" });
if (result.alreadyInstalled && (result.conflicts?.length ?? 0) > 0) {
    console.log("Existing skills:");
    for (const id of result.conflicts ?? []) {
        console.log(`  - ${id}`);
    }
    console.log(
        `Run again with --only ${result.conflicts?.join(",")} to refresh just those`
    );
}

API Reference

detect(ctx, answers?): Promise<DetectResult> — answers may be partial; only targetDir is consulted at this stage.
Return shape — { alreadyInstalled, conflicts?, notes? } from the host's DetectResult type.

Implementation Notes

Detect runs before prompts so it can't access fully-validated answers; the partial answers parameter lets the bin pass through whatever the user already supplied (e.g. via --answers <file>). Reading the target's directory listing instead of stating each known skill's manifest is cheaper and gives the user a holistic view — including unrelated skills that were dropped into the directory by hand.

2.3 KiB Raw Blame History

detect