@qnroa/qtype 0.0.1

package/dist/core/typing/metrics.js

@@ -0,0 +1,20 @@
+const MS_PER_MINUTE = 60_000;
+export function computeMetrics(s, now = Date.now()) {
+    const startedAt = s.startedAt ?? now;
+    const endedAt = s.finishedAt ?? now;
+    const elapsedMs = Math.max(1, endedAt - startedAt);
+    const totalTyped = s.correctCount + s.wrongCount;
+    const accuracy = totalTyped === 0 ? 1 : s.correctCount / totalTyped;
+    const cpm = (s.correctCount / elapsedMs) * MS_PER_MINUTE;
+    const wpm = cpm / 5;
+    return {
+        cpm: round(cpm),
+        wpm: round(wpm),
+        accuracy: round(accuracy, 4),
+        elapsedMs,
+    };
+}
+function round(n, digits = 2) {
+    const p = 10 ** digits;
+    return Math.round(n * p) / p;
+}

package/dist/store/index.js

@@ -0,0 +1,44 @@
+/**
+ * Persistent KV store module.
+ *
+ * ## Two-layer architecture
+ *
+ * ```
+ *   KvStore                    ← business API (get/set/delete/list + optional schema)
+ *     ↓ depends on
+ *   Storage                    ← medium abstraction (read/write entire blob)
+ *     ↓ implemented by
+ *   JsonStorage / BrowserStorage / MemoryStorage
+ * ```
+ *
+ * ## Typical usage
+ *
+ * ```ts
+ * import { KvStore, JsonStorage } from '../../store/index.js';
+ *
+ * const kv = new KvStore(new JsonStorage('user', '/path/to/config.json'));
+ * await kv.set('cli.lang', 'zh');
+ * const lang = await kv.get('cli.lang');
+ * ```
+ *
+ * ## With schema (used by the `qtype config` CLI)
+ *
+ * ```ts
+ * import { KvStore, enumValidator } from '../../store/index.js';
+ *
+ * const kv = new KvStore(storage, {
+ *   'cli.lang': {
+ *     validator: enumValidator(['zh', 'en']),
+ *     default: 'en',
+ *   },
+ * }, { strict: true });
+ * ```
+ *
+ * See `types.ts` / `kv.ts` for detailed design.
+ */
+export * from './types.js';
+export { KvStore, parseKey, getAt, setAt, unsetAt, flatten, } from './kv.js';
+export { enumValidator, nonEmptyStringValidator, boolValidator, positiveIntValidator, absolutePathValidator, predicateValidator, } from './validators.js';
+export { JsonStorage } from './storage/json.js';
+export { BrowserStorage } from './storage/browser.js';
+export { MemoryStorage } from './storage/memory.js';

package/dist/store/kv.js

