@operatingtag/dsh-unclesam 0.0.0-stage → 1.0.0

package/lib/i18n.mjs

@@ -0,0 +1,141 @@
+/**
+ * Locale loading: which language the panel speaks, and how it falls back.
+ *
+ * Copyright (c) 2026 Operating Tag. All rights reserved. Released under the CC BY-NC-ND 4.0 licence.
+ *
+ * @file    i18n.mjs
+ * @version 3.9.11
+ * @author  Operating Tag (@operatingtag)
+ * @license CC-BY-NC-ND-4.0
+ *
+ * WHY THIS IS BUILT THE WAY IT IS
+ *     A person who cannot read English cannot be sold anything in English, so the panel has to speak their
+ *     language. Three rules follow, and they are the whole design:
+ *
+ *     1. Ask the harness which language it is in, rather than guessing from an IP address. The harness
+ *        already knows: it ships its own locale files and has a locale service. An IP lookup would be wrong
+ *        for anyone on a VPN, wrong for someone living abroad, and would put a network call inside a plugin
+ *        that promises nothing leaves the machine.
+ *
+ *     2. Fall back, never fail. A missing language file, a missing key, a file that will not parse - each
+ *        degrades to English for that one string. The panel must never render a key name or an empty box.
+ *
+ *     3. Let the reader choose, always. Detection is a good default and a bad decision. A Spanish speaker
+ *        who prefers English gets English, and the choice sticks.
+ *
+ * WHAT IS NOT HERE
+ *     No network requests. Every language is a file in this package, read from disk at load time.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Shown when a key is absent everywhere. Deliberately visible: it is a bug, not a translation gap. */
+const MISSING = '…';
+
+/**
+ * Fill %s placeholders in order.
+ *
+ * Values are inserted as plain text, so a translation can move a placeholder anywhere in the sentence -
+ * which many languages require - without any parsing on this side.
+ */
+function fill(template, args) {
+  let i = 0;
+  return String(template).replace(/%s/g, () => (i < args.length ? String(args[i++]) : '%s'));
+}
+
+export class Locales {
+  #dir;
+  #tables = new Map();
+  #english;
+
+  /**
+   * @param {string} dir  folder holding <code>.json files
+   * @param {string} forced  a language the reader picked; empty means follow the harness
+   */
+  constructor(dir, forced = '') {
+    this.#dir = dir;
+    this.#forced = String(forced || '').trim().toLowerCase();
+    this.#english = this.#load('en') ?? {};
+  }
+
+  #forced = '';
+
+  /** Read one language file. Absolute path or a code; anything unreadable is simply absent. */
+  #load(code) {
+    const clean = String(code || '').trim().toLowerCase().replace(/[^a-z-]/g, '');
+    if (!clean) return null;
+    if (this.#tables.has(clean)) return this.#tables.get(clean);
+
+    // `zh-CN` and `zh` are the same file; try the exact code, then the language part alone.
+    const candidates = [clean];
+    const base = clean.split('-')[0];
+    if (base !== clean) candidates.push(base);
+
+    for (const candidate of candidates) {
+      const file = join(this.#dir, `${candidate}.json`);
+      if (!existsSync(file)) continue;
+      try {
+        const table = JSON.parse(readFileSync(file, 'utf8'));
+        this.#tables.set(clean, table);
+        return table;
+      } catch {
+        // A broken file must not take the panel down with it.
+        continue;
+      }
+    }
+    this.#tables.set(clean, null);
+    return null;
+  }
+
+  /** Every language this package can speak, in menu order. */
+  available() {
+    const out = [];
+    try {
+      for (const name of readdirSync(this.#dir)) {
+        const m = /^([a-z]{2}(?:-[a-z]{2})?)\.json$/i.exec(name);
+        if (!m) continue;
+        const table = this.#load(m[1]);
+        out.push({ code: m[1].toLowerCase(), name: table?.languageName || m[1] });
+      }
+    } catch {
+      // A missing folder just means English only.
+    }
+    if (!out.some((entry) => entry.code === 'en')) out.unshift({ code: 'en', name: 'English' });
+    return out.sort((a, b) => (a.code === 'en' ? -1 : b.code === 'en' ? 1 : a.name.localeCompare(b.name)));
+  }
+
+  /**
+   * The translator for one language.
+   *
+   * `wanted` is whatever the harness reported. When the reader has picked a language, that wins; when the
+   * picked language is missing, the harness value is tried before English.
+   */
+  pick(wanted) {
+    const table =
+      this.#load(this.#forced) ?? this.#load(wanted) ?? this.#english;
+
+    /*
+     * The language's own name, for telling the model what to answer in.
+     *
+     * `languageName` is written in that language - "Español", "日本語", "فارسی" - which is right in the
+     * selector and wrong in an instruction, because the web model reads the instruction in English. So the
+     * English name is sent instead: "Spanish", "Japanese", "Persian". A model told "answer in Español"
+     * usually works it out, but "answer in Spanish" is unambiguous and costs nothing.
+     */
+    const englishName = table?.languageNameEn || (table === this.#english ? 'English' : '');
+
+    const t = (key, ...args) => {
+      const value = table?.[key] ?? this.#english?.[key];
+      if (value === undefined || value === null) return MISSING;
+      return args.length ? fill(value, args) : value;
+    };
+
+    t.meta = (key) => table?.meta?.[key] ?? this.#english?.meta?.[key] ?? MISSING;
+    t.languageName = table?.languageName || 'English';
+    t.languageNameInEnglish = englishName || t.languageName;
+    t.code = table && table !== this.#english ? Object.keys(this.#tables).find((k) => this.#tables.get(k) === table) : 'en';
+    t.available = () => this.available();
+    return t;
+  }
+}

package/lib/prefs.mjs

@@ -0,0 +1,101 @@
+/**
+ * Durable bits of the plugin's own state, kept in the harness profile.
+ *
+ * Copyright (c) 2026 Operating Tag. All rights reserved. Released under the CC BY-NC-ND 4.0 licence.
+ *
+ * @file    prefs.mjs
+ * @version 3.9.11
+ * @author  Operating Tag (@operatingtag)
+ * @license CC-BY-NC-ND-4.0
+ *
+ * WHY THIS EXISTS
+ *     The reader's language choice lived in a plain variable. Restart the harness and it was gone - the
+ *     panel silently went back to English, and because the page is only told the language when a choice
+ *     exists, answers came back in English too. Reported exactly that way: "I started harness and it was
+ *     auto-set to english."
+ *
+ *     A choice a person made should outlive a restart. Two properties matter more than features here:
+ *
+ *       * A failure to read or write must never break the plugin. A missing file, a corrupt file, or a
+ *         read-only profile all fall back to the defaults rather than throwing.
+ *       * The file must never be mistaken for the truth when it is absent. `get` returns undefined for a
+ *         key it has never been told, so the caller can tell "not chosen" from "chosen and empty".
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** Where a plugin may keep its own small state, given the harness profile directory. */
+export function prefsPath(profileDir) {
+  return join(profileDir, 'storages', 'deepseek-web-chat.json');
+}
+
+export class Prefs {
+  #file;
+  #data;
+
+  /**
+   * @param {string} file  absolute path to the JSON file
+   */
+  constructor(file) {
+    this.#file = file;
+    this.#data = this.#read();
+  }
+
+  #read() {
+    try {
+      const parsed = JSON.parse(readFileSync(this.#file, 'utf8'));
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      // Absent, unreadable or corrupt: defaults. Never throw on startup for this.
+      return {};
+    }
+  }
+
+  /** The stored value, or undefined when it was never set - never a guess. */
+  get(key) {
+    return Object.prototype.hasOwnProperty.call(this.#data, key) ? this.#data[key] : undefined;
+  }
+
+  /**
+   * Store one value and write it immediately.
+   *
+   * Written through a temporary file and renamed, because a half-written JSON file is worse than no file:
+   * the next start would silently fall back to defaults and the choice would vanish again, which is the
+   * bug this whole module exists to remove.
+   */
+  set(key, value) {
+    if (value === undefined || value === null || value === '') delete this.#data[key];
+    else this.#data[key] = value;
+    this.#flush();
+    return value;
+  }
+
+  #flush() {
+    try {
+      mkdirSync(dirname(this.#file), { recursive: true });
+      const tmp = `${this.#file}.tmp`;
+      writeFileSync(tmp, `${JSON.stringify(this.#data, null, 2)}\n`, 'utf8');
+      renameSync(tmp, this.#file);
+      return true;
+    } catch {
+      // A read-only profile must not break a working plugin; the value lives on in memory for this run.
+      return false;
+    }
+  }
+}
+
+/**
+ * The harness profile directory, from whatever the plugin can see.
+ *
+ * `DSH_PROFILE_DIR` is honoured first because it is explicit. Failing that the usual location is used,
+ * and failing that the plugin runs unpersisted rather than not at all.
+ */
+export function profileDir() {
+  const fromEnv = process.env.DSH_PROFILE_DIR;
+  if (fromEnv) return fromEnv;
+  const home = process.env.USERPROFILE || process.env.HOME || '';
+  if (!home) return null;
+  const name = process.env.DSH_PROFILE || 'desktop';
+  return join(home, '.dsh', 'profiles', name);
+}