@oh-my-pi/pi-coding-agent 15.1.0 → 15.1.2

package/dist/types/extensibility/plugins/marketplace/fetcher.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Marketplace catalog fetcher.
+ *
+ * Classifies a source string, resolves it, and loads the catalog.
+ */
+import type { MarketplaceCatalog, MarketplaceSourceType } from "./types";
+export interface FetchResult {
+    catalog: MarketplaceCatalog;
+    /** For git sources: path to the cloned marketplace directory. */
+    clonePath?: string;
+}
+/**
+ * Classify a marketplace source string into one of the four source types.
+ *
+ * Rules are ordered; the first match wins. Protocol/pattern checks (rules 1-3)
+ * run before any path.isAbsolute() check so that SCP-style git@ URLs are
+ * never misclassified as local paths on Windows.
+ *
+ * @throws if the source format is unrecognized.
+ */
+export declare function classifySource(source: string): MarketplaceSourceType;
+/**
+ * Parse and validate a marketplace.json catalog from raw JSON content.
+ *
+ * Required fields: name (valid name segment), owner.name, plugins array.
+ * Each plugin entry requires name (string) and source (string or object
+ * with a "source" field). Extra fields are preserved via spread.
+ *
+ * @throws on JSON parse failure or missing/invalid required fields.
+ */
+export declare function parseMarketplaceCatalog(content: string, filePath: string): MarketplaceCatalog;
+/**
+ * Fetch a marketplace catalog from a source.
+ *
+ * Dispatches on the source type: local filesystem paths are read directly;
+ * GitHub/git sources are cloned with `git`; URL sources are fetched over HTTP.
+ *
+ * @param source   Source identifier: path, GitHub shorthand, git URL, or HTTP URL.
+ * @param cacheDir Cache directory root for non-local sources.
+ */
+export declare function fetchMarketplace(source: string, cacheDir: string): Promise<FetchResult>;
+/**
+ * Promote a temporary clone directory to its final cache location.
+ *
+ * Callers should invoke this only after duplicate/drift checks pass.
+ * Removes any existing directory at the target path before renaming.
+ */
+export declare function promoteCloneToCache(tmpDir: string, cacheDir: string, name: string): Promise<string>;

package/dist/types/extensibility/plugins/marketplace/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./cache";
+export * from "./fetcher";
+export * from "./manager";
+export * from "./registry";
+export * from "./source-resolver";
+export * from "./types";

package/dist/types/extensibility/plugins/marketplace/manager.d.ts

@@ -0,0 +1,57 @@
+/**
+ * MarketplaceManager — orchestrates registry, fetcher, resolver, and cache.
+ *
+ * Constructor takes explicit paths for testability (same pattern as registry.ts).
+ * The `clearPluginRootsCache` dependency is injected so callers can provide
+ * the real `clearClaudePluginRootsCache` while tests supply a counter stub.
+ */
+import type { InstalledPluginEntry, InstalledPluginSummary, MarketplacePluginEntry, MarketplaceRegistryEntry } from "./types";
+export interface MarketplaceManagerOptions {
+    marketplacesRegistryPath: string;
+    installedRegistryPath: string;
+    /**
+     * Path to the project-scoped installed_plugins.json.
+     * Required when installPlugin / uninstallPlugin is called with scope: "project".
+     * Resolved by resolveActiveProjectRegistryPath(cwd) in callers.
+     */
+    projectInstalledRegistryPath?: string;
+    marketplacesCacheDir: string;
+    pluginsCacheDir: string;
+    /** Injected for testing; production callers pass clearClaudePluginRootsCache.
+     *  Receives any additional file paths that should also be invalidated from the fs cache.
+     */
+    clearPluginRootsCache?: (extraPaths?: readonly string[]) => void;
+}
+export declare class MarketplaceManager {
+    #private;
+    constructor(options: MarketplaceManagerOptions);
+    addMarketplace(source: string): Promise<MarketplaceRegistryEntry>;
+    removeMarketplace(name: string): Promise<void>;
+    updateMarketplace(name: string): Promise<MarketplaceRegistryEntry>;
+    updateAllMarketplaces(): Promise<MarketplaceRegistryEntry[]>;
+    listMarketplaces(): Promise<MarketplaceRegistryEntry[]>;
+    listAvailablePlugins(marketplace?: string): Promise<MarketplacePluginEntry[]>;
+    getPluginInfo(name: string, marketplace: string): Promise<MarketplacePluginEntry | null>;
+    installPlugin(name: string, marketplace: string, options?: {
+        force?: boolean;
+        scope?: "user" | "project";
+    }): Promise<InstalledPluginEntry>;
+    uninstallPlugin(pluginId: string, scope?: "user" | "project"): Promise<void>;
+    listInstalledPlugins(): Promise<InstalledPluginSummary[]>;
+    setPluginEnabled(pluginId: string, enabled: boolean, scope?: "user" | "project"): Promise<void>;
+    refreshStaleMarketplaces(): Promise<void>;
+    checkForUpdates(): Promise<Array<{
+        pluginId: string;
+        scope: "user" | "project";
+        from: string;
+        to: string;
+    }>>;
+    upgradePlugin(pluginId: string, scope?: "user" | "project"): Promise<InstalledPluginEntry>;
+    upgradePluginAcrossScopes(pluginId: string): Promise<InstalledPluginEntry[]>;
+    upgradeAllPlugins(): Promise<Array<{
+        pluginId: string;
+        scope: "user" | "project";
+        from: string;
+        to: string;
+    }>>;
+}

