cbs-4px-merchant-cli 0.0.2 → 0.0.4

package/dist/services/skill-installer.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Skill installer — the single source of truth for *where* skills live, *how*
+ * they are laid down, and *which* stale files get removed.
+ *
+ * Design rules (do not break these):
+ *   1. This module never prints and never calls `process.exit`. All IO belongs
+ *      to the command layer (`src/commands/skill.ts`).
+ *   2. The skill version comes from the bundled `skill/package.json`, never
+ *      from the root `package.json`. Today the two values are identical; the
+ *      indirection keeps them separable if the skill is ever published to a
+ *      skill marketplace on its own release cadence.
+ *   3. Deletion is driven exclusively by the `files` list of the *previous*
+ *      manifest. No manifest ⇒ nothing is deleted. A missing/empty list must
+ *      never widen into "remove the whole directory".
+ *   4. Nothing machine-specific may be written into SKILL.md or reference/*.
+ *      Host state (which dirs were touched, whether an API Key is configured)
+ *      belongs in terminal output only.
+ */
+/**
+ * Skill install dir name — the package name with any npm scope stripped
+ * (e.g. `cbs-4px-merchant-cli`). Previously duplicated in scripts/build.js,
+ * scripts/postinstall.js and src/cli.ts; this is now the only copy.
+ */
+export declare const SKILL_DIR_NAME: string;
+/** Legacy version marker written by <= 0.0.2 postinstall. Still written. */
+export declare const VERSION_MARKER = ".skill-version";
+/** npm-style manifest, doubling as the install receipt. */
+export declare const MANIFEST_FILE = "package.json";
+/** Stamp identifying this CLI as the installer of a target directory. */
+export declare const INSTALL_METHOD = "cli";
+export interface AgentDef {
+    /** Stable id accepted by `--agent`. */
+    id: string;
+    label: string;
+    /** Path segments under $HOME that contain the tool's `skills` dir. */
+    segments: string[];
+}
+/** Whitelisted agent ids, for `--agent` validation and error messages. */
+export declare function knownAgentIds(): string[];
+export interface SkillManifest {
+    name: string;
+    version: string;
+    description?: string;
+    /** Relative paths owned by this install — the only paths ever deleted. */
+    files: string[];
+    installSource?: string;
+    installMethod?: string;
+    installedAt?: string;
+}
+export type TargetState = 
+/** Directory absent or empty — clean install. */
+'fresh'
+/** Manifest present and `installSource` is us — normal upgrade. */
+ | 'owned'
+/** No manifest but a legacy `.skill-version` — ours, from <= 0.0.2. */
+ | 'legacy'
+/** Manifest present but installed by someone else (e.g. aone-kit). */
+ | 'foreign'
+/** Non-empty, no manifest, no legacy marker — provenance unknown. */
+ | 'unknown';
+export interface TargetPlan {
+    agent: string;
+    label: string;
+    dir: string;
+    state: TargetState;
+    installed_version: string | null;
+    /** Present when `state === 'foreign'`. */
+    installed_source?: string;
+    /** Stale paths to delete = previous manifest `files` minus the new list. */
+    remove: string[];
+    /** True when the target is skipped unless `--force` is given. */
+    blocked: boolean;
+}
+export interface SkillSource {
+    name: string;
+    version: string;
+    description?: string;
+    root: string;
+    /** Relative paths that will be written into every target. */
+    files: string[];
+}
+export interface InstallPlan {
+    skill: SkillSource;
+    targets: TargetPlan[];
+}
+export type TargetOutcome = 'installed' | 'updated' | 'skipped' | 'failed';
+export interface TargetResult {
+    agent: string;
+    label: string;
+    dir: string;
+    outcome: TargetOutcome;
+    /** Version that was there before this run. */
+    previous_version: string | null;
+    removed: string[];
+    reason?: string;
+}
+export interface ResolveOptions {
+    home?: string;
+    /** Restrict to these agent ids; empty/undefined means every target. */
+    agents?: string[];
+    /** Override the bundled skill dir (tests only). */
+    skillRoot?: string;
+}
+/** Thrown for caller mistakes the command layer must render as a clean error. */
+export declare class SkillInstallerError extends Error {
+    readonly code: string;
+    readonly hint?: string | undefined;
+    constructor(message: string, code: string, hint?: string | undefined);
+}
+/** Bundled skill dir: `<pkg>/skill`, from both `dist/` and `src/` layouts. */
+export declare function resolveSkillRoot(override?: string): string;
+/**
+ * Read the bundled skill and enumerate what will be written.
+ *
+ * The file list is walked from disk rather than taken from the manifest's
+ * `files` field: disk is what actually gets copied, so deriving the receipt
+ * from it keeps the manifest from ever describing files that aren't there.
+ */
+export declare function readSkillSource(override?: string): SkillSource;
+/**
+ * Whitelist ∪ discovery, both gated on the directory looking actually used.
+ *
+ * An explicit `--agent` bypasses the in-use heuristic: naming a tool is a
+ * direct instruction, and the heuristic exists only to guess for the user.
+ */
+export declare function resolveTargets(opts?: ResolveOptions): AgentDef[];
+/** Absolute install dir of the skill for one agent. */
+export declare function targetDirFor(home: string, agent: AgentDef): string;
+/**
+ * All candidate install dirs, used by the CLI's drift check. Includes
+ * whitelisted tools whose root exists plus discovered ones — so a tool that is
+ * only reachable via discovery (e.g. OpenCode) can no longer be invisible to
+ * drift detection.
+ */
+export declare function listSkillDirs(home?: string): string[];
+/** Validate `--agent` values against the whitelist, a1-style. */
+export declare function validateAgentIds(ids: string[]): void;
+/** Read a target's manifest. Returns null when absent or unparsable. */
+export declare function readTargetManifest(dir: string): SkillManifest | null;
+/** Legacy plain-text version marker written by <= 0.0.2 postinstall. */
+export declare function readLegacyVersion(dir: string): string | null;
+/** Installed version of a target, manifest first then legacy marker. */
+export declare function readInstalledVersion(dir: string): string | null;
+/** Classify a target directory before touching it. */
+export declare function inspectTarget(dir: string, source: SkillSource): TargetPlan['state'];
+export declare function buildPlan(source: SkillSource, opts?: ResolveOptions): InstallPlan;
+/**
+ * Reject anything that could escape the target dir. Manifests are read from
+ * disk and may have been edited by hand, so their paths are untrusted input.
+ */
+export declare function isSafeRelativePath(p: string): boolean;
+export interface ApplyOptions {
+    /** Overwrite targets owned by someone else / of unknown provenance. */
+    force?: boolean;
+}
+/** Lay the skill down on every planned target. Never throws per target. */
+export declare function applyPlan(plan: InstallPlan, opts?: ApplyOptions): TargetResult[];
+export interface UninstallPlan {
+    agent: string;
+    label: string;
+    dir: string;
+    state: TargetState;
+    installed_version: string | null;
+    installed_source?: string;
+    /** Paths that will be removed — manifest `files` plus the legacy marker. */
+    remove: string[];
+    blocked: boolean;
+}
+/**
+ * Plan removal. Deletion is still manifest-bounded: without a receipt we only
+ * remove the files this CLI is known to write, never the directory wholesale.
+ */
+export declare function buildUninstallPlan(source: SkillSource, opts?: ResolveOptions): UninstallPlan[];
+export declare function applyUninstall(plans: UninstallPlan[], opts?: ApplyOptions): TargetResult[];