MarkPhamm/quickdbd-cli

Review signals: 1 known vulnerability.

Reviewed as expected for a test run: attempted writes that failed, so nothing was written.

OSV reports a known vulnerability in this dependency version. @azure/msal-node

OSV scanned supported lockfiles; unpinned dependencies and unsupported formats are outside this check.

A short run cannot establish that code is safe.

Connections show IP addresses; proxies can hide the final hostname.

Tracing covers dispatched commands and their children, not the whole OS; guest root can interfere with tracing.

Full safety evidence →

• qdbd check validates a schema file: Real input produced the expected result: No errors found

  Source: A file that passes `qdbd check --strict` pastes into QuickDBD unchanged.

  Input: examples/quickdbd-sample.txt

  Expected: No errors found

  Command: <guest-path> check --strict examples/quickdbd-sample.txt

  Observed: No errors found. Good job!

• qdbd build writes one self-contained HTML diagram: Real input produced the expected result: 7 tables, 7 relationships

  Source: qdbd build schema.txt -o schema.html

  Input: examples/quickdbd-sample.txt

  Expected: writes sample HTML page with 7 tables

  Command: <guest-path> build examples/quickdbd-sample.txt -o <guest-path>

  Observed: …7 tables, 7 relationships)

• qdbd mcp serves schema tables to AI agents: Real input produced the expected result: Customer

  Source: `qdbd mcp` gives Claude, Copilot and Cursor your schema as tools: tables and columns

  Input: {"tool": "list_tables", "arguments": {}}

  Expected: Customer table listed

  Command: <guest-path> mcp examples/quickdbd-sample.txt tools/call {"tool": "list_tables", "arguments": {}}

  Observed: …Customer (as c): 5 columns\n- Order (as o): 4 columns — Every order belongs to one customer.\n- OrderLine: 4 columns\n- Product Catalog (as cat): 2 columns\n- Product: 4 columns\n- Address: 4 columns\n- Wishlist: 2 columns"}], "isError": false}

Examples

• Quickstart step 2: validate the sample schema: command completed successfully

  Source: README.md#quickstart

  Input: examples/quickdbd-sample.txt

  Expected: No errors found

  Command: <guest-path> check examples/quickdbd-sample.txt

  Observed: No errors found. Good job!

Local or hosted: local

Install quickdbd-cli per README and run the documented quickstart: qdbd check, qdbd build (HTML diagram), and qdbd mcp serving schema tools over stdio (list_tables call returning the 7 sample tables).