package/dist/types/extensibility/plugins/marketplace/registry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Registry read/write operations for the marketplace plugin system.
+ *
+ * Two registries:
+ *   - marketplaces.json under getConfigRootDir() — which catalogs the user has added
+ *   - installed_plugins.json under getPluginsDir() — which plugins are installed
+ *
+ * Read/write functions accept explicit file paths so callers control the
+ * location. Path helpers compute the default paths from the dir singleton.
+ *
+ * Both use atomic write (tmp + rename). On Windows, rename over existing file
+ * can fail with EPERM — fallback: unlink target then rename.
+ */
+import type { InstalledPluginEntry, InstalledPluginsRegistry, MarketplaceRegistryEntry, MarketplacesRegistry } from "./types";
+export declare function getMarketplacesRegistryPath(): string;
+export declare function getInstalledPluginsRegistryPath(): string;
+export declare function getMarketplacesCacheDir(): string;
+export declare function getPluginsCacheDir(): string;
+export declare function readMarketplacesRegistry(filePath: string): Promise<MarketplacesRegistry>;
+export declare function writeMarketplacesRegistry(filePath: string, reg: MarketplacesRegistry): Promise<void>;
+export declare function readInstalledPluginsRegistry(filePath: string): Promise<InstalledPluginsRegistry>;
+export declare function writeInstalledPluginsRegistry(filePath: string, reg: InstalledPluginsRegistry): Promise<void>;
+export declare function addMarketplaceEntry(reg: MarketplacesRegistry, entry: MarketplaceRegistryEntry): MarketplacesRegistry;
+export declare function removeMarketplaceEntry(reg: MarketplacesRegistry, name: string): MarketplacesRegistry;
+export declare function getMarketplaceEntry(reg: MarketplacesRegistry, name: string): MarketplaceRegistryEntry | undefined;
+export declare function addInstalledPlugin(reg: InstalledPluginsRegistry, id: string, entry: InstalledPluginEntry): InstalledPluginsRegistry;
+export declare function removeInstalledPlugin(reg: InstalledPluginsRegistry, id: string): InstalledPluginsRegistry;
+export declare function getInstalledPlugin(reg: InstalledPluginsRegistry, id: string): InstalledPluginEntry[] | undefined;
+/**
+ * Collect all installPath values referenced by any of the provided registries.
+ * Use this before deleting a cached plugin directory to verify it is not still
+ * referenced by another scope's registry.
+ */
+export declare function collectReferencedPaths(...registries: InstalledPluginsRegistry[]): Set<string>;

