הצעת ייעול | יוצרים תוספים? שימו לב

[יאיר דניאל]

בעקבות בדיקה מעמיקה שנעשתה על כלל התוספים בתוכנה שנעשו ע"י חברינו היקרים - מ@האדם-החושב דרך @ פלמנמוני עובר דרך עבדכם הנאמן ועד @ מעמע ו@ סנאי.

ישנם כמה באגים קטנים - לא ברמה קריטית, אבל עדיין באגים בקוד - שנמצאו ברוב ככל התוספים.

נבקשכם להבא - לשים לב לדברים הבאים:

הנחיות למפתחי תוספים לאוצריא

קודם כל - תודה רבה על התרומה לקהילת אוצריא!
כל תוסף שאתם כותבים מעשיר ומוסיף ללימוד של אלפי משתמשים!
ההנחיות האלו נכתבו בעקבות ביקורת קוד שנערכה על כלל התוספים, ומטרתו לעזור לכם לכתוב קוד נקי, בטוח ותואם.

---

1. שדות חובה ב-manifest.json

כל תוסף חייב לכלול את השדות הבאים:

{
  "id": "com.yourname.pluginname",
  "name": "שם התוסף",
  "version": "1.0.0",
  "description": "תיאור קצר של התוסף",
  "author": "שמכם",
  "type": "webapp",
  "category": "Utilities",
  "stability": "beta",
  "minAppVersion": "0.9.91",
  "entrypoint": "index.html"
}

שדות חסרים שנמצאו בביקורת: type, category, stability, minAppVersion, description, author.

---

2. הרשאות תקינות בלבד

השתמשו רק בהרשאות שקיימות ב-API של אוצריא. ההרשאות הבאות אינן קיימות ויש להסירן:

• שימו לב - אם ישנה הרשאה שאתם צריכים לצורך התוסף - והיא אינה נמצאת ברשימה - פנו ל@י.-פל. ובקשו ממנו להוסיף הרשאה זו.

הרשאה לא תקינה	הסבר
reader.context_menu	לא קיים
app.info.read	לא קיים
calendar.read	לא קיים
navigation.write	לא קיים
reader.highlight	לא קיים
events.subscribe:calendar.date_changed	לא קיים
events.subscribe:reader.selection_changed	לא קיים
settings.read	לא קיים

הרשאות תקינות לדוגמה:

• plugin.storage.read / plugin.storage.write
• reader.open
• library.books.read / library.content.read
• ui.feedback
• network.access
• notifications.send / notifications.system
• events.subscribe:theme.changed

כלל: אל תוסיפו הרשאה אלא אם הקוד שלכם אכן קורא ל-API המתאים.

---

(3. באג טיימזון — toISOString() לתאריך מקומי

הבעיה

//שגוי — מחזיר תאריך UTC, לא תאריך מקומי!
const today = new Date().toISOString().slice(0, 10);
// בישראל אחרי חצות UTC (= אחרי 2:00 / 3:00 בלילה)
// הפונקציה תחזיר את התאריך של יום המחרת!

הפתרון

הוסיפו את הפונקציה הבאה בתחילת הקוד:

function localDateStr(d) {
  d = d || new Date();
  return d.getFullYear() + '-' +
    String(d.getMonth() + 1).padStart(2, '0') + '-' +
    String(d.getDate()).padStart(2, '0');
}

ואז השתמשו בה במקום toISOString():

//  נכון — תאריך לפי שעון מקומי
const today = localDateStr();

//  עם אובייקט תאריך קיים
const dateStr = localDateStr(someDate);

השאירו toISOString() כשמדובר בחותמת זמן לצורכי ייצוא, לוג, או שליחת התראות (שם ה-UTC הוא הנכון):

//  זה בסדר — חותמת זמן מלאה לשרת
scheduledTime: new Date(d).toISOString()

//  זה בסדר — שמירת זמן ייצוא
exported: new Date().toISOString()

)

4. מניעת XSS — אל תכניסו נתוני משתמש ל-innerHTML

הבעיה

//  שגוי — שם קובץ / נתוני API מהרשת עלולים להכיל HTML זדוני
card.innerHTML = `<div>${fileName}</div>`;
chip.innerHTML = `<span>${img.name}</span>`;

