pi-mono से पोर्टिंग: एक व्यावहारिक मर्ज गाइड

यह गाइड pi-mono से इस रेपो में परिवर्तन पोर्ट करने के लिए एक दोहराने योग्य चेकलिस्ट है। इसे किसी भी मर्ज के लिए उपयोग करें: एकल फ़ाइल, फ़ीचर ब्रांच, या पूर्ण रिलीज़ सिंक।

अंतिम सिंक पॉइंट

कमिट: b21b42d032919de2f2e6920a76fa9a37c3920c0a तिथि: 2026-03-22

प्रत्येक सिंक के बाद इस अनुभाग को अपडेट करें; पिछली रेंज का पुनः उपयोग न करें।

नया सिंक शुरू करते समय, इस कमिट से आगे के पैचेस जेनरेट करें:

git format-patch b21b42d032919de2f2e6920a76fa9a37c3920c0a..HEAD --stdout > changes.patch

0) स्कोप परिभाषित करें

• अपस्ट्रीम संदर्भ (कमिट, टैग, या PR) की पहचान करें।
• उन पैकेजेस या फ़ोल्डरों को सूचीबद्ध करें जिन्हें आप बदलने की योजना बना रहे हैं।
• तय करें कि कौन सी सुविधाएँ स्कोप में हैं और कौन सी जानबूझकर छोड़ी जा रही हैं।

1) कोड को सुरक्षित रूप से लाएँ

• थोक कॉपी के बजाय एक स्वच्छ, केंद्रित diff को प्राथमिकता दें।
• बिल्ट आर्टिफैक्ट्स या जेनरेट की गई फ़ाइलों को कॉपी करने से बचें।
• यदि अपस्ट्रीम ने नई फ़ाइलें जोड़ीं, तो उन्हें स्पष्ट रूप से जोड़ें और सामग्री की समीक्षा करें।

2) इम्पोर्ट एक्सटेंशन कन्वेंशन का मिलान करें

अधिकांश रनटाइम TypeScript सोर्सेस इंटरनल इम्पोर्ट्स में .js को छोड़ देते हैं, लेकिन कुछ test/bench एंट्रीपॉइंट्स ESM रनटाइम संगतता के लिए .js रखते हैं। लोकल पैकेज की मौजूदा शैली का पालन करें; एक्सटेंशन को बड़े पैमाने पर न हटाएँ।

• packages/coding-agent रनटाइम सोर्सेस में, इंटरनल इम्पोर्ट्स को बिना एक्सटेंशन के रखें जब तक कि नॉन-TS एसेट्स इम्पोर्ट न कर रहे हों।
• packages/tui/test और packages/natives/bench में, .js वहाँ रखें जहाँ आसपास की फ़ाइलें पहले से इसका उपयोग करती हैं।
• जब टूलिंग द्वारा आवश्यक हो तो वास्तविक फ़ाइल एक्सटेंशन रखें (जैसे, .json, .css, .md टेक्स्ट एम्बेड्स)।
• उदाहरण: import { x } from "./foo.js"; → import { x } from "./foo"; (केवल जब पैकेज कन्वेंशन एक्सटेंशन-रहित हो)।

3) इम्पोर्ट स्कोप बदलें

अपस्ट्रीम अलग-अलग पैकेज स्कोप का उपयोग करता है। उन्हें लगातार बदलें।

• पुराने स्कोप को यहाँ उपयोग किए जाने वाले लोकल स्कोप से बदलें।
• उदाहरण (उन वास्तविक पैकेजेस के अनुसार समायोजित करें जिन्हें आप पोर्ट कर रहे हैं):
  • @mariozechner/pi-coding-agent → @f5-sales-demo/xcsh
  • @mariozechner/pi-agent-core → @f5-sales-demo/pi-agent-core
  • @mariozechner/pi-tui → @f5-sales-demo/pi-tui
  • @mariozechner/pi-ai → @f5-sales-demo/pi-ai

4) जहाँ Bun APIs Node से बेहतर हों, वहाँ उपयोग करें

हम Bun पर चलते हैं। Node APIs को केवल तभी बदलें जब Bun बेहतर विकल्प प्रदान करता हो।