@@ -0,0 +1,276 @@
+import { KvError } from './types.js';
+// ═══════════════════════════════════════════════════════════════
+// Pure function utilities
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Segment names that would let a hostile `setAt` reach the prototype chain
+ * and pollute every object in the process (`__proto__`, `constructor`,
+ * `prototype`). Reject them at parse time.
+ *
+ * Without this guard, `qtype config set __proto__.poisoned OWNED` would
+ * write `Object.prototype.poisoned = 'OWNED'` and contaminate downstream
+ * code that uses object literals (the entire app, basically).
+ */
+const FORBIDDEN_SEGMENTS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+]);
+/** Parse `a.b.c` → `{ path: ['a','b','c'], raw: 'a.b.c' }`. */
+export function parseKey(raw) {
+    // Splitting an empty string yields [''], length===1 but segment is empty —
+    // caught by the `some` check below. Pure dots like 'a..b' are also caught
+    // by `some`. No need to special-case length===0.
+    const parts = raw.split('.');
+    if (parts.some((p) => p === '')) {
+        throw new KvError('err.kv.key.invalid', { raw }, `invalid key: '${raw}'. Expected dot-separated non-empty segments (e.g. 'cli.lang')`);
+    }
+    if (parts.some((p) => FORBIDDEN_SEGMENTS.has(p))) {
+        throw new KvError('err.kv.key.invalid', { raw }, `invalid key: '${raw}'. Segments cannot be reserved names (__proto__ / constructor / prototype).`);
+    }
+    return { path: parts, raw };
+}
+/**
+ * Defense-in-depth: even though parseKey rejects __proto__ / constructor /
+ * prototype, a config file that already contains those keys (manually edited
+ * or written by an older buggy version) would still hit them via getAt/setAt.
+ * Refusing to traverse forbidden segments at access time keeps the store
+ * safe regardless of how the path was constructed.
+ */
+function isForbidden(seg) {
+    return seg === '__proto__' || seg === 'constructor' || seg === 'prototype';
+}
+/**
+ * Use `Object.hasOwn` instead of `seg in obj` / `obj[seg]` directly so we
+ * never read prototype-chain properties (e.g. inherited toString).
+ */
+function getOwn(obj, seg) {
+    if (isForbidden(seg))
+        return undefined;
+    return Object.prototype.hasOwnProperty.call(obj, seg) ? obj[seg] : undefined;
+}
+/** Get a value from a nested object by path. Returns undefined if any intermediate level is missing. */
+export function getAt(obj, path) {
+    let cur = obj;
+    for (const seg of path) {
+        if (cur == null || typeof cur !== 'object' || Array.isArray(cur))
+            return undefined;
+        cur = getOwn(cur, seg);
+        if (cur === undefined)
+            return undefined;
+    }
+    return cur;
+}
+/** Set a value in a nested object by path. Auto-creates intermediate levels. */
+export function setAt(obj, path, value) {
+    if (path.length === 0)
+        throw new Error('setAt: empty path');
+    // Refuse forbidden segments at write time too (parseKey is the front
+    // door, this is the back door).
+    for (const seg of path) {
+        if (isForbidden(seg)) {
+            throw new Error(`setAt: forbidden segment '${seg}'`);
+        }
+    }
+    let cur = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const seg = path[i];
+        // Use hasOwn to avoid reading inherited properties; if the segment is
+        // not own, treat it as missing and create a fresh object.
+        const ownNext = Object.prototype.hasOwnProperty.call(cur, seg)
+            ? cur[seg]
+            : undefined;
+        if (ownNext == null || typeof ownNext !== 'object' || Array.isArray(ownNext)) {
+            cur[seg] = {};
+        }
+        cur = cur[seg];
+    }
+    cur[path[path.length - 1]] = value;
+}
+/** Delete a value from a nested object by path. Empty intermediate levels are cleaned up upward. Returns whether anything was actually deleted. */
+export function unsetAt(obj, path) {
+    if (path.length === 0)
+        return false;
+    // Refuse forbidden segments at delete time too — without this, a
+    // pre-poisoned config object's `__proto__` segment would let callers
+    // walk into the prototype chain and `delete` properties off Object.prototype.
+    if (path.some((seg) => isForbidden(seg)))
+        return false;
+    const chain = [];
+    let cur = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const seg = path[i];
+        if (!Object.prototype.hasOwnProperty.call(cur, seg))
+            return false;
+        const next = cur[seg];
+        if (next == null || typeof next !== 'object' || Array.isArray(next))
+            return false;
+        chain.push({ parent: cur, key: seg });
+        cur = next;
+    }
+    const leaf = path[path.length - 1];
+    if (!Object.prototype.hasOwnProperty.call(cur, leaf))
+        return false;
+    delete cur[leaf];
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const { parent, key } = chain[i];
+        const child = parent[key];
+        if (child != null && typeof child === 'object' && !Array.isArray(child)) {
+            if (Object.keys(child).length === 0)
+                delete parent[key];
+            else
+                break;
+        }
+    }
+    return true;
+}
+/** Flatten a nested object into dot-separated keys. Arrays are not descended into. */
+export function flatten(obj, prefix = [], out = []) {
+    // Object.entries is "own enumerable string-keyed" — already excludes
+    // properties inherited via the prototype chain, so a poisoned global
+    // Object.prototype won't leak into list output here.
+    for (const [k, v] of Object.entries(obj)) {
+        if (isForbidden(k))
+            continue; // belt-and-suspenders
+        const p = [...prefix, k];
+        if (v != null && typeof v === 'object' && !Array.isArray(v)) {
+            flatten(v, p, out);
+        }
+        else {
+            out.push([p.join('.'), v]);
+        }
+    }
+    return out;
+}
+// ═══════════════════════════════════════════════════════════════
+// KvStore class
+// ═══════════════════════════════════════════════════════════════
+export class KvStore {
+    storage;
+    schema;
+    strict;
+    constructor(storage, schema = {}, options = {}) {
+        this.storage = storage;
+        this.schema = { ...schema };
+        this.strict = options.strict === true;
+    }
+    /** Scope tag for this KV (from the underlying storage). */
+    get scope() {
+        return this.storage.scope;
+    }
+    /** Origin string for this KV (file path, etc.), shown by --show-origin. */
+    get origin() {
+        return this.storage.origin;
+    }
+    /** Whether the underlying storage is available. */
+    async available() {
+        return this.storage.available();
+    }
+    // ── Schema registration ─────────────────────────────────
+    /** Register the schema for a single key. Re-registering overrides. */
+    registerSchema(key, entry) {
+        this.schema[key] = entry;
+    }
+    /** Bulk-extend the schema. Later registrations override earlier ones for the same key. */
+    extendSchema(schema) {
+        for (const [k, v] of Object.entries(schema)) {
+            this.schema[k] = v;
+        }
+    }
+    /** Return the schema entry for a key (can be used to look up default values, scope hints, etc.). */
+    getSchema(key) {
+        return this.schema[key];
+    }
+    /** List all keys known to the schema. */
+    knownKeys() {
+        return Object.keys(this.schema);
+    }
+    // ── CRUD ─────────────────────────────────────────────────
+    /**
+     * Read the value for a key.
+     *
+     * Order:
+     *   1. storage unavailable → fall back to schema default
+     *   2. underlying storage has a value → return it
+     *   3. schema has a default → return default
+     *   4. neither → undefined
+     */
+    async get(rawKey) {
+        const key = parseKey(rawKey);
+        if (!(await this.storage.available())) {
+            return this.schema[rawKey]?.default;
+        }
+        const data = await this.storage.read();
+        const v = getAt(data, key.path);
+        if (v !== undefined)
+            return v;
+        return this.schema[rawKey]?.default;
+    }
+    /**
+     * Write the value for a key.
+     *
+     * Order:
+     *   1. Parse the key
+     *   2. In strict mode, key not in schema → throw
+     *   3. Schema has a validator → validate; throw on failure
+     *   4. Storage unavailable → throw
+     *   5. Read-modify-write
+     */
+    async set(rawKey, value) {
+        const key = parseKey(rawKey);
+        const entry = this.schema[rawKey];
+        if (this.strict && !entry) {
+            const known = Object.keys(this.schema).join(', ') || '(none)';
+            throw new KvError('err.kv.unknown.key', { key: rawKey, known }, `unknown key '${rawKey}'. Known: ${known}`);
+        }
+        if (entry?.validator) {
+            const err = entry.validator(value);
+            if (err) {
+                // Inject the key into vars. Spread validator's vars first, then overwrite `key`,
+                // so that even if a validator author misuses `key` as a variable name they
+                // can't override KvStore's rawKey.
+                throw new KvError(err.code, { ...(err.vars ?? {}), key: rawKey }, `invalid value for '${rawKey}': ${err.fallback}`);
+            }
+        }
+        if (!(await this.storage.available())) {
+            throw new KvError('err.kv.storage.unavailable', { scope: this.storage.scope, origin: this.storage.origin }, `storage unavailable: ${this.storage.origin}`);
+        }
+        const data = await this.storage.read();
+        setAt(data, key.path, value);
+        await this.storage.write(data);
+    }
+    /**
+     * Delete a key. Returns whether anything was actually deleted (false if the key didn't exist).
+     */
+    async delete(rawKey) {
+        const key = parseKey(rawKey);
+        if (!(await this.storage.available()))
+            return false;
+        const data = await this.storage.read();
+        const removed = unsetAt(data, key.path);
+        if (removed)
+            await this.storage.write(data);
+        return removed;
+    }
+    /**
+     * List all keys that have been set (flattened to dot-separated keys).
+     *
+     * Does not include keys that have a default in schema but were never actually written.
+     */
+    async list() {
+        if (!(await this.storage.available()))
+            return [];
+        const data = await this.storage.read();
+        const entries = flatten(data);
+        entries.sort((a, b) => a[0].localeCompare(b[0]));
+        return entries;
+    }
+    /** Check whether a key actually exists in storage (ignoring defaults). */
+    async has(rawKey) {
+        const key = parseKey(rawKey);
+        if (!(await this.storage.available()))
+            return false;
+        const data = await this.storage.read();
+        return getAt(data, key.path) !== undefined;
+    }
+}