package/dist/types/extensibility/plugins/marketplace/source-resolver.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Source resolver for marketplace plugin entries.
+ *
+ * Resolves plugin sources to absolute local directory paths:
+ *   - Relative string "./plugins/foo" → path within marketplace clone
+ *   - { source: "url", url: "https://...git" } → git clone
+ *   - { source: "github", repo: "owner/repo" } → git clone from GitHub
+ *   - { source: "git-subdir", url: "...", path: "sub/dir" } → git clone + subdir
+ *   - { source: "npm", ... } → not yet supported
+ */
+import type { MarketplaceCatalogMetadata, MarketplacePluginEntry } from "./types";
+export interface ResolveContext {
+    /** Absolute path to the cloned/local marketplace directory. Required for relative sources. */
+    marketplaceClonePath?: string;
+    /** Catalog metadata — used for `pluginRoot` prepend. */
+    catalogMetadata?: MarketplaceCatalogMetadata;
+    /** Scratch directory for sources that require cloning or extraction. */
+    tmpDir: string;
+}
+/**
+ * Resolve a plugin source to an absolute local directory path.
+ *
+ * The resolved path is verified to exist on disk.
+ */
+export declare function resolvePluginSource(entry: MarketplacePluginEntry, context: ResolveContext): Promise<{
+    dir: string;
+    tempCloneRoot?: string;
+}>;

package/dist/types/extensibility/plugins/marketplace/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Marketplace plugin system types.
+ *
+ * Two registries:
+ *   - MarketplacesRegistry: which marketplace catalogs the user has added (config)
+ *   - InstalledPluginsRegistry: which plugins are installed (data, Claude Code-compatible)
+ *
+ * The installed registry MUST pass `parseClaudePluginsRegistry()` validation —
+ * it uses `version: 2` (numeric) and `plugins: Record<string, ...[]>`.
+ */
+/** Validate a plugin or marketplace name segment. */
+export declare function isValidNameSegment(s: string): boolean;
+/** Build canonical plugin ID: `"name@marketplace"`. Both segments are validated. */
+export declare function buildPluginId(name: string, marketplace: string): string;
+/** Parse `"name@marketplace"` → `{ name, marketplace }` or `null`. */
+export declare function parsePluginId(id: string): {
+    name: string;
+    marketplace: string;
+} | null;
+export interface MarketplaceCatalogOwner {
+    name: string;
+    email?: string;
+}
+export interface MarketplaceCatalogMetadata {
+    description?: string;
+    version?: string;
+    /** If set, prepended to relative plugin source paths. */
+    pluginRoot?: string;
+}
+export interface MarketplaceCatalog {
+    name: string;
+    owner: MarketplaceCatalogOwner;
+    metadata?: MarketplaceCatalogMetadata;
+    plugins: MarketplacePluginEntry[];
+}
+export interface MarketplacePluginAuthor {
+    name: string;
+    email?: string;
+}
+export interface MarketplacePluginEntry {
+    name: string;
+    source: PluginSource;
+    description?: string;
+    version?: string;
+    author?: MarketplacePluginAuthor;
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+    category?: string;
+    tags?: string[];
+    strict?: boolean;
+    commands?: string | string[];
+    agents?: string | string[];
+    hooks?: string | Record<string, unknown>;
+    mcpServers?: string | Record<string, unknown>;
+    lspServers?: string | Record<string, unknown>;
+}
+export type PluginSource = string | PluginSourceGitHub | PluginSourceUrl | PluginSourceGitSubdir | PluginSourceNpm;
+export interface PluginSourceGitHub {
+    source: "github";
+    repo: string;
+    ref?: string;
+    sha?: string;
+}
+export interface PluginSourceUrl {
+    source: "url";
+    url: string;
+    ref?: string;
+    sha?: string;
+}
+export interface PluginSourceGitSubdir {
+    source: "git-subdir";
+    url: string;
+    path: string;
+    ref?: string;
+    sha?: string;
+}
+export interface PluginSourceNpm {
+    source: "npm";
+    package: string;
+    version?: string;
+    registry?: string;
+}
+export interface MarketplacesRegistry {
+    version: 1;
+    marketplaces: MarketplaceRegistryEntry[];
+}
+export type MarketplaceSourceType = "github" | "git" | "url" | "local";
+export interface MarketplaceRegistryEntry {
+    name: string;
+    sourceType: MarketplaceSourceType;
+    sourceUri: string;
+    catalogPath: string;
+    addedAt: string;
+    updatedAt: string;
+}
+export interface InstalledPluginsRegistry {
+    /** MUST be 2 — parseClaudePluginsRegistry rejects non-numeric version. */
+    version: 2;
+    plugins: Record<string, InstalledPluginEntry[]>;
+}
+export interface InstalledPluginEntry {
+    scope: "user" | "project";
+    /** Absolute path to cached plugin directory. */
+    installPath: string;
+    version: string;
+    /** ISO 8601 date string. */
+    installedAt: string;
+    /** ISO 8601 date string. */
+    lastUpdated: string;
+    /** For git-sourced plugins. */
+    gitCommitSha?: string;
+    /** OMP extension — not in Claude Code's type. CLI/UI concern only in v1. */
+    enabled?: boolean;
+}
+/**
+ * A merged view of an installed plugin, combining entries from both the user and
+ * project registries. Returned by MarketplaceManager.listInstalledPlugins().
+ *
+ * `shadowedBy` is set on user-scoped summaries when the same plugin ID also exists
+ * in the project registry — the project entry takes precedence for capability loading.
+ */
+export interface InstalledPluginSummary {
+    id: string;
+    scope: "user" | "project";
+    entries: InstalledPluginEntry[];
+    /** Set when a user-scoped plugin is overridden by a project-scoped install. */
+    shadowedBy?: "project";
+}