बदलें:

• प्रोसेस स्पॉनिंग: child_process.spawn → सरल कमांड्स के लिए Bun Shell $, स्ट्रीमिंग या लंबे समय तक चलने वाले कार्य के लिए Bun.spawn/Bun.spawnSync
• फ़ाइल I/O: fs.readFileSync → Bun.file().text() / Bun.write()
• HTTP क्लाइंट्स: node-fetch, axios → नेटिव fetch
• क्रिप्टो हैशिंग: node:crypto → Web Crypto या Bun.hash
• SQLite: better-sqlite3 → bun:sqlite
• Env लोडिंग: dotenv → Bun स्वचालित रूप से .env लोड करता है

न बदलें (ये Bun में ठीक काम करते हैं):

• os.homedir() — Bun.env.HOME, Bun.env.HOME, या शाब्दिक "~" से न बदलें
• os.tmpdir() — Bun.env.TMPDIR || "/tmp" या हार्डकोडेड पाथ से न बदलें
• fs.mkdtempSync() — मैन्युअल पाथ कंस्ट्रक्शन से न बदलें
• path.join(), path.resolve(), आदि — ये ठीक हैं

इम्पोर्ट शैली: node: प्रीफ़िक्स का उपयोग केवल नेमस्पेस इम्पोर्ट्स के साथ करें (कोई नेम्ड इम्पोर्ट्स node:fs या node:path से नहीं)।

अतिरिक्त Bun कन्वेंशन:

• छोटे, नॉन-स्ट्रीमिंग कमांड्स के लिए Bun Shell $ को प्राथमिकता दें; Bun.spawn का उपयोग केवल तभी करें जब आपको स्ट्रीमिंग I/O या प्रोसेस कंट्रोल की आवश्यकता हो।
• फ़ाइलों के लिए Bun.file()/Bun.write() और डायरेक्टरीज़ के लिए node:fs/promises का उपयोग करें।
• Bun.file().exists() जाँचों से बचें; try/catch में isEnoent हैंडलिंग का उपयोग करें।
• setTimeout रैपर्स पर Bun.sleep(ms) को प्राथमिकता दें।

गलत:

// BROKEN: env vars may be undefined, "~" is not expanded
const home = Bun.env.HOME || "~";
const tmp = Bun.env.TMPDIR || "/tmp";

सही:

import * as os from "node:os";
import * as fs from "node:fs";
import * as path from "node:path";

const configDir = path.join(os.homedir(), ".config", "myapp");
const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "myapp-"));

5) Bun एम्बेड्स को प्राथमिकता दें (कॉपी नहीं)

बिल्ड समय पर रनटाइम एसेट्स या वेंडर फ़ाइलें कॉपी न करें।

• यदि अपस्ट्रीम एसेट्स को dist फ़ोल्डर में कॉपी करता है, तो Bun-अनुकूल एम्बेड्स से बदलें।
• प्रॉम्प्ट्स स्टैटिक .md फ़ाइलें हैं; इनलाइन प्रॉम्प्ट स्ट्रिंग्स के बजाय Bun टेक्स्ट इम्पोर्ट्स (with { type: "text" }) और Handlebars का उपयोग करें।
• आस-पास के नॉन-टेक्स्ट रिसोर्सेस लोड करने के लिए import.meta.dir + Bun.file का उपयोग करें।
• एसेट्स को इन-रेपो रखें और बंडलर को उन्हें शामिल करने दें।
• कॉपी स्क्रिप्ट्स को समाप्त करें जब तक कि उपयोगकर्ता स्पष्ट रूप से उनका अनुरोध न करे।
• यदि अपस्ट्रीम रनटाइम पर एक बंडल्ड फ़ॉलबैक फ़ाइल पढ़ता है, तो फ़ाइलसिस्टम रीड्स को Bun टेक्स्ट एम्बेड इम्पोर्ट से बदलें।
  • उदाहरण (Codex instructions फ़ॉलबैक):
    • const FALLBACK_PROMPT_PATH = join(import.meta.dir, "codex-instructions.md"); -> हटाया गया
    • import FALLBACK_INSTRUCTIONS from "./codex-instructions.md" with { type: "text" };
    • readFileSync(FALLBACK_PROMPT_PATH, "utf8") के बजाय return FALLBACK_INSTRUCTIONS; का उपयोग करें