package/dist/store/storage/browser.js

@@ -0,0 +1,61 @@
+import { KvError } from '../types.js';
+function getLocalStorage() {
+    try {
+        const ls = globalThis.localStorage;
+        return ls ?? null;
+    }
+    catch {
+        // Some browsers throw on accessing localStorage in private mode
+        return null;
+    }
+}
+export class BrowserStorage {
+    scope;
+    storageKey;
+    constructor(scope, storageKey = `qtype.config.${scope}`) {
+        this.scope = scope;
+        this.storageKey = storageKey;
+    }
+    get origin() {
+        return `localStorage:${this.storageKey}`;
+    }
+    async available() {
+        return getLocalStorage() !== null;
+    }
+    async read() {
+        const ls = getLocalStorage();
+        if (!ls)
+            return {};
+        const raw = ls.getItem(this.storageKey);
+        if (!raw)
+            return {};
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch (e) {
+            throw new KvError('err.kv.storage.parseFailed', { origin: this.origin, reason: e.message }, `${this.origin}: JSON parse error — ${e.message}`);
+        }
+        if (data == null)
+            return {}; // treat literal null as empty, aligned with JsonStorage
+        if (typeof data !== 'object' || Array.isArray(data)) {
+            throw new KvError('err.kv.storage.parseFailed', {
+                origin: this.origin,
+                reason: `root must be a JSON object, got ${Array.isArray(data) ? 'array' : typeof data}`,
+            }, `${this.origin}: root must be a JSON object`);
+        }
+        return data;
+    }
+    async write(data) {
+        const ls = getLocalStorage();
+        if (!ls) {
+            throw new KvError('err.kv.storage.unavailable', { scope: this.scope, origin: this.origin }, `${this.origin}: localStorage not available`);
+        }
+        try {
+            ls.setItem(this.storageKey, JSON.stringify(data));
+        }
+        catch (e) {
+            throw new KvError('err.kv.storage.writeFailed', { origin: this.origin, reason: e.message }, `${this.origin}: write failed — ${e.message}`);
+        }
+    }
+}