package/dist/types/extensibility/plugins/parser.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Feature bracket parser for plugin specifiers.
+ *
+ * Supports syntax like:
+ * - "my-plugin" -> base features (null)
+ * - "my-plugin[search,web]" -> specific features
+ * - "my-plugin[*]" -> all features
+ * - "my-plugin[]" -> no optional features
+ * - "@scope/plugin@1.2.3[feat]" -> scoped with version and features
+ */
+export interface ParsedPluginSpec {
+    /** Package name (may include version specifier like @1.0.0) */
+    packageName: string;
+    /**
+     * Feature selection:
+     * - null: use defaults (base features on first install, preserve on reinstall)
+     * - "*": all features
+     * - string[]: specific features (empty array = no optional features)
+     */
+    features: string[] | null | "*";
+}
+/**
+ * Parse plugin specifier with feature bracket syntax.
+ *
+ * @example
+ * parsePluginSpec("my-plugin") // { packageName: "my-plugin", features: null }
+ * parsePluginSpec("my-plugin[search,web]") // { packageName: "my-plugin", features: ["search", "web"] }
+ * parsePluginSpec("my-plugin[*]") // { packageName: "my-plugin", features: "*" }
+ * parsePluginSpec("my-plugin[]") // { packageName: "my-plugin", features: [] }
+ * parsePluginSpec("@scope/pkg@1.2.3[feat]") // { packageName: "@scope/pkg@1.2.3", features: ["feat"] }
+ */
+export declare function parsePluginSpec(spec: string): ParsedPluginSpec;
+/**
+ * Format a parsed plugin spec back to string form.
+ *
+ * @example
+ * formatPluginSpec({ packageName: "pkg", features: null }) // "pkg"
+ * formatPluginSpec({ packageName: "pkg", features: "*" }) // "pkg[*]"
+ * formatPluginSpec({ packageName: "pkg", features: [] }) // "pkg[]"
+ * formatPluginSpec({ packageName: "pkg", features: ["a", "b"] }) // "pkg[a,b]"
+ */
+export declare function formatPluginSpec(spec: ParsedPluginSpec): string;
+/**
+ * Extract the base package name without version specifier.
+ * Used for path lookups after npm install.
+ *
+ * @example
+ * extractPackageName("lodash@4.17.21") // "lodash"
+ * extractPackageName("@scope/pkg@1.0.0") // "@scope/pkg"
+ * extractPackageName("@scope/pkg") // "@scope/pkg"
+ */
+export declare function extractPackageName(specifier: string): string;