הפתרון — פונקציית sanitize

הוסיפו את הפונקציה הבאה:

function esc(s) {
  const d = document.createElement('div');
  d.textContent = s;
  return d.innerHTML;
}

ועטפו כל ערך שמגיע ממשתמש, מקובץ, מ-API חיצוני, או מאחסון:

//  נכון
card.innerHTML = `<div>${esc(fileName)}</div>`;
chip.innerHTML = `<span>${esc(img.name)}</span>`;

אלטרנטיבה בטוחה עוד יותר — השתמשו ב-textContent ישירות:

//  הכי בטוח
const div = document.createElement('div');
div.textContent = fileName;
card.appendChild(div);

כלל: כל ערך שלא כתבתם אתם בקוד — חייב לעבור sanitize לפני הכנסה ל-innerHTML.

---

5. כלל כללי — אל תבקשו הרשאות מיותרות

בדקו כל הרשאה: האם הקוד שלכם אכן קורא ל-API המתאים? אם לא — הסירו אותה. הרשאות מיותרות מעוררות חשד, פוגעות באמון המשתמשים, ועלולות לגרום לדחיית התוסף.

---

סיכום

בעיה	פתרון
שדות חסרים ב-manifest	הוסיפו type, category, stability, minAppVersion, description, author
הרשאות לא קיימות	הסירו הרשאות שאינן ב-API הרשמי
תאריך UTC במקום מקומי	השתמשו ב-localDateStr()
XSS בנתוני משתמש/API	השתמשו ב-esc() לפני הכנסה ל-innerHTML

תמשיכו לתרום — הקהילה זקוקה לכם!

למי שמעוניין בקובץ להורדה - כהנחיה ישירה לקלוד ודומיו, עם כל הפירוט דלעיל - מצורף:

פירוט התיקונים מקלוד:

• מה תוקן בכל תוסף:

תיקוני מניפסט (רוב התוספים):

- הוספת type, category, stability, minAppVersion שהיו חסרים
- הסרת הרשאות לא חוקיות: reader.context_menu, app.info.read, calendar.read, navigation.write, reader.highlight ועוד
- הוספת הרשאות חסרות (reader.open, plugin.storage.write)

תיקוני קוד:
- continuous_study_tracker (שניהם) — תוקן timezone bug ב-setup_date
- maaser-manager — תוקן todayISO() לתאריך מקומי
- snayim-mikra — תוקן timezone bug בפונקצית הפרשה
- מעקב לימוד v1.0.4 — תוקנו 6 מקומות נוספים של .toISOString() בגרפים ולוח זמנים
- otzaria-github-downloader — XSS: שמות נכסים מ-GitHub מוגנים
- software_bug_report — XSS: שמות קבצים מקומיים מוגנים

הנחיות למפתחי תוספים לאוצריא.MD

• אגב, כל התוספים שכבר בחנות - כלל התוספים, הורדו נערכו, נופו מבאגים והועלו בחזרה כשהם מתוקנים

[י. פל.]

@יאיר-דניאל
בא נלך על בדיקות אוטומטיות!!!
רציתי ליישם זאת מתישהוא, אבל אתה עושה לי את העבודה
בא נתכנן.

