@oh-my-pi/pi-coding-agent 1.337.0

package/src/core/plugins/parser.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 function parsePluginSpec(spec: string): ParsedPluginSpec {
+	// Find the last bracket pair (to handle version specifiers like @1.0.0)
+	const bracketStart = spec.lastIndexOf("[");
+	const bracketEnd = spec.lastIndexOf("]");
+
+	// No brackets or malformed -> base features
+	if (bracketStart === -1 || bracketEnd === -1 || bracketEnd < bracketStart) {
+		return { packageName: spec, features: null };
+	}
+
+	const packageName = spec.slice(0, bracketStart);
+	const featureStr = spec.slice(bracketStart + 1, bracketEnd).trim();
+
+	// All features
+	if (featureStr === "*") {
+		return { packageName, features: "*" };
+	}
+
+	// No optional features
+	if (featureStr === "") {
+		return { packageName, features: [] };
+	}
+
+	// Specific features (comma-separated)
+	const features = featureStr
+		.split(",")
+		.map((f) => f.trim())
+		.filter(Boolean);
+
+	return { packageName, features };
+}
+
+/**
+ * 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 function formatPluginSpec(spec: ParsedPluginSpec): string {
+	if (spec.features === null) {
+		return spec.packageName;
+	}
+	if (spec.features === "*") {
+		return `${spec.packageName}[*]`;
+	}
+	if (spec.features.length === 0) {
+		return `${spec.packageName}[]`;
+	}
+	return `${spec.packageName}[${spec.features.join(",")}]`;
+}
+
+/**
+ * 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 function extractPackageName(specifier: string): string {
+	// Handle scoped packages: @scope/name@version -> @scope/name
+	if (specifier.startsWith("@")) {
+		const match = specifier.match(/^(@[^/]+\/[^@]+)/);
+		return match ? match[1] : specifier;
+	}
+	// Unscoped: name@version -> name
+	return specifier.replace(/@[^@]+$/, "");
+}

package/src/core/plugins/paths.ts

@@ -0,0 +1,32 @@
+import { homedir } from "os";
+import { join } from "path";
+import { CONFIG_DIR_NAME } from "../../config.js";
+
+// =============================================================================
+// Plugin Directory Paths
+// =============================================================================
+
+/** Root plugin directory: ~/.pi/plugins (not under agent/) */
+export function getPluginsDir(): string {
+	return join(homedir(), CONFIG_DIR_NAME, "plugins");
+}
+
+/** Where npm installs packages: ~/.pi/plugins/node_modules */
+export function getPluginsNodeModules(): string {
+	return join(getPluginsDir(), "node_modules");
+}
+
+/** Plugin manifest: ~/.pi/plugins/package.json */
+export function getPluginsPackageJson(): string {
+	return join(getPluginsDir(), "package.json");
+}
+
+/** Plugin lock file: ~/.pi/plugins/pi-plugins.lock.json */
+export function getPluginsLockfile(): string {
+	return join(getPluginsDir(), "pi-plugins.lock.json");
+}
+
+/** Project-local plugin overrides: .pi/plugin-overrides.json */
+export function getProjectPluginOverrides(cwd: string): string {
+	return join(cwd, CONFIG_DIR_NAME, "plugin-overrides.json");
+}

package/src/core/plugins/types.ts

@@ -0,0 +1,190 @@
+// =============================================================================
+// Plugin Manifest Types (from package.json omp/pi field)
+// =============================================================================
+
+/**
+ * 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 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;
+	/** 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>;
+}
+
+// =============================================================================
+// Plugin Settings Schema Types
+// =============================================================================
+
+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;
+
+// =============================================================================
+// Installed Plugin Types
+// =============================================================================
+
+/**
+ * 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;
+}
+
+// =============================================================================
+// Runtime Config Types (stored in pi-plugins.lock.json)
+// =============================================================================
+
+/**
+ * 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 pi-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 Override Types
+// =============================================================================
+
+/**
+ * Project-local plugin overrides (stored in .pi/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>>;
+}
+
+// =============================================================================
+// Doctor Types
+// =============================================================================
+
+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;
+}
+
+// =============================================================================
+// Install Options Types
+// =============================================================================
+
+export interface InstallOptions {
+	/** Overwrite existing without prompting */
+	force?: boolean;
+	/** Preview changes without applying */
+	dryRun?: boolean;
+}
+
+export interface DoctorOptions {
+	/** Attempt automatic fixes */
+	fix?: boolean;
+}