package/dist/types/extensibility/plugins/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Feature definition for selective plugin installation.
+ * Features allow plugins to expose optional functionality.
+ */
+export interface PluginFeature {
+    /** Human-readable description */
+    description?: string;
+    /** Whether this feature is enabled by default */
+    default?: boolean;
+    /** Additional extension entry points provided by this feature */
+    extensions?: string[];
+    /** Additional tool entry points provided by this feature */
+    tools?: string[];
+    /** Additional hook entry points provided by this feature */
+    hooks?: string[];
+    /** Additional command files provided by this feature */
+    commands?: string[];
+}
+/**
+ * Plugin manifest from package.json omp or pi field.
+ */
+export interface PluginManifest {
+    /** Plugin display name (defaults to package name) */
+    name?: string;
+    /** Plugin version (copied from package.json version) */
+    version: string;
+    /** Human-readable description */
+    description?: string;
+    /** Entry point for base tools (relative path from package root) */
+    tools?: string;
+    /** Entry point for base hooks (relative path from package root) */
+    hooks?: string;
+    /** Extension entry points (relative paths from package root) */
+    extensions?: string[];
+    /** Command files (relative paths from package root) */
+    commands?: string[];
+    /** Feature definitions for selective installation */
+    features?: Record<string, PluginFeature>;
+    /** Settings schema for plugin configuration */
+    settings?: Record<string, PluginSettingSchema>;
+}
+export type PluginSettingType = "string" | "number" | "boolean" | "enum";
+interface PluginSettingBase {
+    /** Setting type */
+    type: PluginSettingType;
+    /** Human-readable description */
+    description?: string;
+    /** If true, mask value in UI and logs */
+    secret?: boolean;
+    /** Environment variable to use as fallback value */
+    env?: string;
+}
+export interface StringSetting extends PluginSettingBase {
+    type: "string";
+    default?: string;
+}
+export interface NumberSetting extends PluginSettingBase {
+    type: "number";
+    default?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+export interface BooleanSetting extends PluginSettingBase {
+    type: "boolean";
+    default?: boolean;
+}
+export interface EnumSetting extends PluginSettingBase {
+    type: "enum";
+    /** Allowed values */
+    values: string[];
+    default?: string;
+}
+export type PluginSettingSchema = StringSetting | NumberSetting | BooleanSetting | EnumSetting;
+/**
+ * Represents an installed plugin with full metadata.
+ */
+export interface InstalledPlugin {
+    /** npm package name */
+    name: string;
+    /** Installed version */
+    version: string;
+    /** Absolute path to package directory */
+    path: string;
+    /** Parsed omp/pi manifest */
+    manifest: PluginManifest;
+    /**
+     * Enabled features:
+     * - null: use defaults (all features with default: true)
+     * - string[]: specific features enabled
+     */
+    enabledFeatures: string[] | null;
+    /** Whether the plugin is enabled */
+    enabled: boolean;
+}
+/**
+ * Per-plugin runtime state stored in lock file.
+ */
+export interface PluginRuntimeState {
+    /** Installed version */
+    version: string;
+    /** Enabled features (null = defaults) */
+    enabledFeatures: string[] | null;
+    /** Whether the plugin is enabled */
+    enabled: boolean;
+}
+/**
+ * Runtime configuration persisted to omp-plugins.lock.json.
+ * Tracks plugin states and settings across sessions.
+ */
+export interface PluginRuntimeConfig {
+    /** Plugin states keyed by package name */
+    plugins: Record<string, PluginRuntimeState>;
+    /** Plugin settings keyed by package name, then setting key */
+    settings: Record<string, Record<string, unknown>>;
+}
+/**
+ * Project-local plugin overrides (stored in .omp/plugin-overrides.json).
+ * Allows per-project plugin configuration without modifying global state.
+ */
+export interface ProjectPluginOverrides {
+    /** Plugins to disable in this project */
+    disabled?: string[];
+    /** Per-plugin feature overrides */
+    features?: Record<string, string[]>;
+    /** Per-plugin setting overrides */
+    settings?: Record<string, Record<string, unknown>>;
+}
+export interface DoctorCheck {
+    /** Check identifier */
+    name: string;
+    /** Check result status */
+    status: "ok" | "warning" | "error";
+    /** Human-readable message */
+    message: string;
+    /** Whether --fix resolved this issue */
+    fixed?: boolean;
+}
+export interface InstallOptions {
+    /** Overwrite existing without prompting */
+    force?: boolean;
+    /** Preview changes without applying */
+    dryRun?: boolean;
+}
+export interface DoctorOptions {
+    /** Attempt automatic fixes */
+    fix?: boolean;
+}
+export {};