@yagni-app/code 1.0.5 → 1.0.7

package/dist/pluginStore.d.ts

@@ -0,0 +1,170 @@
+/**
+ * YAGNI Code's own plugin ledger — the state behind `yagni plugin …`.
+ *
+ * Layout under `~/.yagni-code/plugins/` (Claude Code's shape, our own files —
+ * we never write into `~/.claude`, whose ledger format is versioned and
+ * undocumented; we only read it, see claudePlugins.ts):
+ *
+ *   known_marketplaces.json    marketplace name → source + local checkout
+ *   installed_plugins.json     `name@marketplace` → installed entries
+ *   marketplaces/<name>/       git checkout of a marketplace repo
+ *   cache/<mp>/<plugin>/<ver>/ the installed copy of a plugin
+ *
+ * Marketplace sources: `owner/repo` (GitHub over HTTPS, the developer's own
+ * git credentials), any git URL (ssh or https), or a local directory (its
+ * catalog is read in place; installs still copy into the cache, so edits land
+ * on the next `plugin update`). Only marketplace entries with relative-path
+ * sources install;
+ * object sources (github/url/npm/archive) are network installs of a second
+ * repo and are reported as unsupported rather than fetched.
+ *
+ * All git calls go through an injectable runner so tests never touch the
+ * network. Writes are atomic (temp + rename).
+ */
+import { type Marketplace, type MarketplaceEntry } from "./claudePlugins.js";
+export type MarketplaceSource = {
+    source: "github";
+    repo: string;
+} | {
+    source: "git";
+    url: string;
+} | {
+    source: "directory";
+    path: string;
+};
+export interface KnownMarketplace {
+    source: MarketplaceSource;
+    /** Marketplace root: the checkout (git) or the directory itself. */
+    installLocation: string;
+    addedAt: string;
+}
+export type PluginInstallScope = "user" | "project";
+export interface InstalledPlugin {
+    scope: PluginInstallScope;
+    /** Absolute path of the installed copy (cache dir). */
+    installPath: string;
+    version: string;
+    /** Repo root the project-scope install applies to. */
+    projectPath?: string;
+    enabled: boolean;
+    installedAt: string;
+}
+export interface PluginLedger {
+    version: 1;
+    plugins: Record<string, InstalledPlugin[]>;
+}
+export interface GitResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+export type GitRunner = (args: string[], opts: {
+    cwd?: string;
+}) => Promise<GitResult>;
+export declare const defaultGit: GitRunner;
+export declare class PluginStoreError extends Error {
+}
+export declare function pluginsHome(env?: NodeJS.ProcessEnv, userHome?: string): string;
+export declare function readKnownMarketplaces(home: string): Record<string, KnownMarketplace>;
+export declare function writeKnownMarketplaces(home: string, value: Record<string, KnownMarketplace>): void;
+export declare function readLedger(home: string): PluginLedger;
+export declare function writeLedger(home: string, ledger: PluginLedger): void;
+/** Interpret the `marketplace add` argument. Null when it is none of the shapes. */
+export declare function parseMarketplaceSource(input: string, cwd: string): MarketplaceSource | null;
+export declare function cloneUrl(source: MarketplaceSource): string | null;
+export declare function describeSource(source: MarketplaceSource): string;
+export interface StoreDeps {
+    home: string;
+    git?: GitRunner;
+    now?: () => Date;
+}
+export declare function addMarketplace(source: MarketplaceSource, deps: StoreDeps): Promise<{
+    name: string;
+    marketplace: Marketplace;
+    installLocation: string;
+}>;
+export declare function knownMarketplaceOrThrow(name: string, deps: StoreDeps): KnownMarketplace;
+/** Pull a git marketplace; a directory marketplace is always current. Returns whether anything changed. */
+export declare function updateMarketplace(name: string, deps: StoreDeps): Promise<{
+    changed: boolean;
+    head: string | null;
+}>;
+export declare function removeMarketplace(name: string, deps: StoreDeps): {
+    removedPlugins: string[];
+};
+export declare function splitKey(key: string): {
+    plugin: string;
+    marketplace: string | null;
+};
+export interface ResolvedPlugin {
+    key: string;
+    plugin: string;
+    marketplace: string;
+    marketplaceRoot: string;
+    entry: MarketplaceEntry;
+    /** Plugin source dir inside the marketplace checkout. */
+    sourceRoot: string;
+    version: string;
+}
+/**
+ * Find `<plugin>[@marketplace]` across known marketplaces. Without an
+ * explicit marketplace the name must be unique across them.
+ */
+export declare function resolvePluginSpec(spec: string, deps: StoreDeps): Promise<ResolvedPlugin>;
+export interface InstallOptions {
+    scope: PluginInstallScope;
+    /** Required for scope "project": the repo root the install applies to. */
+    projectPath?: string;
+}
+export declare function installPlugin(spec: string, opts: InstallOptions, deps: StoreDeps): Promise<{
+    resolved: ResolvedPlugin;
+    installPath: string;
+    replaced: InstalledPlugin | null;
+}>;
+/** The ledger key an uninstall/enable/disable spec refers to; must be unambiguous. */
+export declare function resolveInstalledKey(spec: string, deps: StoreDeps): string;
+export interface UninstallOptions {
+    scope?: PluginInstallScope;
+    projectPath?: string;
+}
+export declare function uninstallPlugin(spec: string, opts: UninstallOptions, deps: StoreDeps): {
+    key: string;
+    removed: InstalledPlugin[];
+};
+export declare function setPluginEnabled(spec: string, enabled: boolean, deps: StoreDeps): {
+    key: string;
+    count: number;
+};
+export interface UpdateReport {
+    key: string;
+    from: string;
+    to: string;
+    /** Files re-synced from the marketplace even when the version string is unchanged. */
+    refreshed: boolean;
+}
+/**
+ * Refresh marketplaces and re-sync installed plugins from them. Every
+ * installed plugin is re-copied (a content change with no version bump still
+ * lands), and version changes are reported.
+ */
+export declare function updatePlugins(spec: string | undefined, deps: StoreDeps): Promise<{
+    marketplaces: {
+        name: string;
+        changed: boolean;
+    }[];
+    plugins: UpdateReport[];
+    errors: string[];
+}>;
+/** Marketplace catalog entries with their install status (for `plugin list --available`). */
+export declare function catalog(deps: StoreDeps): {
+    marketplace: string;
+    entries: {
+        name: string;
+        version: string | null;
+        description: string | null;
+        installable: boolean;
+    }[];
+}[];
+/** Remove empty cache parents left behind by uninstalls (best effort). */
+export declare function pruneCache(home: string): void;
+//# sourceMappingURL=pluginStore.d.ts.map