@g9tm/app-diagnostic 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +10 -4
- package/src/bytes.ts +48 -0
- package/src/host.ts +124 -0
- package/src/index.ts +30 -0
- package/src/live/bundle.ts +77 -0
- package/src/live/channel.ts +496 -0
- package/src/live/handlers.ts +426 -0
- package/src/live/models.ts +360 -0
- package/src/live/upload.ts +175 -0
- package/src/recording.ts +176 -0
- package/src/store.ts +39 -0
- package/src/strings.generated.ts +242 -0
- package/src/strings.ts +37 -0
- package/src/tester/archive.ts +83 -0
- package/src/tester/compose.ts +99 -0
- package/src/tester/engine.ts +852 -0
- package/src/tester/feed.ts +182 -0
- package/src/tester/gesture.ts +61 -0
- package/src/tester/model.ts +125 -0
- package/src/tester/outbox.ts +131 -0
- package/src/tester/screen.ts +117 -0
- package/src/tester/store.ts +145 -0
- package/src/tester/timeline.ts +98 -0
- package/src/upload.ts +236 -0
- package/src/wire.ts +133 -0
- package/README.md +0 -3
package/package.json
CHANGED
|
@@ -1,6 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@g9tm/app-diagnostic",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Device diagnostics client for apps in the field: tester reports (resumable upload) to a G9AppDiagnostic gateway. No platform code: the host reads the archive.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "src/index.ts",
|
|
7
|
+
"types": "src/index.ts",
|
|
8
|
+
"files": ["src"],
|
|
9
|
+
"scripts": { "test": "node --test test/*.test.ts" },
|
|
10
|
+
"license": "UNLICENSED",
|
|
11
|
+
"engines": { "node": ">=22.6" }
|
|
12
|
+
}
|
package/src/bytes.ts
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
// Base64 and UTF-8 without platform helpers: PrimJS (the Lynx engine) has neither atob nor TextDecoder everywhere.
|
|
2
|
+
|
|
3
|
+
const TABLE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
|
|
4
|
+
|
|
5
|
+
export function base64ToBytes(b64: string): Uint8Array {
|
|
6
|
+
const clean = b64.replace(/[^A-Za-z0-9+/]/g, '');
|
|
7
|
+
const out = new Uint8Array(Math.floor((clean.length * 3) / 4));
|
|
8
|
+
let bits = 0;
|
|
9
|
+
let value = 0;
|
|
10
|
+
let n = 0;
|
|
11
|
+
for (let i = 0; i < clean.length; i++) {
|
|
12
|
+
value = ((value << 6) | TABLE.indexOf(clean.charAt(i))) & 0xffffff;
|
|
13
|
+
bits += 6;
|
|
14
|
+
if (bits >= 8) {
|
|
15
|
+
bits -= 8;
|
|
16
|
+
out[n++] = (value >> bits) & 0xff;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
return out.subarray(0, n);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** UTF-8 → string; a broken sequence becomes U+FFFD (a log file cut mid-character at a chunk boundary). */
|
|
23
|
+
export function utf8Decode(bytes: Uint8Array): string {
|
|
24
|
+
let out = '';
|
|
25
|
+
let i = 0;
|
|
26
|
+
while (i < bytes.length) {
|
|
27
|
+
const b = bytes[i]!;
|
|
28
|
+
let cp = 0xfffd;
|
|
29
|
+
let len = 1;
|
|
30
|
+
if (b < 0x80) cp = b;
|
|
31
|
+
else if (b >= 0xc2 && b < 0xe0 && i + 1 < bytes.length && (bytes[i + 1]! & 0xc0) === 0x80) {
|
|
32
|
+
cp = ((b & 0x1f) << 6) | (bytes[i + 1]! & 0x3f);
|
|
33
|
+
len = 2;
|
|
34
|
+
} else if (b >= 0xe0 && b < 0xf0 && i + 2 < bytes.length && (bytes[i + 1]! & 0xc0) === 0x80 && (bytes[i + 2]! & 0xc0) === 0x80) {
|
|
35
|
+
cp = ((b & 0x0f) << 12) | ((bytes[i + 1]! & 0x3f) << 6) | (bytes[i + 2]! & 0x3f);
|
|
36
|
+
len = 3;
|
|
37
|
+
} else if (b >= 0xf0 && b < 0xf5 && i + 3 < bytes.length && (bytes[i + 1]! & 0xc0) === 0x80 && (bytes[i + 2]! & 0xc0) === 0x80 && (bytes[i + 3]! & 0xc0) === 0x80) {
|
|
38
|
+
cp = ((b & 0x07) << 18) | ((bytes[i + 1]! & 0x3f) << 12) | ((bytes[i + 2]! & 0x3f) << 6) | (bytes[i + 3]! & 0x3f);
|
|
39
|
+
len = 4;
|
|
40
|
+
}
|
|
41
|
+
if (cp > 0xffff) {
|
|
42
|
+
const c = cp - 0x10000;
|
|
43
|
+
out += String.fromCharCode(0xd800 + (c >> 10), 0xdc00 + (c & 0x3ff));
|
|
44
|
+
} else out += String.fromCharCode(cp);
|
|
45
|
+
i += len;
|
|
46
|
+
}
|
|
47
|
+
return out;
|
|
48
|
+
}
|
package/src/host.ts
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
// What the package needs from the platform it runs on — and nothing more. Structural on purpose: a Lynx app's own file,
|
|
2
|
+
// preference and HTTP layers satisfy these as they are, a Node tool passes `fs` and `fetch`, tests pass fakes. No member
|
|
3
|
+
// names a product; every product value (header names, folders, preference keys) is the app's configuration.
|
|
4
|
+
|
|
5
|
+
export type Unsubscribe = () => void;
|
|
6
|
+
|
|
7
|
+
export interface DiagnosticFileEntry {
|
|
8
|
+
readonly name: string;
|
|
9
|
+
readonly path: string;
|
|
10
|
+
readonly size: number;
|
|
11
|
+
readonly modifiedMs: number;
|
|
12
|
+
readonly dir: boolean;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** A zip entry: a file (or a folder, recursively) at `path`, or a text. */
|
|
16
|
+
export type DiagnosticZipEntry = { readonly name: string; readonly path: string } | { readonly name: string; readonly text: string };
|
|
17
|
+
|
|
18
|
+
/** The app's files (absolute paths). The archive, the hash and the zip are the app's: the package never reads bytes itself. */
|
|
19
|
+
export interface DiagnosticFiles {
|
|
20
|
+
writeText(path: string, text: string, append?: boolean): Promise<void>;
|
|
21
|
+
readText(path: string, maxBytes: number, fromEnd?: boolean): Promise<string>;
|
|
22
|
+
/** A folder's direct children; [] when it does not exist. */
|
|
23
|
+
list(dir: string): Promise<DiagnosticFileEntry[]>;
|
|
24
|
+
/** A file or a folder (recursive). Missing is fine. */
|
|
25
|
+
remove(path: string): Promise<void>;
|
|
26
|
+
copy(from: string, to: string): Promise<void>;
|
|
27
|
+
size(path: string): Promise<number>;
|
|
28
|
+
sha256(path: string): Promise<string>;
|
|
29
|
+
zip(out: string, entries: readonly DiagnosticZipEntry[]): Promise<{ readonly path: string; readonly bytes: number; readonly sha256: string }>;
|
|
30
|
+
zipReadText(zip: string, name: string, maxBytes: number): Promise<string>;
|
|
31
|
+
/** Base64 of up to `length` bytes at `offset` ('' at the end). */
|
|
32
|
+
readChunk(path: string, offset: number, length: number): Promise<string>;
|
|
33
|
+
/** Appends base64 bytes; resolves the new size. */
|
|
34
|
+
appendChunk(path: string, base64: string): Promise<number>;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Plain key/value preferences (strings; null removes). */
|
|
38
|
+
export interface DiagnosticPrefs {
|
|
39
|
+
get(key: string): string | null;
|
|
40
|
+
set(key: string, value: string | null): void;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Secrets (the gateway's device secret, a fleet password): the platform's secure storage. */
|
|
44
|
+
export interface DiagnosticSecrets {
|
|
45
|
+
get(key: string): Promise<string | null>;
|
|
46
|
+
set(key: string, value: string): Promise<void>;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** An HTTP response as the package reads it. */
|
|
50
|
+
export interface DiagnosticHttpResponse {
|
|
51
|
+
readonly status: number;
|
|
52
|
+
text(): Promise<string>;
|
|
53
|
+
/** A response header, when the platform's HTTP layer exposes them (lower-case names are fine). */
|
|
54
|
+
readonly headers?: { get(name: string): string | null } | Readonly<Record<string, string>>;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export interface DiagnosticHttpRequest {
|
|
58
|
+
readonly method: 'GET' | 'POST' | 'PUT';
|
|
59
|
+
readonly headers: Readonly<Record<string, string>>;
|
|
60
|
+
readonly body?: string | Uint8Array;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** `fetch`, or the platform's own HTTP call with the same shape. */
|
|
64
|
+
export type DiagnosticFetch = (url: string, init: DiagnosticHttpRequest) => Promise<DiagnosticHttpResponse>;
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* One HTTP request whose body is a byte range of a file, read natively (the chunk never crosses a JS bridge as base64).
|
|
68
|
+
* Every HTTP status resolves; only a transport failure rejects.
|
|
69
|
+
*/
|
|
70
|
+
export interface RangeRequest {
|
|
71
|
+
readonly url: string;
|
|
72
|
+
readonly method: 'PUT' | 'POST';
|
|
73
|
+
readonly path: string;
|
|
74
|
+
readonly offset: number;
|
|
75
|
+
readonly length: number;
|
|
76
|
+
readonly contentType?: string;
|
|
77
|
+
readonly headers: Readonly<Record<string, string>>;
|
|
78
|
+
readonly timeoutMs?: number;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export interface RangeResponse {
|
|
82
|
+
readonly status: number;
|
|
83
|
+
readonly body: string;
|
|
84
|
+
readonly headers: Readonly<Record<string, string>>;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
export type DiagnosticSendRange = (request: RangeRequest) => Promise<RangeResponse>;
|
|
88
|
+
|
|
89
|
+
/** The package's own lines in the app's log (never required). */
|
|
90
|
+
export interface DiagnosticLog {
|
|
91
|
+
log(level: 'debug' | 'info' | 'warn' | 'error', tag: string, message: string): void;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
export const silentLog: DiagnosticLog = { log: () => {} };
|
|
95
|
+
|
|
96
|
+
/** A header of a response, whatever shape the platform gives them in. */
|
|
97
|
+
export function headerOf(r: { readonly headers?: DiagnosticHttpResponse['headers'] }, name: string): string | null {
|
|
98
|
+
const h = r.headers;
|
|
99
|
+
if (!h) return null;
|
|
100
|
+
if (typeof (h as { get?: unknown }).get === 'function') return (h as { get(n: string): string | null }).get(name);
|
|
101
|
+
const map = h as Readonly<Record<string, string>>;
|
|
102
|
+
const lower = name.toLowerCase();
|
|
103
|
+
for (const k of Object.keys(map)) if (k.toLowerCase() === lower) return map[k] ?? null;
|
|
104
|
+
return null;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** Rejects with `step timed out` after `ms` (a half-open socket fails the step, not the queue). */
|
|
108
|
+
export function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
|
|
109
|
+
return new Promise<T>((resolve, reject) => {
|
|
110
|
+
const timer = setTimeout(() => reject(new Error('step timed out')), ms);
|
|
111
|
+
promise.then(
|
|
112
|
+
(v) => {
|
|
113
|
+
clearTimeout(timer);
|
|
114
|
+
resolve(v);
|
|
115
|
+
},
|
|
116
|
+
(e: unknown) => {
|
|
117
|
+
clearTimeout(timer);
|
|
118
|
+
reject(e);
|
|
119
|
+
},
|
|
120
|
+
);
|
|
121
|
+
});
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
export const errorText = (e: unknown): string => String((e as Error)?.message ?? e);
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
// @g9tm/app-diagnostic — the TypeScript twin of G9AppDiagnostic.Client and of the platform-free half of
|
|
2
|
+
// G9AppDiagnostic.Maui: the wire (shared/schema/*.schema.json), the tester-report upload, the tester mode's engine (drafts,
|
|
3
|
+
// captures, the recording state machine, the send rules, the outbox, the report list) and the live channel (Hello and
|
|
4
|
+
// its trust-on-first-use secret, consent, presence, logs, the operator's commands, bundles, restores). No platform code:
|
|
5
|
+
// the host passes its files, preferences, HTTP and SignalR client, and the platform package (@g9tm/app-diagnostic-lynx)
|
|
6
|
+
// its recorders and capture. Erasable TypeScript only (no enums, namespaces or parameter properties), so Node runs it
|
|
7
|
+
// with type stripping; ES2019 APIs only, so PrimJS (the Lynx engine) runs it too.
|
|
8
|
+
|
|
9
|
+
export * from './host.ts';
|
|
10
|
+
export * from './store.ts';
|
|
11
|
+
export * from './bytes.ts';
|
|
12
|
+
export * from './strings.ts';
|
|
13
|
+
export * from './wire.ts';
|
|
14
|
+
export * from './upload.ts';
|
|
15
|
+
export * from './recording.ts';
|
|
16
|
+
export * from './tester/model.ts';
|
|
17
|
+
export * from './tester/screen.ts';
|
|
18
|
+
export * from './tester/compose.ts';
|
|
19
|
+
export * from './tester/store.ts';
|
|
20
|
+
export * from './tester/outbox.ts';
|
|
21
|
+
export * from './tester/timeline.ts';
|
|
22
|
+
export * from './tester/gesture.ts';
|
|
23
|
+
export * from './tester/feed.ts';
|
|
24
|
+
export * from './tester/archive.ts';
|
|
25
|
+
export * from './tester/engine.ts';
|
|
26
|
+
export * from './live/models.ts';
|
|
27
|
+
export * from './live/bundle.ts';
|
|
28
|
+
export * from './live/upload.ts';
|
|
29
|
+
export * from './live/channel.ts';
|
|
30
|
+
export * from './live/handlers.ts';
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
// The bundle format (`g9-diagnostic-bundle/1`, schema x-bundle; G9AppDiagnostic.Maui BackupOrchestrator.ManifestAsync):
|
|
2
|
+
// every bundle — an operator's backup and the user's full report — has `bundle.json` at its root: what it is, which build
|
|
3
|
+
// made it, which scopes it holds. Everything else in the archive is the app's own layout. A reader (the gateway, an
|
|
4
|
+
// agent) starts at bundle.json; an old bundle without it is the app's legacy layout.
|
|
5
|
+
import type { BackupBuildRequestPayload } from './models.ts';
|
|
6
|
+
|
|
7
|
+
export const BUNDLE_FORMAT = 'g9-diagnostic-bundle/1';
|
|
8
|
+
export const BUNDLE_ENTRY = 'bundle.json';
|
|
9
|
+
|
|
10
|
+
export type BundleKind = 'backup' | 'full-report';
|
|
11
|
+
|
|
12
|
+
export interface BundleManifestInput {
|
|
13
|
+
readonly kind: BundleKind;
|
|
14
|
+
readonly product: string;
|
|
15
|
+
readonly appVersion: string;
|
|
16
|
+
readonly appBuild: string;
|
|
17
|
+
readonly branch?: string | null;
|
|
18
|
+
readonly commit?: string | null;
|
|
19
|
+
readonly platform: string;
|
|
20
|
+
readonly clientId: string;
|
|
21
|
+
readonly username?: string | null;
|
|
22
|
+
readonly note?: string | null;
|
|
23
|
+
readonly scopes: BackupBuildRequestPayload;
|
|
24
|
+
readonly now?: () => number;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export function bundleManifest(m: BundleManifestInput): string {
|
|
28
|
+
const s = m.scopes;
|
|
29
|
+
return JSON.stringify(
|
|
30
|
+
{
|
|
31
|
+
format: BUNDLE_FORMAT,
|
|
32
|
+
kind: m.kind,
|
|
33
|
+
product: m.product,
|
|
34
|
+
appVersion: m.appVersion,
|
|
35
|
+
appBuild: m.appBuild,
|
|
36
|
+
branch: m.branch ?? null,
|
|
37
|
+
commit: m.commit ?? null,
|
|
38
|
+
platform: m.platform,
|
|
39
|
+
clientId: m.clientId,
|
|
40
|
+
username: m.username ?? null,
|
|
41
|
+
createdUtc: new Date((m.now ?? Date.now)()).toISOString(),
|
|
42
|
+
note: m.note ?? null,
|
|
43
|
+
scopes: {
|
|
44
|
+
sqlite: s.includeSqlite,
|
|
45
|
+
geoDatabase: s.includeGeoDatabase,
|
|
46
|
+
attachments: s.includeAttachments,
|
|
47
|
+
logs: s.includeLogs,
|
|
48
|
+
preferences: s.includePreferences,
|
|
49
|
+
secureStorage: s.includeSecureStorage,
|
|
50
|
+
},
|
|
51
|
+
},
|
|
52
|
+
null,
|
|
53
|
+
2,
|
|
54
|
+
);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** `<prefix>-backup-20261101-142233.zip` / `<prefix>-report-…` (UTC). */
|
|
58
|
+
export function bundleFileName(prefix: string, kind: BundleKind, ms: number): string {
|
|
59
|
+
const d = new Date(ms);
|
|
60
|
+
const p = (n: number) => String(n).padStart(2, '0');
|
|
61
|
+
const stamp = `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}-${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}`;
|
|
62
|
+
return `${prefix}-${kind === 'backup' ? 'backup' : 'report'}-${stamp}.zip`;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** The scopes an operator asked for, every flag present (an older console sends fewer). */
|
|
66
|
+
export function normalizeScopes(raw: Partial<BackupBuildRequestPayload> | null | undefined): BackupBuildRequestPayload {
|
|
67
|
+
const r = raw ?? {};
|
|
68
|
+
return {
|
|
69
|
+
includeSqlite: r.includeSqlite !== false,
|
|
70
|
+
includeGeoDatabase: r.includeGeoDatabase === true,
|
|
71
|
+
includeAttachments: r.includeAttachments === true,
|
|
72
|
+
includeLogs: r.includeLogs !== false,
|
|
73
|
+
includePreferences: r.includePreferences === true,
|
|
74
|
+
includeSecureStorage: r.includeSecureStorage === true,
|
|
75
|
+
includeErrors: r.includeErrors === true,
|
|
76
|
+
};
|
|
77
|
+
}
|