@windsland52/maa-log-tools 1.0.0 → 1.1.1

package/README.md

@@ -9,6 +9,7 @@ Node tools package for Maa log analysis.
   - `analyzeZipBuffer`
   - `analyzeZipFile`
   - `analyzeDirectory`
+- Extract MaaFramework runtime sessions and version evidence from core Logger headers
 - Provide CLI entry (`mla-log-tools`)
 
 `analyzeLogContent` is delegated to `@windsland52/maa-log-runtime` with a local parser/statistics adapter.
@@ -21,6 +22,9 @@ The concrete adapter is provided by `@windsland52/maa-log-adapter`.
   - `analyzeZipBuffer`
   - `analyzeZipFile`
   - `analyzeDirectory`
+  - `loadFrameworkLogSources`
+  - `extractFrameworkSessions`
+  - `resolveFrameworkSessionForTimestamp`
   - `DEFAULT_CORE_PARSE_OPTIONS`
 - `@windsland52/maa-log-tools/node-input`
   - Node file/zip/folder extraction helpers
@@ -45,7 +49,21 @@ When `focus` is provided, the helpers scan candidate primary and history log fil
 ## CLI
 
 ```bash
-pnpm kernel:cli <path> [--pretty] [--no-events]
+pnpm kernel:cli <path> [--pretty] [--no-events] [--preflight]
 ```
 
 `<path>` can be a log file, a zip file, or a log directory.
+
+The `--preflight` option emits a compact `mla-preflight/v1` compatibility result. It exits
+with 0 when Notify events produce at least one task lifecycle, 3 for an unsupported log format,
+and 2 when the input contains no analyzable log content.
+
+Preflight also emits `frameworkVersionSummary` and `frameworkSessions`. A session starts at an
+exact `[Logger] MAA Process Start` header and gets its version only from `[Logger] Version ...`
+evidence in that session. Every boundary and version occurrence retains its source reference and
+line number. Multiple versions are preserved instead of collapsed, conflicts produce warnings,
+and content before a process-start marker is explicitly marked as a partial file segment.
+
+Use the session containing the relevant failure timestamp when selecting version-matched source.
+`resolveFrameworkSessionForTimestamp` returns a session only when exactly one resolved,
+process-start-bounded interval contains the timestamp; otherwise it returns `null`.

package/dist/cli.d.ts

@@ -1,2 +1,20 @@
 #!/usr/bin/env node
-export {};
+import type { KernelOutput } from '@windsland52/maa-log-kernel/protocol';
+import { type FrameworkSession, type FrameworkSessionExtraction, type FrameworkVersionSummary } from './frameworkVersion.js';
+export declare const MLA_PREFLIGHT_SCHEMA_VERSION = "mla-preflight/v1";
+export type PreflightReason = 'notify_events_parsed' | 'empty_log' | 'no_notify_events' | 'no_task_lifecycle' | 'no_analyzable_content';
+export interface PreflightOutput {
+    schemaVersion: typeof MLA_PREFLIGHT_SCHEMA_VERSION;
+    status: 'supported' | 'unsupported';
+    reason: PreflightReason;
+    parserVersion: string | null;
+    taskCount: number;
+    eventCount: number;
+    nodeStatisticCount: number;
+    recognitionStatisticCount: number;
+    frameworkVersionSummary: FrameworkVersionSummary;
+    frameworkSessions: FrameworkSession[];
+    warnings: string[];
+}
+export declare const buildPreflightOutput: (output: KernelOutput | null, framework?: FrameworkSessionExtraction) => PreflightOutput;
+export declare const main: () => Promise<void>;

package/dist/cli.js

@@ -2,16 +2,19 @@
 import { stat } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { loadFrameworkLogSources } from './frameworkInput.js';