6) package.json को सावधानी से पोर्ट करें

package.json को एक अनुबंध मानें। जानबूझकर मर्ज करें।

• मौजूदा name, version, type, exports, और bin को रखें जब तक कि पोर्ट में परिवर्तन की आवश्यकता न हो।
• npm/node स्क्रिप्ट्स को Bun समकक्षों से बदलें (जैसे, bun check, bun test)।
• सुनिश्चित करें कि डिपेंडेंसीज़ सही स्कोप का उपयोग करती हैं।
• टाइप एरर ठीक करने के लिए डिपेंडेंसीज़ को डाउनग्रेड न करें; इसके बजाय अपग्रेड करें।
• वर्कस्पेस पैकेज लिंक्स और peerDependencies को वेलिडेट करें।

7) कोड स्टाइल और टूलिंग का मिलान करें

• मौजूदा फ़ॉर्मेटिंग कन्वेंशन को बनाए रखें।
• जब तक आवश्यक न हो any का परिचय न दें।
• डायनामिक इम्पोर्ट्स और इनलाइन टाइप इम्पोर्ट्स से बचें; केवल टॉप-लेवल इम्पोर्ट्स का उपयोग करें।
• कोड में कभी भी प्रॉम्प्ट्स न बनाएँ; प्रॉम्प्ट्स स्टैटिक .md फ़ाइलें हैं जो Handlebars से रेंडर होती हैं।
• coding-agent में, कभी भी console.log/console.warn/console.error का उपयोग न करें; @f5-sales-demo/pi-utils से logger का उपयोग करें।
• new Promise((resolve, reject) => ...) के बजाय Promise.withResolvers() का उपयोग करें।
• क्लास फ़ील्ड्स या मेथड्स पर private/protected/public कीवर्ड्स नहीं। एनकैप्सुलेशन के लिए ES # प्राइवेट फ़ील्ड्स का उपयोग करें; एक्सेसिबल सदस्यों को बिना कीवर्ड के रखें। एकमात्र अपवाद कंस्ट्रक्टर पैरामीटर प्रॉपर्टीज़ (constructor(private readonly x: T)) है, जहाँ कीवर्ड TypeScript द्वारा आवश्यक है। जब अपस्ट्रीम कोड पोर्ट कर रहे हों जो private foo या protected bar का उपयोग करता है, तो #foo (प्राइवेट) या बेयर bar (एक्सेसिबल) में बदलें।
• नए एड-हॉक कोड पर मौजूदा हेल्पर्स और यूटिलिटीज़ को प्राथमिकता दें।
• इस रेपो में पहले से किए गए Bun-फ़र्स्ट इंफ्रास्ट्रक्चर परिवर्तनों को संरक्षित रखें:
  • रनटाइम Bun है (कोई Node एंट्री पॉइंट्स नहीं)।
  • पैकेज मैनेजर Bun है (कोई npm लॉकफ़ाइल्स नहीं)।
  • भारी Node APIs (child_process, readline) को Bun समकक्षों से बदला गया है।
  • हल्के Node APIs (os.homedir, os.tmpdir, fs.mkdtempSync, path.*) को रखा गया है।
  • CLI shebangs bun का उपयोग करते हैं (node नहीं, tsx नहीं)।
  • पैकेजेस सीधे सोर्स फ़ाइलों का उपयोग करते हैं (कोई TypeScript बिल्ड स्टेप नहीं)।
  • CI वर्कफ़्लो install/check/test के लिए Bun चलाते हैं।

8) पुरानी संगतता परतें हटाएँ

जब तक अनुरोध न किया जाए, अपस्ट्रीम संगतता शिम्स हटाएँ।

• पुराने APIs को हटाएँ जो बदले गए थे।
• सभी कॉल साइट्स को सीधे नई API पर अपडेट करें।
• *_v2 या समानांतर संस्करण न रखें।

