tks18/personal-finance-etl

[
  {
    "status": "PASS",
    "details": {
      "working": false,
      "argv": [
        "<host-path>",
        "--help"
      ],
      "kind": "cli",
      "returncode": 0,
      "stdout": "usage: shan-fin [-h] {cli,tkinter} ...\n\nPersonal Finance Quant Engine\n\npositional arguments:\n  {cli,tkinter}  Frontend to launch\n    cli          Launch the terminal CLI\n    tkinter      Launch the Desktop GUI\n\noptions:\n  -h, --help     show this help message and exit",
      "stderr": "",
      "needs_credentials": false,
      "needs_browser": false,
      "scope": "partial: install"
    },
    "check": "install",
    "optional": false
  },
  {
    "status": "FAIL",
    "details": {
      "working": false,
      "argv": [
        "<host-path>",
        "cli",
        "--help"
      ],
      "kind": "cli",
      "returncode": 0,
      "stdout": "usage: shan-fin cli [-h] [--config CONFIG] [--rules RULES] [--snapshot]\n                    [--restore RESTORE] [--auto] [--cron] [--docs]\n\noptions:\n  -h, --help         show this help message and exit\n  --config CONFIG    Path to config.toml\n  --rules RULES      Path to rules.toml\n  --snapshot         Snapshot the DuckDB database instead of running ETL\n  --restore RESTORE  Path to backup zip file to restore (requires --config)\n  --auto             Bypass confirmation prompts and automatically start the\n                     pipeline\n  --cron             Run completely unattended and exit immediately after\n[excerpt truncated]",
      "stderr": "",
      "needs_credentials": false,
      "needs_browser": false,
      "blocker": "wrong subcommand or usage-only response: {\"returncode\": 0, \"stdout\": \"usage: shan-fin cli [-h] [--config CONFIG] [--rules RULES] [--snapshot]\\n                    [--restore RESTORE] [--auto] [--cron] [--docs]\\n\\noptions:\\n  -h, --help         show this help message and exit\\n  --config CONFIG    Path to config.toml\\n  --rules RULES      Path to rules.toml\\n  --snapshot         Snapshot the DuckDB database instead of running ETL\\n  --restore RESTORE  Path to backup zip file to restore (requires --config)\\n  --auto             Bypass confirmation prompts and automatically start the\\n                     pipeline\\n  --cron             Run completely unattended and exit immediately after\\n                     completion (implies --auto)\\n  --docs             Open the documentation and guides window, then exit\\n\", \"stderr\": \"\", \"needs_credentials\": false, \"needs_browser\": false}"
    },
    "check": "start",
    "optional": false
  }
]

Installed package launcher verified (shan-fin --help, shan-fin cli --help). Attempted documented pipeline run: shan-fin cli --config ... --rules ... --auto --cron; it halts at config validation because user-owned inputs are absent.