package/dist/store/storage/json.js

@@ -0,0 +1,113 @@
+/**
+ * JSON file storage.
+ *
+ * Read: exists → parse JSON; missing → return {}; parse failure → throw `KvError`.
+ * Write: atomic (write .tmp then rename), auto-creates parent directory;
+ *        IO failure → throw `KvError`. Keys are recursively sorted for
+ *        diff-friendly output.
+ *
+ * ## About `available()`
+ *
+ * Always available by default (write will `mkdir -p` the parent directory).
+ * Business judgments like "are we in a repo" are decided by the caller —
+ * just pass a `guard` function to the constructor:
+ *
+ * ```ts
+ * new JsonStorage('repo', path, { guard: () => fs.existsSync(repoRoot) });
+ * ```
+ *
+ * Without `guard`, it is always available.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { KvError } from '../types.js';
+export class JsonStorage {
+    scope;
+    filePath;
+    guard;
+    constructor(scope, filePath, options = {}) {
+        this.scope = scope;
+        this.filePath = filePath;
+        this.guard = options.guard;
+    }
+    get origin() {
+        return this.filePath;
+    }
+    async available() {
+        if (!this.guard)
+            return true;
+        try {
+            return this.guard();
+        }
+        catch {
+            return false;
+        }
+    }
+    async read() {
+        if (!fs.existsSync(this.filePath))
+            return {};
+        const text = fs.readFileSync(this.filePath, 'utf8').trim();
+        if (!text)
+            return {};
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch (e) {
+            throw new KvError('err.kv.storage.parseFailed', { origin: this.filePath, reason: e.message }, `${this.filePath}: JSON parse error — ${e.message}`);
+        }
+        if (data == null)
+            return {};
+        if (typeof data !== 'object' || Array.isArray(data)) {
+            throw new KvError('err.kv.storage.parseFailed', { origin: this.filePath, reason: `root must be a JSON object, got ${typeof data}` }, `${this.filePath}: root must be a JSON object, got ${typeof data}`);
+        }
+        return data;
+    }
+    async write(data) {
+        const sorted = sortKeys(data);
+        const text = JSON.stringify(sorted, null, 2) + '\n';
+        // Per-process unique tmp name. Without this, two qtype processes
+        // writing the same file concurrently (e.g. a CLI run overlapping
+        // with another long-running qtype process) would both target
+        // `<file>.tmp` — the later writer's rename clobbers the earlier
+        // .tmp midway, so the earlier writer either errors out or silently
+        // produces a corrupt file. The pid + intra-process counter
+        // combination keeps the rename's atomic last-writer-wins semantics
+        // on the *final* file
+        // but eliminates the tmp-collision corruption.
+        const tmp = `${this.filePath}.${process.pid}.${nextWriteSeq()}.tmp`;
+        try {
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+            fs.writeFileSync(tmp, text, 'utf8');
+            fs.renameSync(tmp, this.filePath);
+        }
+        catch (e) {
+            // Best-effort cleanup of .tmp (it may not have been created)
+            try {
+                if (fs.existsSync(tmp))
+                    fs.unlinkSync(tmp);
+            }
+            catch {
+                /* ignore */
+            }
+            throw new KvError('err.kv.storage.writeFailed', { origin: this.filePath, reason: e.message }, `${this.filePath}: write failed — ${e.message}`);
+        }
+    }
+}
+/** Per-process counter so concurrent writes within the same process also get
+ *  distinct tmp names. */
+let writeSeq = 0;
+function nextWriteSeq() {
+    return ++writeSeq;
+}
+/** Recursively sort by key for stable output (diff-friendly). */
+function sortKeys(v) {
+    if (v == null || typeof v !== 'object' || Array.isArray(v))
+        return v;
+    const obj = v;
+    const out = {};
+    for (const k of Object.keys(obj).sort()) {
+        out[k] = sortKeys(obj[k]);
+    }
+    return out;
+}