9) डॉक्स और संदर्भ अपडेट करें

• जहाँ उचित हो pi-mono रेपो लिंक्स को बदलें।
• उदाहरणों को Bun और सही पैकेज स्कोप का उपयोग करने के लिए अपडेट करें।
• सुनिश्चित करें कि README निर्देश अभी भी वर्तमान रेपो व्यवहार से मेल खाते हैं।

10) पोर्ट को वेलिडेट करें

परिवर्तनों के बाद मानक जाँचें चलाएँ:

• bun check

यदि रेपो में पहले से ऐसी जाँचें विफल हो रही हैं जो आपके परिवर्तनों से संबंधित नहीं हैं, तो इसे स्पष्ट करें। टेस्ट Bun के रनर (Vitest नहीं) का उपयोग करते हैं, लेकिन bun test केवल तभी चलाएँ जब स्पष्ट रूप से अनुरोध किया गया हो।

11) सुधारी गई सुविधाओं की सुरक्षा करें (रिग्रेशन ट्रैप सूची)

यदि आपने पहले से स्थानीय रूप से व्यवहार में सुधार किया है, तो उन्हें अपरिवर्तनीय मानें। पोर्ट करने से पहले, सुधारों को लिखें और स्पष्ट जाँचें जोड़ें ताकि वे मर्ज में खो न जाएँ।

• अपेक्षित व्यवहार को फ़्रीज़ करें: प्रत्येक सुधार के लिए एक संक्षिप्त “पहले/बाद” नोट जोड़ें (इनपुट, आउटपुट, डिफ़ॉल्ट, एज केसेस)। यह मूक रोलबैक को रोकता है।
• पुराने → नए APIs का मैपिंग करें: यदि अपस्ट्रीम ने अवधारणाओं का नाम बदला (hooks → extensions, custom tools → tools, आदि), सुनिश्चित करें कि हर पुराना एंट्री पॉइंट अभी भी वायर है। एक छूटा हुआ फ़्लैग या एक्सपोर्ट = खोई हुई कार्यक्षमता।
• एक्सपोर्ट्स सत्यापित करें: package.json exports, पब्लिक टाइप्स, और बैरल फ़ाइलों की जाँच करें। अपस्ट्रीम पोर्ट्स अक्सर लोकल एडिशन्स को री-एक्सपोर्ट करना भूल जाते हैं।
• नॉन-हैप्पी पाथ कवर करें: यदि आपने एरर हैंडलिंग, टाइमआउट्स, या फ़ॉलबैक लॉजिक ठीक किया है, तो एक टेस्ट या कम से कम एक मैन्युअल चेकलिस्ट जोड़ें जो उन पाथ्स को एक्सरसाइज़ करे।
• डिफ़ॉल्ट्स और कॉन्फ़िग मर्ज ऑर्डर जाँचें: सुधार अक्सर डिफ़ॉल्ट्स में रहते हैं। पुष्टि करें कि नए डिफ़ॉल्ट्स रिवर्ट नहीं हुए (जैसे, नई कॉन्फ़िग प्राथमिकता, अक्षम सुविधाएँ, टूल सूचियाँ)।
• env/shell व्यवहार का ऑडिट करें: यदि आपने एक्ज़ीक्यूशन या सैंडबॉक्सिंग ठीक की है, तो सत्यापित करें कि नया पाथ अभी भी आपके सैनिटाइज़्ड env का उपयोग करता है और alias/function ओवरराइड्स को फिर से पेश नहीं करता।
• लक्षित सैंपल्स फिर से चलाएँ: “ज्ञात अच्छे” उदाहरणों का एक न्यूनतम सेट रखें और पोर्ट के बाद उन्हें चलाएँ (CLI फ़्लैग्स, एक्सटेंशन रजिस्ट्रेशन, टूल एक्ज़ीक्यूशन)।

12) रीवर्क किए गए कोड का पता लगाएँ और उसे संभालें

किसी फ़ाइल को पोर्ट करने से पहले, जाँचें कि क्या अपस्ट्रीम ने इसे महत्वपूर्ण रूप से रीफ़ैक्टर किया है:

# Compare the file you're about to port against what you have locally
git diff HEAD upstream/main -- path/to/file.ts

यदि diff दिखाता है कि फ़ाइल रीवर्क की गई थी (केवल पैच नहीं):

• नई एब्स्ट्रैक्शन्स, नाम बदली गई अवधारणाएँ, मर्ज किए गए मॉड्यूल, बदला हुआ डेटा फ़्लो

तो आपको पोर्ट करने से पहले नई इम्प्लीमेंटेशन को अच्छी तरह पढ़ना होगा। रीवर्क किए गए कोड का अंधा मर्जिंग कार्यक्षमता खो देता है क्योंकि:

नोट: इंटरैक्टिव मोड को हाल ही में controllers/utils/types में विभाजित किया गया था। संबंधित परिवर्तनों को बैकपोर्ट करते समय, अपडेट्स को उन व्यक्तिगत फ़ाइलों में पोर्ट करें जो हमने बनाई हैं और सुनिश्चित करें कि interactive-mode.ts वायरिंग सिंक में रहे।

1. डिफ़ॉल्ट्स चुपचाप बदल जाते हैं - एक नया वेरिएबल defaultFoo = [a, b] पुराने getAllFoo() को बदल सकता है जो [a, b, c, d, e] लौटाता था।

2. API विकल्प छूट जाते हैं - जब सिस्टम मर्ज होते हैं (जैसे, hooks + customTools → extensions), पुराने विकल्प नई इम्प्लीमेंटेशन में वायर नहीं हो सकते।

3. कोड पाथ्स स्टेल हो जाते हैं - एक नाम बदली गई अवधारणा (जैसे, hookMessage → custom) को हर switch स्टेटमेंट, टाइप गार्ड, और हैंडलर में अपडेट की आवश्यकता होती है—केवल परिभाषा में नहीं।

4. कॉन्टेक्स्ट/कैपेबिलिटीज़ सिकुड़ती हैं - पुरानी APIs ने { logger, typebox, pi } एक्सपोज़ किया हो सकता है जिसे नई APIs ने शामिल करना भूल दिया।

सिमेंटिक पोर्टिंग प्रक्रिया

जब अपस्ट्रीम ने एक मॉड्यूल रीवर्क किया हो:

1. पुरानी इम्प्लीमेंटेशन पढ़ें - समझें कि यह क्या करती थी, कौन से विकल्प स्वीकार करती थी, क्या एक्सपोज़ करती थी।

2. नई इम्प्लीमेंटेशन पढ़ें - नई एब्स्ट्रैक्शन्स और वे पुराने व्यवहार से कैसे मैप होती हैं, समझें।

3. फ़ीचर पैरिटी सत्यापित करें - पुराने कोड की प्रत्येक क्षमता के लिए, पुष्टि करें कि नया कोड इसे संरक्षित करता है या स्पष्ट रूप से हटाता है।

4. बचे हुओं के लिए grep करें - पुराने नामों/अवधारणाओं को खोजें जो switch स्टेटमेंट्स, हैंडलर्स, UI कंपोनेंट्स में छूट गए हो सकते हैं।

5. सीमाओं का परीक्षण करें - CLI फ़्लैग्स, SDK विकल्प, इवेंट हैंडलर्स, डिफ़ॉल्ट वैल्यूज़—ये वहाँ हैं जहाँ रिग्रेशन छिपते हैं।

त्वरित जाँचें

# Find all uses of an old concept that may need updating
rg "oldConceptName" --type ts

# Compare default values between versions
git show upstream/main:path/to/file.ts | rg "default|DEFAULT"

# Check if all enum/union values have handlers
rg "case \"" path/to/file.ts

13) त्वरित ऑडिट चेकलिस्ट

समाप्त करने से पहले इसे अंतिम पास के रूप में उपयोग करें:

• इम्पोर्ट एक्सटेंशन लोकल पैकेज कन्वेंशन का पालन करते हैं (बड़े पैमाने पर .js स्ट्रिपिंग नहीं)
• नए/पोर्ट किए गए कोड में कोई Node-ओनली APIs नहीं
• सभी पैकेज स्कोप अपडेट किए गए
• package.json स्क्रिप्ट्स Bun का उपयोग करती हैं
• प्रॉम्प्ट्स .md टेक्स्ट इम्पोर्ट्स हैं (कोई इनलाइन प्रॉम्प्ट स्ट्रिंग्स नहीं)
• coding-agent में कोई console.* नहीं (logger का उपयोग करें)
• एसेट्स Bun एम्बेड पैटर्न से लोड होती हैं (कोई कॉपी स्क्रिप्ट्स नहीं)
• टेस्ट या जाँचें चलती हैं (या स्पष्ट रूप से ब्लॉक्ड के रूप में नोट किया गया)
• कोई कार्यक्षमता रिग्रेशन नहीं (अनुभाग 11-12 देखें)

14) कमिट मैसेज फ़ॉर्मेट

बैकपोर्ट कमिट करते समय, रेपो फ़ॉर्मेट <type>(scope): <past-tense description> का पालन करें और कमिट रेंज को शीर्षक में रखें।

fix(coding-agent): backported pi-mono changes (<from>..<to>)

