प्लगइन मैनेजर और इंस्टॉलर प्लंबिंग

यह दस्तावेज़ बताता है कि xcsh plugin ऑपरेशन डिस्क पर प्लगइन स्थिति को किस प्रकार बदलते हैं और इंस्टॉल किए गए प्लगइन किस प्रकार रनटाइम क्षमताएं बनते हैं (आज उपकरण, हुक/कमांड पाथ रिज़ॉल्यूशन उपलब्ध)।

स्कोप और आर्किटेक्चर

कोडबेस में प्लगइन-प्रबंधन के दो कार्यान्वयन हैं:

1. CLI कमांड द्वारा उपयोग किया जाने वाला सक्रिय पाथ: PluginManager (src/extensibility/plugins/manager.ts)
2. लेगेसी हेल्पर मॉड्यूल: इंस्टॉलर फ़ंक्शन (src/extensibility/plugins/installer.ts)

xcsh plugin ... कमांड का निष्पादन PluginManager से होकर जाता है।

installer.ts अभी भी महत्वपूर्ण सुरक्षा जाँच और फ़ाइलसिस्टम व्यवहार को दस्तावेज़ीकृत करता है, लेकिन यह src/commands/plugin.ts + src/cli/plugin-cli.ts द्वारा उपयोग किया जाने वाला पाथ नहीं है।

लाइफसाइकल: CLI इनवोकेशन से रनटाइम उपलब्धता तक

xcsh plugin <action> ...
  -> src/commands/plugin.ts
  -> runPluginCommand(...) in src/cli/plugin-cli.ts
  -> PluginManager method (install/list/uninstall/link/...)
  -> mutate ~/.xcsh/plugins/{package.json,node_modules,xcsh-plugins.lock.json}
  -> runtime discovery: discoverAndLoadCustomTools(...)
  -> getAllPluginToolPaths(cwd)
  -> custom tool loader imports tool modules

कमांड एंट्रीपॉइंट

• src/commands/plugin.ts कमांड/फ़्लैग परिभाषित करता है और runPluginCommand को अग्रेषित करता है।
• src/cli/plugin-cli.ts सबकमांड को PluginManager मेथड से मैप करता है:
  • install, uninstall, list, link, doctor, features, config, enable, disable
• कोई स्पष्ट update एक्शन मौजूद नहीं है; अपडेट नए पैकेज/वर्जन स्पेक के साथ install पुनः चलाकर किया जाता है।

ऑन-डिस्क मॉडल

ग्लोबल प्लगइन स्थिति ~/.xcsh/plugins के अंतर्गत रहती है:

• package.json — bun install/bun uninstall द्वारा उपयोग किया जाने वाला डिपेंडेंसी मैनिफेस्ट
• node_modules/ — इंस्टॉल किए गए प्लगइन पैकेज या सिमलिंक
• xcsh-plugins.lock.json — रनटाइम स्थिति:
  • प्रति प्लगइन सक्षम/अक्षम
  • प्रति प्लगइन चयनित फीचर सेट
  • स्थायी प्लगइन सेटिंग्स

प्रोजेक्ट-लोकल ओवरराइड यहाँ रहते हैं:

• <cwd>/.xcsh/plugin-overrides.json

ओवरराइड मैनेजर/लोडर दृष्टिकोण से केवल पढ़ने योग्य हैं (यहाँ कोई राइट पाथ नहीं है) और इस प्रोजेक्ट के लिए प्लगइन को अक्षम कर सकते हैं या फीचर/सेटिंग्स को ओवरराइड कर सकते हैं।

प्लगइन स्पेक पार्सिंग और मेटाडेटा इंटरप्रिटेशन

इंस्टॉल स्पेक ग्रामर

parsePluginSpec (parser.ts) इनका समर्थन करता है:

• pkg -> features: null (डिफॉल्ट व्यवहार)
• pkg[*] -> सभी मैनिफेस्ट फीचर सक्षम करें
• pkg[] -> कोई वैकल्पिक फीचर सक्षम न करें
• pkg[a,b] -> नामित फीचर सक्षम करें
• @scope/pkg@1.2.3[feat] -> स्पष्ट फीचर चयन के साथ स्कोप्ड + वर्जन्ड पैकेज

extractPackageName इंस्टॉल के बाद ऑन-डिस्क पाथ लुकअप के लिए वर्जन सफिक्स हटाता है।

मैनिफेस्ट स्रोत और आवश्यक फील्ड

मैनिफेस्ट इस प्रकार रिज़ॉल्व होता है:

1. package.json.xcsh
2. फॉलबैक package.json.pi
3. फॉलबैक { version: package.version }

निहितार्थ:

• मैनेजर/लोडर में कोई सख्त स्कीमा वैलिडेशन नहीं है।
• xcsh/pi से रहित पैकेज अभी भी इंस्टॉल करने योग्य और सूचीबद्ध करने योग्य है।
• रनटाइम प्लगइन लोडिंग (getEnabledPlugins) xcsh/pi मैनिफेस्ट के बिना पैकेज को छोड़ देती है।
• manifest.version हमेशा पैकेज version से ओवरराइट होता है।

पढ़ने के समय खराब package.json JSON एक हार्ड फेलियर है; खराब मैनिफेस्ट शेप बाद में तभी फेल हो सकता है जब विशिष्ट फील्ड उपयोग किए जाएं।

इंस्टॉल/अपडेट फ्लो (PluginManager.install)

1. इंस्टॉल स्पेक से फीचर ब्रैकेट सिंटैक्स पार्स करें।
2. रेगेक्स + शेल-मेटाकैरेक्टर डेनीलिस्ट के विरुद्ध पैकेज नाम वैलिडेट करें।
3. सुनिश्चित करें कि प्लगइन package.json मौजूद है (xcsh-plugins, प्राइवेट डिपेंडेंसी मैप)।
4. ~/.xcsh/plugins में bun install <packageSpec> चलाएं।
5. इंस्टॉल किया गया पैकेज node_modules/<name>/package.json पढ़ें।
6. मैनिफेस्ट रिज़ॉल्व करें और enabledFeatures कंप्यूट करें:
   • [*]: सभी घोषित फीचर (या null यदि कोई फीचर मैप नहीं है)
   • [a,b]: मैनिफेस्ट फीचर मैप में प्रत्येक फीचर की जाँच करता है
   • []: खाली फीचर सूची
   • बेयर स्पेक: null (बाद में लोडर में डिफॉल्ट पॉलिसी उपयोग करें)
7. लॉकफाइल रनटाइम स्थिति अपसर्ट करें: { version, enabledFeatures, enabled: true }।

अपडेट सेमेंटिक्स

क्योंकि अपडेट इंस्टॉल-संचालित है:

• xcsh plugin install pkg@newVersion डिपेंडेंसी और लॉकफाइल वर्जन अपडेट करता है।
• मौजूदा सेटिंग्स संरक्षित रहती हैं; स्टेट एंट्री version/features/enabled के लिए ओवरराइट होती है।
• कोई अलग “अपडेट जाँचें” या ट्रांजेक्शनल माइग्रेशन लॉजिक मौजूद नहीं है।

रिमूव फ्लो (PluginManager.uninstall)

1. पैकेज नाम वैलिडेट करें।
2. प्लगइन डायरेक्टरी में bun uninstall <name> चलाएं।
3. लॉकफाइल से प्लगइन रनटाइम स्थिति हटाएं:
   • config.plugins[name]
   • config.settings[name]

यदि अनइंस्टॉल कमांड विफल होती है, तो रनटाइम स्थिति नहीं बदलती।

लिस्ट फ्लो (PluginManager.list)

1. ~/.xcsh/plugins/package.json से प्लगइन डिपेंडेंसी मैप पढ़ें।
2. लॉकफाइल रनटाइम कॉन्फिग लोड करें (फाइल नहीं मिली -> खाली डिफॉल्ट)।
3. प्रोजेक्ट ओवरराइड लोड करें (<cwd>/.xcsh/plugin-overrides.json, पार्स/पढ़ने की त्रुटियां -> चेतावनी के साथ खाली ऑब्जेक्ट)।
4. रिज़ॉल्व करने योग्य package.json वाली प्रत्येक डिपेंडेंसी के लिए:
   • InstalledPlugin रिकॉर्ड बनाएं
   • फीचर/इनेबल स्थिति मर्ज करें:
     • लॉकफाइल से बेस (या डिफॉल्ट)
     • प्रोजेक्ट ओवरराइड फीचर चयन को बदल सकते हैं
     • प्रोजेक्ट disabled सूची प्लगइन को अक्षम के रूप में मास्क करती है

यह CLI स्टेटस आउटपुट और settings/features ऑपरेशन द्वारा उपयोग की जाने वाली प्रभावी स्थिति है।

लिंक फ्लो (PluginManager.link)

link लोकल पैकेज को ~/.xcsh/plugins/node_modules/<pkg.name> में सिमलिंक करके लोकल प्लगइन डेवलपमेंट का समर्थन करता है।

व्यवहार:

1. मैनेजर cwd के विरुद्ध localPath रिज़ॉल्व करें।
2. लोकल package.json और name फील्ड की आवश्यकता है।
3. प्लगइन डायरेक्टरी सुनिश्चित करें।
4. स्कोप्ड नामों के लिए, स्कोप डायरेक्टरी बनाएं।
5. टार्गेट लिंक लोकेशन पर मौजूदा पाथ हटाएं।
6. सिमलिंक बनाएं।
7. डिफॉल्ट फीचर (null) के साथ सक्षम रनटाइम लॉकफाइल एंट्री जोड़ें।