package/dist/store/storage/memory.js

@@ -0,0 +1,24 @@
+export class MemoryStorage {
+    scope;
+    origin;
+    _available;
+    data = {};
+    constructor(scope, options = {}) {
+        this.scope = scope;
+        this.origin = options.origin ?? `memory:${scope}`;
+        this._available = options.available ?? true;
+    }
+    /** Test helper: toggle availability at runtime. */
+    setAvailable(v) {
+        this._available = v;
+    }
+    async available() {
+        return this._available;
+    }
+    async read() {
+        return structuredClone(this.data);
+    }
+    async write(data) {
+        this.data = structuredClone(data);
+    }
+}

package/dist/store/types.js

@@ -0,0 +1,47 @@
+/**
+ * Type definitions for the KV storage layer.
+ *
+ * ## Two-layer architecture
+ *
+ * ```
+ * KvStore       ← business API (get/set/delete/list, optional schema)
+ *   ↓ depends on
+ * Storage       ← medium abstraction (read entire blob / write entire blob)
+ *   ↓ implemented by
+ * JsonStorage / BrowserStorage / MemoryStorage
+ * ```
+ *
+ * KvStore doesn't care where data is stored or how it's serialized; Storage
+ * doesn't care how the data is used. Decoupled via the Storage interface.
+ */
+// ═══════════════════════════════════════════════════════════════
+// Error types
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Structured error thrown by the KV layer.
+ *
+ * Carries `code` + `vars`: the CLI's `wrapAction` catches it and runs i18n
+ * translation; other hosts (tests / app) just display `message` (the English
+ * fallback).
+ *
+ * ## Defined codes
+ *
+ * - `err.kv.key.invalid`           — invalid key format (empty / pure dots / ...)
+ * - `err.kv.unknown.key`           — key not in schema under strict mode
+ * - `err.kv.storage.unavailable`   — storage.available() === false
+ * - `err.kv.storage.parseFailed`   — failed to parse the blob in storage (JSON corruption, etc.)
+ * - `err.kv.storage.writeFailed`   — failed to write storage (localStorage quota exceeded, etc.)
+ *
+ * Validator-thrown errors keep their own `code` (typically `err.schema.*`);
+ * KvStore does not wrap them, keeping the message context direct.
+ */
+export class KvError extends Error {
+    code;
+    vars;
+    constructor(code, vars, fallback) {
+        super(fallback);
+        this.name = 'KvError';
+        this.code = code;
+        this.vars = vars;
+    }
+}

