String packs, phase 1: data-only packs that replace the wrapped site's own UI strings. Pack and inventory formats, validator (only inventory keys, parameter names, plural and select kinds, no markup), ordered idempotent engine that keeps what a restore needs, coverage and drift report; the per-site catalog hook adapter with a self-check (ok, hook not matched, no catalog seen), a fail-open webpack chunk array hook, a small DOM text net; waybetter strings check

This commit is contained in:
CRTkafa 2026-09-30 22:38:07 +07:00
parent 8324bc94af
commit 9209280959
10 changed files with 1857 additions and 2 deletions

View file

@ -112,6 +112,7 @@ const Shell = createShell({ ...site, panel: { id: 'app', title: 'wayBetter', com
- `waybetter store build --config store.config.mjs`: builds an app's part of the shared store folder (its items only, validated with the apps' own rules).
- `waybetter store sign [--init] --key <private key>` / `waybetter store verify --pub <key file>`: Ed25519 signature over the exact catalog bytes; any listed public key verifies (rotation). The private key is never printed or copied.
- `waybetter strings check <pack> [--inventory <file>] [--verbose]`: validates a string pack (data that replaces the wrapped site's own UI strings: `waybetter/runtime/stringPacks`, `waybetter/runtime/stringPackHook`, `waybetter/runtime/textNet`) against the site's string inventory and prints its coverage; the inventories otherwise come from `waybetter.strings.json` in the app's root.
- `waybetter i18n check [--write] [--verbose] [locale…]`: checks an app's catalogs (and the framework's in the same languages) with the `waybetter/i18n/check` rules, bundled plugins' inline English and the generated files; `--write` regenerates `languages.json` and the native localization files (macOS, Linux). `waybetter i18n extract [--missing]`: keys the code looks up that English lacks, and English keys without a literal lookup. Both read `waybetter.i18n.json` in the app's root (`locales`, `sources`, `nativeSources`, `bundledPlugins`, `runtimeKeys`, `supported`, `native`; schema: `i18n-config.schema.json`). `supported` lists the languages in the supported tier; every other catalog gets `tier: "community"` in the generated `languages.json` (`languages.schema.json`), and an app resolves its automatic language choices only to supported ones (`createLanguage({ supported })`).
- `waybetter release windows|macos`: signed native releases and the update manifest (`waybetter.release.json`). The Windows build runs path-free (below) and every artifact must pass the privacy scan before anything is copied or signed.
- `waybetter build-env -- <command>`: runs a build (`tauri build`, `cargo build`) so the binary holds none of the machine's paths: the home folder, the workspace, `CARGO_HOME`, `RUSTUP_HOME` and `CARGO_TARGET_DIR` become `/home`, `/src`, `/cargo`, `/rustup` and `/target` (`--remap-path-prefix` appended to the flags already in `RUSTFLAGS`/`CARGO_ENCODED_RUSTFLAGS`, `/PDBALTPATH` on MSVC; for C and C++ a build script compiles, `-ffile-prefix-map` on gcc and clang and, on MSVC, `/d1trimfile:<root>` in `CL` and `/PDBALTPATH` in `LINK`, which reach the cc crate, CMake and MSBuild alike). Without a command it prints that environment (`--json`).

View file

@ -2,13 +2,15 @@
// The `waybetter` command: `waybetter store build|sign|verify` (cli/store.mjs),
// `waybetter release windows|macos` (cli/release.mjs), `waybetter i18n check|extract`
// (cli/i18n.mjs), `waybetter privacy-scan` (cli/privacy.mjs) and `waybetter build-env`
// (cli/buildenv.mjs), `waybetter dev` (cli/dev.mjs: watchers + tauri dev).
// (cli/buildenv.mjs), `waybetter dev` (cli/dev.mjs: watchers + tauri dev), `waybetter strings check`
// (cli/strings.mjs).
import { readFileSync } from 'node:fs';
import { BUILD_ENV_USAGE, buildEnvCommand } from '../cli/buildenv.mjs';
import { DEV_USAGE, devCommand } from '../cli/dev.mjs';
import { I18N_USAGE, i18nCommand } from '../cli/i18n.mjs';
import { PRIVACY_USAGE, privacyCommand } from '../cli/privacy.mjs';
import { STORE_USAGE, storeCommand } from '../cli/store.mjs';
import { STRINGS_USAGE, stringsCommand } from '../cli/strings.mjs';
import { RELEASE_USAGE, releaseCommand } from '../cli/release.mjs';
const [area, ...rest] = process.argv.slice(2);
@ -19,6 +21,8 @@ try {
await releaseCommand(rest);
} else if (area === 'i18n') {
process.exitCode = await i18nCommand(rest);
} else if (area === 'strings') {
process.exitCode = await stringsCommand(rest);
} else if (area === 'privacy-scan') {
process.exitCode = privacyCommand(rest);
} else if (area === 'build-env') {
@ -28,7 +32,7 @@ try {
} else if (area === '--version' || area === '-v') {
console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
} else {
console.log(`${STORE_USAGE}\n\n${RELEASE_USAGE}\n\n${I18N_USAGE}\n\n${PRIVACY_USAGE}\n\n${BUILD_ENV_USAGE}
console.log(`${STORE_USAGE}\n\n${RELEASE_USAGE}\n\n${I18N_USAGE}\n\n${STRINGS_USAGE}\n\n${PRIVACY_USAGE}\n\n${BUILD_ENV_USAGE}
${DEV_USAGE}`);
if (area && area !== '--help' && area !== '-h') process.exitCode = 1;

View file

@ -0,0 +1,121 @@
// `waybetter strings check`: a string pack against a site's string inventory, with the
// framework's rules (waybetter/runtime/stringPacks: the envelope, only inventory keys, parameter
// names, plural and select kinds, no markup) and its coverage.
//
// waybetter strings check pack.strings.json --inventory strings/x.web.inventory.json
// waybetter strings check pack.strings.json the inventory comes from the config
// waybetter strings check pack.strings.json --verbose list every key that was refused or unknown
//
// Config: waybetter.strings.json in the app's root (or --config <file>); paths are relative to it.
//
// { "inventories": ["strings/x.web.inventory.json"] }
//
// The pack names its site and catalog; the inventory with the same two is used. Exit 1 when the
// envelope is invalid, a value is refused or a key is unknown (none of those is ever applied).
import { existsSync, readFileSync } from 'node:fs';
import { dirname, isAbsolute, relative, resolve } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
export const STRINGS_CONFIG_FILE = 'waybetter.strings.json';
export const STRINGS_USAGE = `Usage:
waybetter strings check <pack> [--inventory <file>] [--verbose] [--config <file>]
Validates a string pack against the site's string inventory and prints its coverage.
Config: ${STRINGS_CONFIG_FILE} in the app's root (inventories).`;
class StringsError extends Error {}
const LISTED = 12;
/** The pack rules: the framework's sources inside its repository, else the built package. */
async function loadRules() {
const source = fileURLToPath(new URL('../../runtime/src/stringPacks.ts', import.meta.url));
const built = fileURLToPath(new URL('../dist/runtime/stringPacks.js', import.meta.url));
const file = existsSync(source) ? source : built;
if (!existsSync(file)) throw new StringsError('the string pack rules are not built (run the package build)');
return import(pathToFileURL(file).href);
}
function readJson(file, what) {
if (!existsSync(file)) throw new StringsError(`${what} not found: ${file}`);
try {
return JSON.parse(readFileSync(file, 'utf8'));
} catch (error) {
throw new StringsError(`${what} is not JSON: ${file} (${error instanceof Error ? error.message : error})`);
}
}
/** The inventories a config lists, as absolute paths. */
export function loadStringsConfig(cwd, file) {
const path = resolve(cwd, file ?? STRINGS_CONFIG_FILE);
if (!existsSync(path)) throw new StringsError(`${relative(cwd, path) || path} not found: pass --inventory <file> (see \`waybetter strings --help\`)`);
const config = readJson(path, 'the config');
if (!Array.isArray(config.inventories) || config.inventories.some(item => typeof item !== 'string')) throw new StringsError(`${relative(cwd, path)}: "inventories" must be a list of files`);
return { inventories: config.inventories.map(item => resolve(dirname(path), item)) };
}
const percent = (part, whole) => (whole ? `${(part / whole * 100).toFixed(part && part < whole / 1000 ? 2 : 1)}%` : 'n/a');
/**
* Checks one pack. `inventories` are inventory files; the one for the pack's site and catalog is
* used. Returns the lines to print, the number of errors and the compiled report.
*/
export async function checkPack(packFile, inventories, { verbose = false } = {}) {
const rules = await loadRules();
const pack = readJson(packFile, 'the pack');
const lines = [];
const issues = rules.checkPackShape(pack);
for (const issue of issues) lines.push(`${issue.level}: ${issue.message}`);
if (issues.some(issue => issue.level === 'error')) return { lines, errors: issues.filter(issue => issue.level === 'error').length, report: null, coverage: null };
const loaded = inventories.map(file => ({ file, inventory: readJson(file, 'the inventory') }));
const match = loaded.find(item => item.inventory.site === pack.site && item.inventory.catalog === pack.catalog);
if (!match) throw new StringsError(`no inventory for ${pack.site}/${pack.catalog} (have: ${loaded.map(item => `${item.inventory.site}/${item.inventory.catalog}`).join(', ') || 'none'})`);
if (match.inventory.format !== 1 || typeof match.inventory.entries !== 'object') throw new StringsError(`${match.file} is not a string inventory`);
const compiled = rules.compilePack(pack, match.inventory);
const { report } = compiled;
const coverage = rules.coverage(match.inventory, compiled);
lines.push(`${pack.name} (${pack.language}) for ${pack.site}/${pack.catalog}, inventory build ${match.inventory.build ?? 'unknown'}`);
lines.push(`${report.total} strings: ${report.valid} valid, ${report.rejected.length} refused, ${report.unknown.length} unknown`);
const list = (items, render) => {
for (const item of verbose ? items : items.slice(0, LISTED)) lines.push(` ${render(item)}`);
if (!verbose && items.length > LISTED) lines.push(` … ${items.length - LISTED} more (--verbose lists all)`);
};
if (report.rejected.length) {
lines.push('Refused (not applied, the site\'s text stays):');
list(report.rejected, item => `${item.id}: ${item.reason}`);
}
if (report.unknown.length) {
lines.push('Unknown keys (not in the inventory, never applied):');
list(report.unknown, id => id);
}
lines.push('Coverage:');
for (const [group, numbers] of Object.entries(coverage)) {
lines.push(` ${group.padEnd(8)} ${numbers.translated} of ${numbers.translatable} translatable strings (${percent(numbers.translated, numbers.translatable)})${numbers.closed ? `; ${numbers.closed} not translatable yet (rich text, formatters)` : ''}`);
}
return { lines, errors: report.rejected.length + report.unknown.length, report, coverage };
}
export async function stringsCommand(args, { cwd = process.cwd(), log = console.log } = {}) {
const [action, ...rest] = args;
const value = flag => {
const at = rest.indexOf(flag);
if (at < 0) return undefined;
if (!rest[at + 1] || rest[at + 1].startsWith('--')) throw new StringsError(`${flag} needs a file`);
return rest[at + 1];
};
if (action === 'check') {
const inventory = value('--inventory');
const config = value('--config');
const taken = new Set([inventory, config].filter(Boolean));
const [pack, ...extra] = rest.filter(arg => !arg.startsWith('--') && !taken.has(arg));
if (!pack || extra.length) throw new StringsError('check needs one pack file');
const at = file => (isAbsolute(file) ? file : resolve(cwd, file));
const inventories = inventory ? [at(inventory)] : loadStringsConfig(cwd, config).inventories;
const result = await checkPack(at(pack), inventories, { verbose: rest.includes('--verbose') });
for (const line of result.lines) log(line);
return result.errors ? 1 : 0;
}
log(STRINGS_USAGE);
return action && action !== '--help' && action !== '-h' ? 1 : 0;
}

View file

@ -0,0 +1,80 @@
// `waybetter strings check` on a small site inventory.
import assert from 'node:assert/strict';
import { execFileSync, spawnSync } from 'node:child_process';
import { mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import test from 'node:test';
import { fileURLToPath } from 'node:url';
import { checkPack, loadStringsConfig, stringsCommand } from '../cli/strings.mjs';
const BIN = fileURLToPath(new URL('../bin/waybetter.mjs', import.meta.url));
const json = (file, value) => writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
/** An app folder: an inventory (2 texts, 1 plural message, 1 rich entry, 1 emoji name), a config, a pack. */
function app(strings, extra = {}) {
const dir = mkdtempSync(join(tmpdir(), 'wb-strings-'));
json(join(dir, 'demo.web.inventory.json'), { format: 1, site: 'demo', catalog: 'web', base: 'en', build: 'b7', entries: {
a0000001: { kind: 'text', hash: '00000000001' },
a0000002: { kind: 'text', hash: '00000000002' },
b0000001: { kind: 'message', params: ['count'], plural: ['count'], hash: '00000000003' },
c0000001: { kind: 'rich', hash: '00000000004' },
e0000001: { kind: 'text', group: 'emoji', hash: '00000000005' },
} });
json(join(dir, 'waybetter.strings.json'), { inventories: ['demo.web.inventory.json'] });
json(join(dir, 'pack.json'), { format: 1, site: 'demo', catalog: 'web', language: 'en-x-test', name: 'Testish', authors: ['A tester'], strings, ...extra });
return dir;
}
test('check: a valid pack passes and prints its coverage per group', async () => {
const dir = app({ a0000001: 'Hoom', b0000001: '{count, plural, one {# postle} other {# postles}}' });
const result = await checkPack(join(dir, 'pack.json'), [join(dir, 'demo.web.inventory.json')]);
assert.equal(result.errors, 0);
const text = result.lines.join('\n');
assert.match(text, /Testish \(en-x-test\) for demo\/web, inventory build b7/);
assert.match(text, /2 strings: 2 valid, 0 refused, 0 unknown/);
assert.match(text, /all\s+2 of 4 translatable strings \(50\.0%\); 1 not translatable yet/);
assert.match(text, /main\s+2 of 3 translatable strings/);
assert.match(text, /emoji\s+0 of 1 translatable strings \(0\.0%\)/);
assert.deepEqual(result.coverage.all, { translatable: 4, translated: 2, closed: 1 });
});
test('check: unknown keys and refused values are errors, listed with the reason', async () => {
const dir = app({ a0000001: '<b>Hoom</b>', b0000001: '{total} postles', c0000001: 'Rich', zzzzzzzz: 'Nope', a0000002: 'Fine' });
const lines = [];
const code = await stringsCommand(['check', 'pack.json'], { cwd: dir, log: line => lines.push(line) });
assert.equal(code, 1);
const text = lines.join('\n');
assert.match(text, /5 strings: 1 valid, 3 refused, 1 unknown/);
assert.match(text, /a0000001: markup is not allowed/);
assert.match(text, /b0000001: \{total\} is not a parameter of the original \(it has: count\)/);
assert.match(text, /c0000001: not translatable yet \(rich\)/);
assert.match(text, /Unknown keys[^\n]*\n\s+zzzzzzzz/);
});
test('check: an invalid envelope stops before the inventory; a pack for another catalog has no inventory', async () => {
const dir = app({}, { language: 'not a tag', format: 3 });
const result = await checkPack(join(dir, 'pack.json'), [join(dir, 'demo.web.inventory.json')]);
assert.equal(result.errors, 2);
assert.equal(result.report, null);
const other = app({ a0000001: 'x' }, { catalog: 'guest' });
await assert.rejects(stringsCommand(['check', 'pack.json'], { cwd: other, log() {} }), /no inventory for demo\/guest \(have: demo\/web\)/);
});
test('command: the config, --inventory, usage and the binary', async () => {
const dir = app({ a0000001: 'Hoom' });
assert.deepEqual(loadStringsConfig(dir).inventories, [join(dir, 'demo.web.inventory.json')]);
assert.throws(() => loadStringsConfig(tmpdir(), 'nope.json'), /pass --inventory/);
const lines = [];
assert.equal(await stringsCommand(['check', 'pack.json', '--inventory', 'demo.web.inventory.json'], { cwd: dir, log: line => lines.push(line) }), 0);
assert.equal(await stringsCommand([], { log: line => lines.push(line) }), 0);
assert.equal(await stringsCommand(['nope'], { log() {} }), 1);
await assert.rejects(stringsCommand(['check'], { cwd: dir, log() {} }), /one pack file/);
await assert.rejects(stringsCommand(['check', 'pack.json', '--inventory'], { cwd: dir, log() {} }), /--inventory needs a file/);
const out = execFileSync(process.execPath, [BIN, 'strings', 'check', 'pack.json'], { cwd: dir, encoding: 'utf8' });
assert.match(out, /1 strings: 1 valid/);
const bad = app({ zzzzzzzz: 'x' });
const run = spawnSync(process.execPath, [BIN, 'strings', 'check', 'pack.json'], { cwd: bad, encoding: 'utf8' });
assert.equal(run.status, 1);
assert.match(execFileSync(process.execPath, [BIN, '--help'], { encoding: 'utf8' }), /waybetter strings check/);
});