1. פירוק הZIP שמועלה.
2. בדיקת API'S
3. בדיקה אם שם התוסף וכותרת התוסף היא אותו דבר (לתשומת לב מפתח בתוסף "מנהל מאגרים )
4. בדיקת שימוש במטריאל3 - ונתינת התגית "תואם לאוצריא" אוטומטית.

מה עוד?

[יאיר דניאל]

@י.-פל. כתב:

(לתשומת לב מפתח בתוסף "מנהל מאגרים )

???

[חד בדרא]

@יאיר-דניאל תכין פוסט שנוכל להעלות לקלוד עם כל ההוראות!
כי אני לא יודע לקרוא מה שכתוב...

פשוט תתתן לי הוראות להעתיק לו

@יאיר-דניאל כתב בהצעת ייעול | יוצרים תוספים? שימו לב:

תוריד את הקובץ הוראות שיש למעלה ותעלה לקלוד - הוא מבין היטב מה כתוב שם...

איזה קובץ? לא שמתי לב

[יאיר דניאל]

@חד-בדרא כתב:

לא צריך להכין כלום....
תוריד את הקובץ הוראות שיש למעלה ותעלה לקלוד - הוא מבין היטב מה כתוב שם...
אגב, בזכות @פלמנמוני כל מי שמנסה לעלות תוסף לחנות - שלא תואם לדרישות, עולה לו הודעת שגיאה מפורטת מה לא מותאם בתוסף שלו.
אל תתייאש יכול להיות שיהיו לך כמה סבבי תיקונים כאלו, אבל זה שווה את זה שהתוספים ישבו טוב ויעבדו טוב בלי שגיאות.
חיילך לאוריתא!
בהצלחה!

[יאיר דניאל]

@חד-בדרא כתב:

איזה קובץ? לא שמתי לב

אתה צודק.
הוספתי עכשיו בפוסט הראשון - בסוף.

[חד בדרא]

יש שם יותר מההוראות בגיט'?

[יום חדש מתחיל]

@יאיר-דניאל כתב:

אגב, כל התוספים שכבר בחנות - כלל התוספים, הורדו נערכו, נופו מבאגים והועלו בחזרה כשהם מתוקנים

ובטח אתה חושב שכל ה "מפתחים" שמסתמא ירצו מידי פעם לעדכן את התוספים שלהם,
יורידו את התוספים מהחנות ויחלצו אותם, ויעבדו על הקובץ המתוקן שלך...
אז תהיה בטוח שהם ממשיכים לעבוד על מה שכבר יש להם במחשב...

[י. פל.]

@יום-חדש-מתחיל
הוא האחראי על החנות, והוא פשוט לא יאשר אותם...
מלבד זאת שיש כעת בדיקות אוטומטיות, ולא ניתן בכלל להעלות לאישור תוספים שלא עברו את הבדיקות...

[יאיר דניאל]

@יום-חדש-מתחיל כתב:

ובטח אתה חושב שכל ה "מפתחים" שמסתמא ירצו מידי פעם לעדכן את התוספים שלהם,
יורידו את התוספים מהחנות ויחלצו אותם, ויעבדו על הקובץ המתוקן שלך...

א. כן, הם יהיו חייבים. כמו שכתב @י.-פל.
פשוט @פלמנמוני הגאון, הוסיף שם באתר שבעת העלאת תוסף - האתר בודק שאין בו שגיאות והגדרות לא מותאמות.

ב. כן - הם פשוט יורידו את הקובץ מהחנות ויביאו את זה לAI שאיתו הם יצרו את התוסף, ומשם הם ימשיכו לשדרוגים.
אני (עדיין...) מאמין קצת באנשים.

[דאנציג]

@יאיר-דניאל
לא מצאתי מקום לכתוב לך, אבל תוסף 'חנות' לא נגלל כל כך טוב בלוח מגע של מחשב נייד (כמו שהיה לפני שתיקנת בשאר התוספים).

[צדיק וטוב לו]

@דאנציג כתב:

@יאיר-דניאל
לא מצאתי מקום לכתוב לך, אבל תוסף 'חנות' לא נגלל כל כך טוב בלוח מגע של מחשב נייד (כמו שהיה לפני שתיקנת בשאר התוספים).

אצלי לא נגלל בכלל ב'מחוות מגע', רק בסרגל הגלילה בצד.

[יאיר דניאל]

@דאנציג כתב:

(כמו שהיה לפני שתיקנת בשאר התוספים).

אני כנראה יותר הרסתי מאשר הועלתי.
אני צריך לבדוק מה הסיפור, מקווה ש @פלמנמוני יעזור לי בזה, ניסיתי 3 פעמים בכמה דרכים - ולא הצלחתי לפתור את הבעיה, מה עוד שהרסתי את הגלילה בחנות התוספים - מה שעבד בהתחלה מצויין בגלילה בלוח המגע...

לגבי המגע במחשב - אצלי ככל הזכור לי זה כן עבד טוב, בכל התוספים. אבל אבדוק זאת שוב בל"נ.

[יאיר דניאל]

מנסה כעת לסדר את הגלילה בתוספים.
מקווה שהפעם זה יעבוד.

עריכה: לא עבד!
רק נהרסו חלק מהתוספים בדרך...
בשחזור כרגע.