🧾 Synticore Website Compiler - Log Guide

🎯 Purpose

This page explains where logs are written, what each log is for, and a practical workflow for debugging build/GUI/setup issues.

🗂️ Log Locations

🧰 Compiler-Root Logs

Located in <compiler-root>/_log/:

• _log/gulpfile.log - compiler/gulp pipeline log stream
• _log/gui.log - GUI runtime log stream
• _log/setup.log - setup script log stream (setup.py)

📁 Project-Root Logs

Located in <project-root>/_log/:

• _log/task_<task-name>.log - per-task execution logs
  • example: _log/task_build.log
  • example: _log/task_watch.log
  • example: _log/task_project_update_full.log

The gulp pipeline resolves per-task log names from current task name.

🧭 Which Log To Read First

❗ Build/Task Failures

1. <project>/_log/task_<task>.log
2. <compiler>/_log/gulpfile.log

🖥️ GUI Issues

1. <compiler>/_log/gui.log
2. <compiler>/_log/gulpfile.log (if issue occurs while launching task)

🧰 Setup Issues

1. <compiler>/_log/setup.log

🧪 Common Debugging Workflows

🧵 A. Reproduce + Tail Task Log (PowerShell)

Get-Content .\\example\\min\\_log\\task_build.log -Tail 200

For live tail while task runs:

Get-Content .\\example\\min\\_log\\task_watch.log -Wait

✅ B. Run Baseline Diagnostics

npm run gulp about
npm run gulp build

Then inspect project task log.

🧭 C. Migration Diagnostics

npm run gulp project_update_full

Then inspect:

• <project>/_log/task_project_update_full.log
• <compiler>/_log/gulpfile.log

🧠 What Log Messages Usually Indicate

• Path errors: invalid project selection, missing file/folder, bad relative path.
• Config errors: malformed JSON, invalid key shape, legacy key mismatch.
• Toolchain errors: missing Node/Python dependency, binary not found.
• Cache behavior: stale cache entries, cache upgrades/rewrites, rebuild triggers.
• Dependency graph behavior: referenced-file changes/deletes and dependency-triggered follow-up tasks in watch mode.
• Migration behavior: version checks, moved files, key moves, token rewrite steps.

🧹 Log Retention And Cleanup

Safe to delete any time:

• <compiler-root>/_log/*
• <project-root>/_log/*

Logs will be recreated on next GUI/task/setup run.

📦 Recommended Incident Report Bundle

When sharing an issue, include:

1. Command run (exact)
2. Selected project path
3. <project>/_log/task_<task>.log
4. <compiler>/_log/gulpfile.log
5. config.json excerpt around affected option namespace

This usually reduces troubleshooting turnaround dramatically.