packages/<package>:
- <type>: <description>
- <type>: <description> (#<issue> by @<contributor>)

packages/<other-package>:
- <type>: <description>

उदाहरण:

fix(coding-agent): backported pi-mono changes (9f3eef65f..52532c7c0)

packages/ai:
- fix: handle "sensitive" stop reason from Anthropic API
- fix: normalize tool call IDs with special characters for Responses API
- fix: add overflow detection for Bedrock, MiniMax, Kimi providers
- fix: 429 status is rate limiting, not context overflow

packages/tui:
- fix: refactored autocomplete state tracking
- fix: file autocomplete should not trigger on empty text
- fix: configurable autocomplete max visible items
- fix: improved table column width calculation with word-aware wrapping

packages/coding-agent:
- fix: preserve external config.yml edits on save (#1046 by @nicobailonMD)
- fix: resolve macOS NFD and curly quote variants in file paths

नियम:

• परिवर्तनों को पैकेज के अनुसार समूहित करें
• कन्वेंशनल कमिट टाइप्स का उपयोग करें (fix, feat, refactor, perf, docs)
• बाहरी योगदानों के लिए अपस्ट्रीम issue/PR नंबर और कंट्रीब्यूटर एट्रिब्यूशन शामिल करें
• शीर्षक में कमिट रेंज सिंक पॉइंट्स को ट्रैक करने में मदद करती है

15) जानबूझकर किए गए विचलन

हमारे फ़ोर्क में वास्तुशिल्प निर्णय हैं जो अपस्ट्रीम से भिन्न हैं। इन अपस्ट्रीम पैटर्न को पोर्ट न करें:

UI आर्किटेक्चर

अपस्ट्रीम	हमारा फ़ोर्क	कारण
FooterDataProvider क्लास	StatusLineComponent	सरल, एकीकृत स्टेटस लाइन
ctx.ui.setHeader() / ctx.ui.setFooter()	नॉन-TUI मोड्स में स्टब	TUI में लागू, अन्यथा no-op
ctx.ui.setEditorComponent()	नॉन-TUI मोड्स में स्टब	TUI में लागू, अन्यथा no-op
InteractiveModeOptions ऑप्शन्स ऑब्जेक्ट	पोज़िशनल कंस्ट्रक्टर args (ऑप्शन्स टाइप अभी भी एक्सपोर्टेड)	कंस्ट्रक्टर सिग्नेचर रखें; जब अपस्ट्रीम फ़ील्ड्स जोड़े तो टाइप अपडेट करें

कंपोनेंट नेमिंग

अपस्ट्रीम	हमारा फ़ोर्क
extension-input.ts	hook-input.ts
extension-selector.ts	hook-selector.ts
ExtensionInputComponent	HookInputComponent
ExtensionSelectorComponent	HookSelectorComponent

API नेमिंग

अपस्ट्रीम	हमारा फ़ोर्क	नोट्स
sessionManager.appendSessionInfo(name)	sessionManager.setSessionName(name)	हम पूरे कोड में sessionName का उपयोग करते हैं
sessionManager.getSessionName()	sessionManager.getSessionName()	समान (हमने अपस्ट्रीम के RPC से मिलान के लिए एकीकृत किया)
agent.sessionName / setSessionName()	agent.sessionName / setSessionName()	समान

फ़ाइल कंसोलिडेशन

अपस्ट्रीम	हमारा फ़ोर्क	कारण
clipboard.ts + clipboard-image.ts (टूल फ़ाइलें)	@f5-sales-demo/pi-natives क्लिपबोर्ड मॉड्यूल	N-API नेटिव इम्प्लीमेंटेशन में मर्ज किया गया

टेस्ट फ़्रेमवर्क

अपस्ट्रीम	हमारा फ़ोर्क
vitest with vi.mock()	bun:test with vi from bun
node:test assertions	expect() matchers

टूल आर्किटेक्चर

अपस्ट्रीम	हमारा फ़ोर्क	नोट्स
createTool(cwd: string, options?)	createTools(session: ToolSession) via BUILTIN_TOOLS रजिस्ट्री	टूल फ़ैक्ट्रीज़ ToolSession स्वीकार करती हैं और null लौटा सकती हैं
प्रति-टूल *Operations इंटरफ़ेसेज़	प्रति-टूल इंटरफ़ेसेज़ बने रहते हैं (FindOperations, GrepOperations)	SSH/रिमोट ओवरराइड्स के लिए उपयोग किया जाता है
हर जगह Node.js fs/promises	फ़ाइलों के लिए Bun.file()/Bun.write(); dirs के लिए node:fs/promises	जब Bun APIs सरल बनाएँ तो उन्हें प्राथमिकता दें

Auth स्टोरेज

अपस्ट्रीम	हमारा फ़ोर्क	नोट्स
proper-lockfile + auth.json	agent.db (bun:sqlite)	क्रेडेंशियल्स विशेष रूप से agent.db में संग्रहीत
प्रति प्रोवाइडर एकल क्रेडेंशियल	राउंड-रॉबिन चयन के साथ मल्टी-क्रेडेंशियल	सेशन एफ़िनिटी और बैकऑफ़ लॉजिक संरक्षित

एक्सटेंशन्स

अपस्ट्रीम	हमारा फ़ोर्क
TypeScript लोडिंग के लिए jiti	नेटिव Bun import()
pkg.pi मैनिफ़ेस्ट फ़ील्ड	pkg.xcsh ?? pkg.pi (हमारे नेमस्पेस को प्राथमिकता)

इन अपस्ट्रीम सुविधाओं को छोड़ें

पोर्ट करते समय, इन फ़ाइलों/सुविधाओं को पूरी तरह छोड़ें:

• footer-data-provider.ts — हम StatusLineComponent का उपयोग करते हैं
• clipboard-image.ts — क्लिपबोर्ड @f5-sales-demo/pi-natives N-API मॉड्यूल में है
• GitHub वर्कफ़्लो फ़ाइलें — हमारी अपनी CI है
• models.generated.ts — ऑटो-जेनरेटेड, स्थानीय रूप से रीजेनरेट करें (models.json के रूप में)

हमने जोड़ी गई सुविधाएँ (इन्हें संरक्षित रखें)

ये हमारे फ़ोर्क में मौजूद हैं लेकिन अपस्ट्रीम में नहीं। कभी ओवरराइट न करें:

• इंटरैक्टिव मोड में StatusLineComponent
• सेशन एफ़िनिटी के साथ मल्टी-क्रेडेंशियल auth
• कैपेबिलिटी-बेस्ड डिस्कवरी सिस्टम (defineCapability, registerProvider, loadCapability, skillCapability, आदि)
• MCP/Exa/SSH इंटीग्रेशन्स
• फ़ॉर्मेट-ऑन-सेव के लिए LSP राइट-थ्रू
• Bash इंटरसेप्शन (checkBashInterception)
• रीड टूल में फ़ज़ी पाथ सजेशन्स