cd <host-path> && ls -la && git log --oneline -1 2>/dev/null; cat README.md 2>/dev/null | head -300
cd <host-path> && ls -la .coldpass 2>/dev/null; cat .coldpass/*.json 2>/dev/null | head -50; ls <host-path> 2>/dev/null
cd <host-path> && grep -n -i "quick start\|^## \|^### \|uv \|pip install\|python -m\|personal-finance\|\bpfe\b\|cli" README.md | sed -n '1,200p' | grep -v "^[0-9]*:  *- \[" | head -150
cd <host-path> && sed -n 880,920p README.md; echo ----; cat docs/getting-started/quick-start.md 2>/dev/null | head -200; echo ----; cat docs/getting-started/cli-and-desktop.md 2>/dev/null | head -150
cd <host-path> && cat docs/getting-started/installation.md | head -150; echo ----; ls .github/workflows scripts tests docs; echo ----; grep -n "run:" -A3 .github/workflows/*.yml | head -120
cd <host-path> && python3 --version; which uv pip3 pip; cat .python-version; grep -n "uv\|python" docs/getting-started/*.md | grep -i "uv sync\|uv run\|pip install" | head; echo ---; cat tests/config.toml | head -40; echo ---; env | grep -i "proxy\|CDP"
cd <host-path> && (command -v curl >/dev/null || sudo apt-get install -y curl >/dev/null 2>&1); curl -LsSf https://astral.sh/uv/install.sh | sh 2>&1 | tail -3; export PATH="$HOME/.local/bin:$PATH"; uv --version && uv python install 3.13 2>&1 | tail -3
cd <host-path> && export PATH="$HOME/.local/bin:$PATH" NODE_USE_ENV_PROXY=1 && uv sync 2>&1 | tail -15; ls -d .venv && .venv/bin/shan-fin --help 2>&1 | head -30
cd <host-path> && head -60 tests/run_headless.py; echo ----; cat tests/financial_rules.toml | head -20; echo ----; grep -rn "synthetic\|sample data\|demo" README.md docs --include=*.md | head
cd <host-path> && export PATH="$HOME/.local/bin:$PATH"; timeout 60 .venv/bin/shan-fin cli --docs 2>&1 | tail -5; echo "rc=$?"; echo ----; timeout 60 .venv/bin/shan-fin cli --config tests/config.toml --rules tests/financial_rules.toml --auto --cron 2>&1 | tail -8; echo "rc=${PIPESTATUS[0]}"
cd <host-path> && grep -n "checks\|\"check\"\|'check'\|def _validate\|--validate" <host-path> | head -60
sed -n 75,100p <host-path>; echo ....; sed -n 385,460p <host-path>; echo ....; sed -n 520,560p <host-path>
cd <host-path> && mkdir -p .coldpass && cat > .coldpass/probe.json <<'EOF'
{"checks":[
 {"check":"install","kind":"cli","argv":["<host-path>","expected_text":"Personal Finance Quant Engine"},
 {"check":"start","kind":"cli","argv":["<host-path>","expected_text":"--config"}
]}
EOF
cat > .coldpass/report.json <<'EOF'
{"outcome":"blocked",
 "operation":"Installed package launcher verified (shan-fin --help, shan-fin cli --help). Attempted documented pipeline run: shan-fin cli --config ... --rules ... --auto --cron; it halts at config validation because user-owned inputs are absent.",
 "operation_scope":"Partial: install and launcher start only. The ETL operation (discover, synchronize, transform, publish Gold/Meta) is not exercised; it requires the user's own config.toml, financial_rules.toml, source DB, statements folder and seven reference CSVs. Desktop (shan-fin / shan-fin-gui / shan-fin cli --docs) needs a GTK or Qt display for pywebview and is not runnable in this headless guest.",
 "steps":["Read README.md and docs/getting-started/installation.md (uv sync documented)",
  "Installed uv 0.13.1 via https://astral.sh/uv/install.sh",
  "uv python install 3.13 (project .python-version is 3.13)",
  "NODE_USE_ENV_PROXY=1 uv sync (created .venv, 3.13.16)",
  ".venv/bin/shan-fin --help (launcher lists cli and tkinter)",
  ".venv/bin/shan-fin cli --help",
  "Read docs/getting-started/quick-start.md; attempted .venv/bin/shan-fin cli --config tests/config.toml --rules tests/financial_rules.toml --auto --cron: validation reports missing paths (placeholder '...' values) and halts; exit 0"],
 "deviations":["Guest had no uv; installed it with the astral.sh installer before uv sync (installation.md names uv as the workflow).",
  "quick-start.md step 1-4 cannot run: needs user-owned config.toml, financial_rules.toml and source data. Repo tests/config.toml uses placeholder '...' paths, so it was not usable and no synthetic financial data was created.",
  "shan-fin cli --docs fails under headless guest: pywebview needs QT or GTK Python bindings (WebViewException)."],
 "stuck_step":"README Quick Start, steps 1-4 (docs/getting-started/quick-start.md): run the ETL with config.toml and financial_rules.toml",
 "main_blocker":"Prerequisite, not a repo defect: the ETL needs the user's own financial source files, config and rules, none of which exist in the guest. Config validation fails as designed.",
 "suggested_fix":"Provide a real config.toml with absolute Linux paths to SOURCE_DB_FOLDER, STATEMENTS_FOLDER and the seven CSVs, plus a financial_rules.toml, then run: .venv/bin/shan-fin cli --config /abs/config.toml --rules /abs/financial_rules.toml --auto --cron. For the desktop check, install GTK/PyGObject or Qt bindings in the guest.",
 "fault_owner":"prerequisite"}
EOF
<env-var>=<host-path> python3 -I <host-path> --validate; echo rc=$?; python3 -m json.tool .coldpass/report.json >/dev/null && echo report-ok
cd <host-path> && .venv/bin/shan-fin cli --help | grep -c -- "--config"; .venv/bin/shan-fin --help | grep -c "Personal Finance Quant Engine"; ls .coldpass