+import { extractFrameworkSessions, } from './frameworkVersion.js';
 import { readNodeTextFileContent } from './nodeInput.js';
 import { analyzeLogContent, analyzeDirectory, analyzeZipFile, } from './index.js';
 const printUsage = () => {
-    console.error('Usage: mla-log-tools <path> [--pretty] [--no-events]');
+    console.error('Usage: mla-log-tools <path> [--pretty] [--no-events] [--preflight]');
     console.error('  <path>: log file path, zip path, or log directory path');
 };
 const parseArgs = (argv) => {
     let targetPath = null;
     let pretty = false;
     let noEvents = false;
+    let preflight = false;
     for (const arg of argv) {
         if (arg === '--pretty') {
             pretty = true;
@@ -21,6 +24,10 @@ const parseArgs = (argv) => {
             noEvents = true;
             continue;
         }
+        if (arg === '--preflight') {
+            preflight = true;
+            continue;
+        }
         if (arg === '--help' || arg === '-h') {
             printUsage();
             process.exit(0);
@@ -29,7 +36,7 @@ const parseArgs = (argv) => {
             targetPath = arg;
         }
     }
-    return { targetPath, pretty, noEvents };
+    return { targetPath, pretty, noEvents, preflight };
 };
 const renderOutput = (output, pretty, noEvents) => {
     const payload = noEvents
@@ -37,14 +44,60 @@ const renderOutput = (output, pretty, noEvents) => {
         : output;
     return JSON.stringify(payload, null, pretty ? 2 : 0);
 };
-const main = async () => {
-    const { targetPath, pretty, noEvents } = parseArgs(process.argv.slice(2));
+export const MLA_PREFLIGHT_SCHEMA_VERSION = 'mla-preflight/v1';
+const EMPTY_FRAMEWORK_EXTRACTION = {
+    sessions: [],
+    summary: { status: 'none', versions: [] },
+    warnings: [],
+};
+export const buildPreflightOutput = (output, framework = EMPTY_FRAMEWORK_EXTRACTION) => {
+    if (!output) {
+        return {
+            schemaVersion: MLA_PREFLIGHT_SCHEMA_VERSION,
+            status: 'unsupported',
+            reason: 'no_analyzable_content',
+            parserVersion: null,
+            taskCount: 0,
+            eventCount: 0,
+            nodeStatisticCount: 0,
+            recognitionStatisticCount: 0,
+            frameworkVersionSummary: framework.summary,
+            frameworkSessions: framework.sessions,
+            warnings: framework.warnings,
+        };
+    }
+    const reason = output.events.length > 0
+        ? output.tasks.length > 0
+            ? 'notify_events_parsed'
+            : 'no_task_lifecycle'
+        : output.warnings.includes('Empty log content.')
+            ? 'empty_log'
+            : 'no_notify_events';
+    return {
+        schemaVersion: MLA_PREFLIGHT_SCHEMA_VERSION,
+        status: reason === 'notify_events_parsed' ? 'supported' : 'unsupported',
+        reason,
+        parserVersion: output.meta.parserVersion,
+        taskCount: output.tasks.length,
+        eventCount: output.events.length,
+        nodeStatisticCount: output.stats.nodes.length,
+        recognitionStatisticCount: output.stats.recognitionActions.length,
+        frameworkVersionSummary: framework.summary,
+        frameworkSessions: framework.sessions,
+        warnings: [...output.warnings, ...framework.warnings],
+    };
+};
+export const main = async () => {
+    const { targetPath, pretty, noEvents, preflight, } = parseArgs(process.argv.slice(2));
     if (!targetPath) {
         printUsage();
         process.exit(1);
     }
     const resolvedPath = path.resolve(targetPath);
     const targetStat = await stat(resolvedPath);
+    const framework = preflight
+        ? extractFrameworkSessions(await loadFrameworkLogSources(resolvedPath))
+        : EMPTY_FRAMEWORK_EXTRACTION;
     let result = null;
     if (targetStat.isDirectory()) {
         result = await analyzeDirectory({ directoryPath: resolvedPath });
@@ -57,9 +110,22 @@ const main = async () => {
         result = await analyzeLogContent({ content });
     }
     if (!result) {
+        if (preflight) {
+            process.stdout.write(JSON.stringify(buildPreflightOutput(null, framework), null, pretty ? 2 : 0));
+            process.stdout.write('\n');
+        }
         console.error('No analyzable log content found in the provided path.');
         process.exit(2);
     }
+    if (preflight) {
+        const output = buildPreflightOutput(result, framework);
+        process.stdout.write(JSON.stringify(output, null, pretty ? 2 : 0));
+        process.stdout.write('\n');
+        if (output.status === 'unsupported') {
+            process.exit(3);
+        }
+        return;
+    }
     process.stdout.write(renderOutput(result, pretty, noEvents));
     process.stdout.write('\n');
 };

package/dist/frameworkInput.d.ts

@@ -0,0 +1,2 @@
+import type { FrameworkLogSource } from './frameworkVersion.js';
+export declare const loadFrameworkLogSources: (targetPath: string) => Promise<FrameworkLogSource[]>;

package/dist/frameworkInput.js

@@ -0,0 +1,124 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { unzipSync } from 'fflate';
+import { readNodeTextFileContent } from './nodeInput.js';
+const MAIN_LOG_NAMES = ['maafw.log', 'maa.log'];
+const BAK_LOG_NAMES = ['maafw.bak.log', 'maa.bak.log'];
+const toPosixPath = (value) => value.replace(/\\/g, '/');
+const decodeBytes = (bytes) => {
+    for (const encoding of ['utf-8', 'gbk', 'gb18030', 'gb2312']) {
+        try {
+            return new TextDecoder(encoding, { fatal: true }).decode(bytes);
+        }
+        catch {
+            continue;
+        }
+    }
+    return new TextDecoder('utf-8').decode(bytes);
+};
+const findEntryPath = (paths, target) => {
+    const normalizedTarget = toPosixPath(target).toLowerCase();
+    return paths.find((candidate) => toPosixPath(candidate).toLowerCase() === normalizedTarget) ?? null;
+};
+const findZipBasePath = (paths) => {
+    for (const candidate of paths) {
+        const normalized = toPosixPath(candidate);
+        const lowerName = path.posix.basename(normalized).toLowerCase();
+        if (!MAIN_LOG_NAMES.includes(lowerName))
+            continue;
+        const parent = path.posix.dirname(normalized);
+        return parent === '.' ? '' : parent;
+    }
+    return null;
+};
+const loadZipSources = async (zipPath) => {
+    const files = unzipSync(new Uint8Array(await readFile(zipPath)));
+    const paths = Object.keys(files);
+    const basePath = findZipBasePath(paths);
+    if (basePath == null)
+        return [];
+    const selected = [];
+    for (const name of [...BAK_LOG_NAMES, ...MAIN_LOG_NAMES]) {
+        const candidate = findEntryPath(paths, basePath ? `${basePath}/${name}` : name);
+        if (candidate && !selected.includes(candidate))
+            selected.push(candidate);
+        if (candidate && MAIN_LOG_NAMES.includes(name))
+            break;
+    }
+    return selected.flatMap((entryPath) => {
+        const bytes = files[entryPath];
+        if (!bytes)
+            return [];
+        const normalized = toPosixPath(entryPath);
+        return [{
+                path: normalized,
+                name: path.posix.basename(normalized),
+                content: decodeBytes(bytes),
+                reference: `zip:${toPosixPath(zipPath)}#${normalized}`,
+            }];
+    });
+};
+const pathExists = async (candidate) => {
+    try {
+        await stat(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const findDebugDirectory = async (root) => {
+    for (const name of MAIN_LOG_NAMES) {
+        if (await pathExists(path.join(root, name)))
+            return root;
+    }
+    const directDebug = path.join(root, 'debug');
+    for (const name of MAIN_LOG_NAMES) {
+        if (await pathExists(path.join(directDebug, name)))
+            return directDebug;
+    }
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const found = await findDebugDirectory(path.join(root, entry.name));
+        if (found)
+            return found;
+    }
+    return null;
+};
+const firstExisting = async (root, names) => {
+    for (const name of names) {
+        const candidate = path.join(root, name);
+        if (await pathExists(candidate))
+            return candidate;
+    }
+    return null;
+};
+const loadDirectorySources = async (directoryPath) => {
+    const debugPath = await findDebugDirectory(directoryPath);
+    if (!debugPath)
+        return [];
+    const selected = [
+        await firstExisting(debugPath, BAK_LOG_NAMES),
+        await firstExisting(debugPath, MAIN_LOG_NAMES),
+    ].filter((candidate) => candidate != null);
+    return Promise.all(selected.map(async (absolutePath) => ({
+        path: toPosixPath(path.relative(debugPath, absolutePath)),
+        name: path.basename(absolutePath),
+        content: await readNodeTextFileContent(absolutePath),
+        reference: `file:${toPosixPath(absolutePath)}`,
+    })));
+};
+export const loadFrameworkLogSources = async (targetPath) => {
+    const targetStat = await stat(targetPath);
+    if (targetStat.isDirectory())
+        return loadDirectorySources(targetPath);
+    if (targetPath.toLowerCase().endsWith('.zip'))
+        return loadZipSources(targetPath);
+    return [{
+            path: toPosixPath(targetPath),
+            name: path.basename(targetPath),
+            content: await readNodeTextFileContent(targetPath),
+            reference: `file:${toPosixPath(targetPath)}`,
+        }];
+};

package/dist/frameworkVersion.d.ts

@@ -0,0 +1,36 @@
+export interface FrameworkLogSource {
+    path: string;
+    name: string;
+    content: string;
+    reference: string;
+}
+export interface FrameworkLogPosition {
+    source: string;
+    path: string;
+    line: number;
+    timestamp: string | null;
+}
+export interface FrameworkVersionEvidence extends FrameworkLogPosition {
+    version: string;
+}
+export interface FrameworkSession {
+    sessionId: string;
+    startKind: 'process_start' | 'partial_file';
+    status: 'resolved' | 'missing_version' | 'conflict';
+    version: string | null;
+    versions: string[];
+    start: FrameworkLogPosition;
+    end: FrameworkLogPosition;
+    versionEvidence: FrameworkVersionEvidence[];
+}
+export interface FrameworkVersionSummary {
+    status: 'none' | 'single' | 'multiple' | 'conflict';
+    versions: string[];
+}
+export interface FrameworkSessionExtraction {
+    sessions: FrameworkSession[];
+    summary: FrameworkVersionSummary;
+    warnings: string[];
+}
+export declare const extractFrameworkSessions: (sources: readonly FrameworkLogSource[]) => FrameworkSessionExtraction;
+export declare const resolveFrameworkSessionForTimestamp: (extraction: FrameworkSessionExtraction, timestamp: string) => FrameworkSession | null;

package/dist/frameworkVersion.js

@@ -0,0 +1,126 @@
+const PROCESS_START_PATTERN = /\]\[Logger\]\s+MAA Process Start(?:\s|$)/;
+const VERSION_PATTERN = /\]\[Logger\]\s+Version\s+(v\d+(?:\.\d+)+(?:[-+][0-9A-Za-z.-]+)?)(?:\s|$)/;
+const TIMESTAMP_PATTERN = /^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(?:\.\d{1,3})?)\]/;
+const splitLines = (content) => {
+    const lines = content.split(/\r?\n/);
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+};
+const timestampOf = (line) => {
+    if (!line)
+        return null;
+    return line.match(TIMESTAMP_PATTERN)?.[1] ?? null;
+};
+const position = (source, lines, lineIndex) => ({
+    source: source.reference,
+    path: source.path,
+    line: lineIndex + 1,
+    timestamp: timestampOf(lines[lineIndex]),
+});
+const findTimestamp = (lines, startIndex, endIndex, direction) => {
+    for (let index = direction === 1 ? startIndex : endIndex; index >= startIndex && index <= endIndex; index += direction) {
+        const timestamp = timestampOf(lines[index]);
+        if (timestamp)
+            return timestamp;
+    }
+    return null;
+};
+const buildSession = (source, lines, startIndex, endIndex, startKind, sessionIndex) => {
+    const versionEvidence = [];
+    for (let index = startIndex; index <= endIndex; index += 1) {
+        const match = lines[index]?.match(VERSION_PATTERN);
+        const version = match?.[1];
+        if (!version)
+            continue;
+        versionEvidence.push({
+            ...position(source, lines, index),
+            version,
+        });
+    }
+    const versions = [...new Set(versionEvidence.map((item) => item.version))];
+    const status = versions.length === 0
+        ? 'missing_version'
+        : versions.length === 1
+            ? 'resolved'
+            : 'conflict';
+    const start = position(source, lines, startIndex);
+    start.timestamp = findTimestamp(lines, startIndex, endIndex, 1);
+    const end = position(source, lines, endIndex);
+    end.timestamp = findTimestamp(lines, startIndex, endIndex, -1);
+    return {
+        sessionId: `framework-session-${sessionIndex}`,
+        startKind,
+        status,
+        version: status === 'resolved' ? (versions[0] ?? null) : null,
+        versions,
+        start,
+        end,
+        versionEvidence,
+    };
+};
+export const extractFrameworkSessions = (sources) => {
+    const sessions = [];
+    for (const source of sources) {
+        const lines = splitLines(source.content);
+        if (lines.length === 0)
+            continue;
+        const processStarts = [];
+        for (let index = 0; index < lines.length; index += 1) {
+            if (PROCESS_START_PATTERN.test(lines[index] ?? ''))
+                processStarts.push(index);
+        }
+        const firstProcessStart = processStarts[0];
+        const hasPartialPrefix = firstProcessStart != null
+            && firstProcessStart > 0
+            && lines.slice(0, firstProcessStart).some((line) => (VERSION_PATTERN.test(line) || line.includes('!!!OnEventNotify!!!')));
+        const boundaries = processStarts.length === 0 || hasPartialPrefix
+            ? [0, ...processStarts]
+            : processStarts;
+        for (let index = 0; index < boundaries.length; index += 1) {
+            const startIndex = boundaries[index];
+            if (startIndex == null)
+                continue;
+            const nextStart = boundaries[index + 1];
+            const endIndex = nextStart == null ? lines.length - 1 : nextStart - 1;
+            const isProcessStart = processStarts.includes(startIndex);
+            sessions.push(buildSession(source, lines, startIndex, endIndex, isProcessStart ? 'process_start' : 'partial_file', sessions.length + 1));
+        }
+    }
+    const versions = [...new Set(sessions.flatMap((session) => session.versions))];
+    const hasConflict = sessions.some((session) => session.status === 'conflict');
+    const summary = {
+        status: hasConflict
+            ? 'conflict'
+            : versions.length === 0
+                ? 'none'
+                : versions.length === 1
+                    ? 'single'
+                    : 'multiple',
+        versions,
+    };
+    const warnings = [];
+    if (summary.status === 'multiple') {
+        warnings.push(`Multiple MaaFramework versions found in selected logs: ${versions.join(', ')}.`);
+    }
+    if (summary.status === 'conflict') {
+        warnings.push('Conflicting MaaFramework version headers found within a runtime session.');
+    }
+    if (sessions.some((session) => session.startKind === 'partial_file')) {
+        warnings.push('Some core log content starts without a MAA Process Start marker; its session boundary is partial.');
+    }
+    if (sessions.some((session) => session.status === 'missing_version')) {
+        warnings.push('Some MaaFramework runtime sessions do not contain a Logger version header.');
+    }
+    return { sessions, summary, warnings };
+};
+export const resolveFrameworkSessionForTimestamp = (extraction, timestamp) => {
+    const candidates = extraction.sessions.filter((session) => {
+        if (session.status !== 'resolved' || session.startKind !== 'process_start')
+            return false;
+        const start = session.start.timestamp;
+        const end = session.end.timestamp;
+        return start != null && end != null && timestamp >= start && timestamp <= end;
+    });
+    return candidates.length === 1 ? (candidates[0] ?? null) : null;
+};

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { KernelOutput } from '@windsland52/maa-log-kernel';
 import type { AnalyzeLogContentInput, ParseFileOptions } from '@windsland52/maa-log-runtime';
-import { type LogBundleFocus } from './nodeInput';
+import { type LogBundleFocus } from './nodeInput.js';
 type ParseOptions = ParseFileOptions;
 export interface AnalyzeZipBufferInput {
     zipData: Uint8Array;
@@ -27,4 +27,6 @@ export declare const analyzeZipFile: (input: AnalyzeZipFileInput) => Promise<Ker
 export declare const analyzeDirectory: (input: AnalyzeDirectoryInput) => Promise<KernelOutput | null>;
 export { DEFAULT_CORE_PARSE_OPTIONS, } from '@windsland52/maa-log-runtime';
 export type { AnalyzeLogContentInput, ParseFileOptions } from '@windsland52/maa-log-runtime';
-export * from './nodeInput';
+export * from './nodeInput.js';
+export * from './frameworkInput.js';
+export * from './frameworkVersion.js';

package/dist/index.js

@@ -54,3 +54,5 @@ export const analyzeDirectory = async (input) => {
 };
 export { DEFAULT_CORE_PARSE_OPTIONS, } from '@windsland52/maa-log-runtime';
 export * from './nodeInput.js';
+export * from './frameworkInput.js';
+export * from './frameworkVersion.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windsland52/maa-log-tools",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "type": "module",
   "private": false,
   "bin": {
@@ -42,10 +42,10 @@
   },
   "dependencies": {
     "fflate": "^0.8.2",
-    "@windsland52/maa-log-adapter": "1.0.0",
-    "@windsland52/maa-log-kernel": "1.0.0",
-    "@windsland52/maa-log-runtime": "1.0.0",
-    "@windsland52/maa-log-parser": "1.0.0"
+    "@windsland52/maa-log-adapter": "1.0.1",
+    "@windsland52/maa-log-parser": "1.0.1",
+    "@windsland52/maa-log-runtime": "1.0.1",
+    "@windsland52/maa-log-kernel": "1.0.1"
   },
   "engines": {
     "node": ">=24.0.0"