cd <guest-path> && ls -la && cat README.md | head -c 7000 && python3 --version && ls /inputs 2>/dev/null
cd <guest-path> && grep -n -i -E "^#|install|pip|qdbd build|quickstart|python" README.md | head -80; ls <guest-path> 2>/dev/null; ls /inputs 2>/dev/null
cd <guest-path> && sed -n 72,136p README.md
python3 --version; which pipx uv pip3 2>&1; ls -la <guest-path> <guest-path>; echo "CDP=$CDP_URL"; curl -s -m 10 -o /dev/null -w "%{http_code}\n" $CDP_URL/json/version
curl -s -m 10 $CDP_URL/json/version; echo; python3 -m venv <guest-path> 2>&1 | tail -3; <guest-path> install -q quickdbd-cli 2>&1 | tail -5; <guest-path> --version 2>&1
cd <guest-path> && grep -m3 -E "^(name|version)" pyproject.toml; git init -q 2>&1; git remote add origin https://github.com/MarkPhamm/quickdbd-cli 2>&1; timeout 120 git fetch --depth 1 origin d39602af4436555c3c2d7a3a95acc65e3d46657c 2>&1 | tail -3; git reset --mixed FETCH_HEAD 2>&1 | tail -2; git log --oneline -1; git status --short | head
cd /tmp && <guest-path> install -q <guest-path> 2>&1 | tail -5; <guest-path> --version; <guest-path> --help 2>&1 | head -40
cd <guest-path> && Q=<guest-path>; $Q check examples/quickdbd-sample.txt; echo "rc=$?"; mkdir -p <guest-path> && $Q build examples/quickdbd-sample.txt -o <guest-path>; echo "rc=$?"; ls -la <guest-path>; grep -o "<title>[^<]*" <guest-path> | head -2
cd <guest-path> && grep -rn -E "@(mcp|server)\.tool|def (tool_|_tool_)|Tool\(" src | head -30; grep -rn "mcp" README.md | head -5; sed -n 201,212p README.md
cd <guest-path> && grep -n -A1 -E "^\s+Tool\(" src/quickdbd_cli/agent.py | grep name | head -20; grep -n -B2 -A12 "def _tool_schema\|inputSchema\|input_schema" src/quickdbd_cli/agent.py | head -30
cd <guest-path> && sed -n 737,860p src/quickdbd_cli/agent.py | grep -n -E '^\s+"[a-z_]+",|properties|required|"name"|"type"' | head -60
cd <guest-path> && <guest-path> mcp --help 2>&1 | head -30; grep -n -i "root\|cwd\|getcwd" src/quickdbd_cli/agent.py | head -10
cd <guest-path> && cat examples/quickdbd-sample.txt | head -30; ls examples; <guest-path> check --help | head -3
cd <guest-path> && mkdir -p .coldpass && cat > .coldpass/probe.json <<'EOF'
{"kind":"mcp","argv":["<guest-path>","mcp","examples/quickdbd-sample.txt"],"cwd":"<guest-path>","tool":"list_tables","arguments":{},"expected_text":"Customer"}
EOF
cat .coldpass/probe.json; echo; ls /inputs 2>&1
cd <guest-path> && rm -f <guest-path> && cat > .coldpass/claims.json <<'EOF'
[{"kind":"claim","claim":"qdbd check validates a schema file","source":"A file that passes `qdbd check --strict` pastes into QuickDBD unchanged.","input":"examples/quickdbd-sample.txt","expected":"No errors found","probe_kind":"cli","argv":["<guest-path>","check","examples/quickdbd-sample.txt"],"expected_text":"No errors found","cwd":"<guest-path>"},
{"kind":"claim","claim":"qdbd build writes one self-contained HTML diagram","source":"qdbd build schema.txt -o schema.html","input":"examples/quickdbd-sample.txt","expected":"writes sample HTML page with 7 tables","probe_kind":"cli","argv":["<guest-path>","build","examples/quickdbd-sample.txt","-o","<guest-path>"],"expected_text":"7 tables, 7 relationships","cwd":"<guest-path>"},
{"kind":"claim","claim":"qdbd mcp serves schema tables to AI agents","source":"`qdbd mcp` gives Claude, Copilot and Cursor your schema as tools: tables and columns","input":"examples/quickdbd-sample.txt","expected":"Customer table listed","probe_kind":"mcp","argv":["<guest-path>","mcp","examples/quickdbd-sample.txt"],"tool":"list_tables","arguments":{},"expected_text":"Customer","cwd":"<guest-path>"}]
EOF
python3 -m json.tool .coldpass/claims.json >/dev/null && echo ok; python3 -I <guest-path> --help 2>&1 | head -20
cd <guest-path> && grep -rn -i -E "cron|--once|--now|schedule|webhook|watch" src/quickdbd_cli/*.py README.md | grep -v -i "github/workflows\|erd.yml" | head -15; ls tests; grep -n -i -E "pytest|test" CLAUDE.md | head -10
cd <guest-path> && cat > .coldpass/cycles.json <<'EOF'
{"detected":false,"checks":[],"reason":"Inspected README.md quickstart and src/quickdbd_cli entrypoints (check, build, share, export, layout, path, diff, import, convert, serve, mcp). No cron, scheduler, --once/--now flag, or webhook exists. The only background loop is serve.py's mtime file watcher, which is an interactive live-reload for the editor, not a scheduled cycle, so no manual cycle was triggered."}
EOF
cat > .coldpass/examples.json <<'EOF'
[{"kind":"example","claim":"Quickstart step 2: validate the sample schema","source":"README.md#quickstart","input":"examples/quickdbd-sample.txt","expected":"No errors found","argv":["<guest-path>","check","examples/quickdbd-sample.txt"],"cwd":"<guest-path>","env":{},"expected_text":"No errors found"}]
EOF
python3 -I <guest-path> --validate --replay 2>&1 | head -c 4000
cd <guest-path> && <guest-path> check --strict examples/quickdbd-sample.txt; echo "rc=$?"; python3 -I <guest-path> --validate --replay > <guest-path> 2>&1; echo "checker rc=$?"; python3 -c "import json,sys; d=json.load(open('<guest-path>')) if False else None" ; tail -c 1500 <guest-path>
cd <guest-path> && sed -i 's|"argv":\["<guest-path>","check","examples/quickdbd-sample.txt"\],"expected_text":"No errors found","cwd"|"argv":["<guest-path>","check","--strict","examples/quickdbd-sample.txt"],"expected_text":"No errors found","cwd"|' .coldpass/claims.json && grep -c "strict" .coldpass/claims.json && python3 -I <guest-path> --validate --replay > <guest-path> 2>&1; echo "rc=$?"; head -c 300 <guest-path>; echo; grep -o '"valid": [a-z]*\|"status": "[A-Z]*"\|"problems": \[[^]]*\]' <guest-path> | sort | uniq -c
cd <guest-path> && rm -f <guest-path> && cat > .coldpass/report.json <<'EOF'
{"outcome":"working","fault_owner":null,"operation":"Install quickdbd-cli per README and run the documented quickstart: qdbd check, qdbd build (HTML diagram), and qdbd mcp serving schema tools over stdio (list_tables call returning the 7 sample tables).","operation_scope":"Linux guest, Python 3.12.3, venv at <guest-path>, sample schema examples/quickdbd-sample.txt. No browser, GitHub gist, or dbt needed; CDP endpoint responded HTTP 200 but was not used because qdbd build/check/mcp are CLI-only. qdbd serve (browser editor) was not exercised.","steps":["curl -s $CDP_URL/json/version (HTTP 200, Chrome/155.0.8059.84)","python3 3.12.3 satisfies README 'Python 3.11+'","python3 -m venv <guest-path> && <guest-path> install quickdbd-cli (qdbd 0.3.3)","git init; git remote add origin https://github.com/MarkPhamm/quickdbd-cli; git fetch --depth 1 origin d39602af4436555c3c2d7a3a95acc65e3d46657c; git reset --mixed FETCH_HEAD","<guest-path> install <guest-path> (local pinned source, 0.3.3)","qdbd check examples/quickdbd-sample.txt -> No errors found; qdbd check --strict also passes","qdbd build examples/quickdbd-sample.txt -o <guest-path> -> Wrote ... (7 tables, 7 relationships)","qdbd mcp examples/quickdbd-sample.txt, tool list_tables -> 7 tables incl. Customer"],"deviations":["README suggests pipx/pip/uv; used a venv (README-compatible). Installed PyPI quickdbd-cli first, then replaced it with the pinned local checkout.","/inputs/coldpass-preflight.py does not exist in the guest; ran the supplied <guest-path> --validate --replay instead.","No browser used; the README quickstart 'qdbd serve' opens a browser and was not run. No README claim depends on it.","No product cycle exists (no cron/--once/webhook); cycles.json has detected=false.","Did not run the repo's pytest suite or the VS Code extension; no offline suite counts as operation evidence."],"stuck_step":null,"main_blocker":null,"plain_failure":null,"suggested_fix":"None required for the verified operations."}
EOF
python3 -m json.tool .coldpass/report.json >/dev/null && echo report-ok; ls .coldpass; python3 -I <guest-path> --validate --replay > <guest-path> 2>&1; echo "final rc=$?"; grep -o '"valid": [a-z]*' <guest-path>