package/dist/store/validators.js

@@ -0,0 +1,71 @@
+/** Value must be one of the specified enum strings. */
+export function enumValidator(allowed) {
+    return (v) => {
+        if (typeof v === 'string' && allowed.includes(v)) {
+            return null;
+        }
+        return {
+            code: 'err.schema.enum',
+            vars: { allowed: allowed.map((x) => `'${x}'`).join(' | ') },
+            fallback: `must be one of: ${allowed.join(' | ')}`,
+        };
+    };
+}
+/** Value must be a non-empty string. */
+export function nonEmptyStringValidator() {
+    return (v) => {
+        if (typeof v === 'string' && v.length > 0)
+            return null;
+        return {
+            code: 'err.schema.nonEmptyString',
+            fallback: 'must be a non-empty string',
+        };
+    };
+}
+/** Value must be a boolean. */
+export function boolValidator() {
+    return (v) => {
+        if (typeof v === 'boolean')
+            return null;
+        return {
+            code: 'err.schema.bool',
+            fallback: 'must be true or false',
+        };
+    };
+}
+/**
+ * Value must be a positive integer (also accepts numeric string form, so the
+ * CLI can pass things like `--port 4000`).
+ */
+export function positiveIntValidator() {
+    return (v) => {
+        if (typeof v === 'number' && Number.isInteger(v) && v > 0)
+            return null;
+        if (typeof v === 'string' && /^\d+$/.test(v) && Number(v) > 0)
+            return null;
+        return {
+            code: 'err.schema.positiveInt',
+            fallback: 'must be a positive integer',
+        };
+    };
+}
+/** Value must be a string starting with `/` (path base). */
+export function absolutePathValidator() {
+    return (v) => {
+        if (typeof v === 'string' && v.startsWith('/'))
+            return null;
+        return {
+            code: 'err.schema.absolutePath',
+            fallback: "must be a path starting with '/'",
+        };
+    };
+}
+/**
+ * Custom validator: pass a predicate + i18n error key.
+ *
+ * Fallback for when the built-in helpers aren't enough; business code should
+ * generally prefer the specific functions above.
+ */
+export function predicateValidator(predicate, error) {
+    return (v) => (predicate(v) ? null : error);
+}