चेतावनी: वर्तमान PluginManager.link लेगेसी installer.ts (normalizedPath.startsWith(normalizedCwd)) में मौजूद cwd पाथ-बाउंड्री जाँच को लागू नहीं करता, इसलिए विश्वास कॉलर की जिम्मेदारी है।

रनटाइम लोडिंग: इंस्टॉल किए गए प्लगइन से कॉल करने योग्य क्षमताओं तक

डिस्कवरी गेट

getEnabledPlugins(cwd) (plugins/loader.ts) पढ़ता है:

• प्लगइन डिपेंडेंसी मैनिफेस्ट (package.json)
• लॉकफाइल रनटाइम स्थिति
• getConfigDirPaths("plugin-overrides.json", { user: false, cwd }) के माध्यम से प्रोजेक्ट ओवरराइड

फ़िल्टरिंग:

• यदि कोई प्लगइन package.json नहीं है तो छोड़ें
• यदि मैनिफेस्ट (xcsh/pi) अनुपस्थित है तो छोड़ें
• यदि लॉकफाइल में ग्लोबली अक्षम है तो छोड़ें
• यदि प्रोजेक्ट-अक्षम है तो छोड़ें

क्षमता पाथ रिज़ॉल्यूशन

प्रत्येक सक्षम प्लगइन के लिए:

• resolvePluginToolPaths(plugin)
• resolvePluginHookPaths(plugin)
• resolvePluginCommandPaths(plugin)

प्रत्येक रिज़ॉल्वर में बेस एंट्री के साथ फीचर एंट्री शामिल हैं:

• स्पष्ट फीचर सूची -> केवल चयनित फीचर
• enabledFeatures === null -> default: true चिह्नित फीचर सक्षम करें

गुम फाइलें चुपचाप छोड़ दी जाती हैं (existsSync गार्ड)।

वर्तमान रनटाइम वायरिंग अंतर

• उपकरण आज रनटाइम में वायर्ड हैं discoverAndLoadCustomTools (custom-tools/loader.ts) के माध्यम से, जो getAllPluginToolPaths(cwd) कॉल करता है।
• पाथ को कस्टम टूल डिस्कवरी में रिज़ॉल्व किए गए एब्सोल्यूट पाथ द्वारा डी-डुप्लिकेट किया जाता है (seen सेट, पहला पाथ जीतता है)।
• हुक/कमांड रिज़ॉल्वर मौजूद हैं और एक्सपोर्ट किए गए हैं, लेकिन यह कोड पाथ वर्तमान में उन्हें उसी तरह रनटाइम रजिस्ट्री में वायर नहीं करता जैसे उपकरण वायर किए जाते हैं।

लॉक/स्टेट प्रबंधन विवरण

PluginManager प्रति इंस्टेंस मेमोरी में रनटाइम कॉन्फिग कैश करता है (#runtimeConfig) और एक बार लेजिली लोड करता है।

लोड व्यवहार:

• लॉकफाइल नहीं मिली -> { plugins: {}, settings: {} }
• लॉकफाइल पढ़ने/पार्स करने की विफलता -> चेतावनी + समान खाली डिफॉल्ट

सेव व्यवहार:

• प्रत्येक म्यूटेशन पर पूरी लॉकफाइल JSON प्रिटी-प्रिंटेड लिखता है

कोई क्रॉस-प्रोसेस लॉकिंग या मर्ज रणनीति मौजूद नहीं है; समवर्ती राइटर एक-दूसरे को ओवरराइट कर सकते हैं।

सुरक्षा जाँच और विश्वास सीमाएं

इनपुट/पैकेज वैलिडेशन

सक्रिय मैनेजर पाथ पैकेज-नाम वैलिडेशन लागू करता है:

• स्कोप्ड/अनस्कोप्ड पैकेज स्पेक के लिए रेगेक्स (वैकल्पिक रूप से वर्जन के साथ)
• स्पष्ट शेल मेटाकैरेक्टर डेनीलिस्ट ([;&|$(){}[]<>\]`)

यह bun install/uninstall इनवोक करते समय कमांड-इंजेक्शन जोखिम को सीमित करता है।

फ़ाइलसिस्टम विश्वास सीमा

• कस्टम टूल मॉड्यूल इंपोर्ट होने पर प्लगइन कोड इन-प्रोसेस निष्पादित होता है; कोई सैंडबॉक्सिंग नहीं।
• मैनिफेस्ट रिलेटिव पाथ प्लगइन पैकेज डायरेक्टरी के विरुद्ध जॉइन किए जाते हैं और केवल अस्तित्व-जाँच किए जाते हैं।
• प्लगइन पैकेज स्वयं इंस्टॉल होने के बाद विश्वसनीय कोड है।

लेगेसी इंस्टॉलर-केवल जाँच

installer.ts में अतिरिक्त लिंक-टाइम जाँच हैं जो PluginManager.link में नहीं हैं:

• लोकल पाथ प्रोजेक्ट cwd के अंदर रिज़ॉल्व होना चाहिए
• सिमलिंक टार्गेट नामकरण के लिए अतिरिक्त पैकेज नाम/पाथ ट्रैवर्सल गार्ड

क्योंकि CLI PluginManager उपयोग करता है, ये सख्त लिंक गार्ड वर्तमान में मुख्य पाथ पर नहीं हैं।

विफलता, आंशिक सफलता, और रोलबैक व्यवहार

प्लगइन मैनेजर ट्रांजेक्शनल नहीं है।

ऑपरेशन चरण	विफलता व्यवहार	रोलबैक
bun install विफल	stderr के साथ इंस्टॉल रद्द	N/A (अभी तक कोई स्टेट राइट नहीं)
इंस्टॉल सफल, फिर मैनिफेस्ट/फीचर वैलिडेशन विफल	कमांड विफल	कोई अनइंस्टॉल रोलबैक नहीं; डिपेंडेंसी node_modules/package.json में बनी रह सकती है
इंस्टॉल सफल, फिर लॉकफाइल राइट विफल	कमांड विफल	इंस्टॉल किए गए पैकेज का कोई रोलबैक नहीं
bun uninstall सफल, लॉकफाइल राइट विफल	कमांड विफल	पैकेज हटाया गया, स्टेल रनटाइम स्थिति बनी रह सकती है
link पुराना टार्गेट हटाता है फिर सिमलिंक निर्माण विफल	कमांड विफल	पिछले लिंक/डायरेक्टरी की कोई रिस्टोरेशन नहीं

संचालन में, doctor --fix कुछ ड्रिफ्ट की मरम्मत कर सकता है (bun install, अनाथ कॉन्फिग क्लीनअप, अमान्य-फीचर क्लीनअप), लेकिन यह बेस्ट-एफर्ट है।

खराब/अनुपस्थित मैनिफेस्ट व्यवहार सारांश

• अनुपस्थित xcsh/pi फील्ड:
  • इंस्टॉल/लिस्ट: सहन किया जाता है (न्यूनतम मैनिफेस्ट)
  • रनटाइम enabled-plugin डिस्कवरी: नॉन-प्लगइन के रूप में छोड़ा जाता है
• इंस्टॉल स्पेक या features --set/--enable द्वारा संदर्भित अनुपस्थित फीचर: उपलब्ध फीचर सूची के साथ हार्ड एरर
• अमान्य plugin-overrides.json: मैनेजर और लोडर दोनों पाथ में {} के फॉलबैक के साथ अनदेखा किया जाता है
• मैनिफेस्ट द्वारा संदर्भित अनुपस्थित टूल/हुक/कमांड फाइल पाथ: रिज़ॉल्वर विस्तार के दौरान चुपचाप अनदेखा; केवल doctor द्वारा त्रुटि के रूप में चिह्नित

मोड अंतर और प्राथमिकता

• --dry-run (install): सिंथेटिक इंस्टॉल परिणाम लौटाता है, कोई फ़ाइलसिस्टम/नेटवर्क/स्टेट राइट नहीं।
• --json: केवल आउटपुट फॉर्मेटिंग, कोई व्यवहार परिवर्तन नहीं।
• प्रोजेक्ट ओवरराइड हमेशा फीचर/सेटिंग्स दृश्य के लिए ग्लोबल लॉकफाइल पर प्राथमिकता लेते हैं।
• प्रभावी सक्षमता runtimeEnabled && !projectDisabled है।

कार्यान्वयन फाइलें

• src/commands/plugin.ts — CLI कमांड घोषणा और फ्लैग मैपिंग
• src/cli/plugin-cli.ts — एक्शन डिस्पैच, उपयोगकर्ता-सामना कमांड हैंडलर
• src/extensibility/plugins/manager.ts — सक्रिय install/remove/list/link/state/doctor कार्यान्वयन
• src/extensibility/plugins/installer.ts — लेगेसी इंस्टॉलर हेल्पर और अतिरिक्त लिंक सुरक्षा जाँच
• src/extensibility/plugins/loader.ts — enabled-plugin डिस्कवरी और टूल/हुक/कमांड पाथ रिज़ॉल्यूशन
• src/extensibility/plugins/parser.ts — इंस्टॉल स्पेक और पैकेज-नाम पार्सिंग हेल्पर
• src/extensibility/plugins/types.ts — मैनिफेस्ट/रनटाइम/ओवरराइड टाइप कॉन्ट्रैक्ट
• src/extensibility/custom-tools/loader.ts — प्लगइन-प्रदत्त टूल मॉड्यूल के लिए रनटाइम वायरिंग