taskuary 0.2.0__py3-none-any.whl

taskuary/ci.py

@@ -0,0 +1,237 @@
+"""Closing the git loop: a task's branch becomes a DRAFT pull request, its CI is watched,
+and a red build - or a human's review comment - goes back to the agent that wrote the code
+instead of to nobody.
+
+The human gate never moves. Taskuary opens drafts, never merges; pushing at all still needs
+the GitHub card's 'Agents may push / deploy'. What this adds is the half that was missing:
+after the agent stops typing, something watches what its work did to CI and hands the
+failure back with the failing check named.
+
+The PR lives on the task as a comment marker (PR_MARK) - no schema change, and the whole
+history of what was opened stays readable in the task itself.
+"""
+import json, re
+from datetime import datetime
+from loguru import logger
+
+PR_MARK = 'PULL REQUEST'          # comment marker: 'PULL REQUEST {json}'
+PUSH_MARK = 'PUSHED'              # the same, for work landed straight on the default branch
+CI_MARK = 'CI FEEDBACK'           # what we have already handed back, so it goes back ONCE
+BRANCH_SAFE = re.compile(r'[^a-zA-Z0-9._/-]+')
+TOKEN_URL = re.compile(r'https://[^@/]*@')     # never let a PAT reach a log line or a comment
+
+
+def _conn(store):
+    c = store.get_connector_by_type('github', with_secret=True)
+    if not (c and c.get('Secret')): raise RuntimeError('no GitHub PAT saved (Connectors → GitHub)')
+    return c
+
+
+def _cfg(store) -> dict:
+    c = store.get_connector_by_type('github') or {}
+    try: return json.loads(c.get('ConfigJson') or '{}')
+    except ValueError: return {}
+
+
+def pr_of(store, task_id: int):
+    """The pull request opened for this task, if any - read back off its comments."""
+    for c in reversed(store.list_comments(task_id)):
+        body = str(c.get('Body') or '')
+        if body.startswith(PR_MARK):
+            try: return json.loads(body[len(PR_MARK):].strip())
+            except ValueError: return None
+    return None
+
+
+def landing_of(store, task_id: int):
+    """Where this task's work actually WENT - a pull request or a direct push, whichever
+    happened last. Both are the same question to everything downstream (what commit do I
+    check CI on?), so both answer it the same way: {kind, repo, sha, url, ...}."""
+    for c in reversed(store.list_comments(task_id)):
+        body = str(c.get('Body') or '')
+        for mark, kind in ((PR_MARK, 'pr'), (PUSH_MARK, 'push')):
+            if body.startswith(mark):
+                try: return {**json.loads(body[len(mark):].strip()), 'kind': kind}
+                except ValueError: return None
+    return None
+
+
+def _save_pr(store, task_id: int, pr: dict, actor='ci'):
+    store.add_comment(task_id, actor, 'agent', f'{PR_MARK} {json.dumps(pr)}')
+
+
+def _save_push(store, task_id: int, info: dict, actor='ci'):
+    store.add_comment(task_id, actor, 'agent', f'{PUSH_MARK} {json.dumps(info)}')
+
+
+def flow(store) -> str:
+    """'pr' (a draft pull request) or 'direct' (straight onto the default branch). The
+    owner's call: on your own repo the PR is ceremony, on a shared one it is the review."""
+    return store.get_settings().get('git_flow', 'pr')
+
+
+def branch_for(store, task_id: int, cwd: str) -> str:
+    """The branch the agent actually worked on. Whatever is checked out IS the answer - the
+    agent chose it (or stayed on the default), and guessing a name we did not create would
+    open a PR for a branch that does not exist."""
+    from .agents import _git
+    b = (_git(cwd, 'rev-parse', '--abbrev-ref', 'HEAD') or '').strip()
+    return BRANCH_SAFE.sub('-', b) if b and b != 'HEAD' else ''
+
+
+def open_for_task(store, task_id: int, actor='owner') -> dict:
+    """Open (or find) the draft PR for this task's branch. Refuses the default branch: a PR
+    from main to main is not a thing, and it is the shape a mis-detected branch takes."""
+    from . import github, terminal as hub_term
+    from .store import task_ref
+    c = _conn(store)
+    if not store.get_settings().get('agent_push_enabled') == '1':
+        raise RuntimeError("pushing is off - flip 'Agents may push / deploy' on the GitHub card first")
+    ses = hub_term.session_for(task_id)
+    cwd = getattr(ses, 'cwd', None)
+    if not cwd: raise RuntimeError('no session on this task to read a branch from')
+    repo, _ = hub_term.guess_repo(store, task_id, {})
+    repo = repo or _cfg(store).get('default_repo')
+    if not repo: raise RuntimeError('no repository known for this task')
+    branch = branch_for(store, task_id, cwd)
+    base = _cfg(store).get('default_base') or 'master'
+    if not branch or branch == base:
+        raise RuntimeError(f"the checkout is on '{branch or 'a detached HEAD'}' - the agent needs its own "
+                           'branch before a pull request can be opened')
+    t = store.get_task(task_id) or {}
+    body = (f"Opened by Taskuary for {task_ref(task_id)}.\n\n{(t.get('Summary') or '')[:1500]}\n\n"
+            '_Draft: review and merge yourself - Taskuary never merges._')
+    pr = github.open_pr(c['Secret'], repo, branch, base, f"[{task_ref(task_id)}] {t.get('Title') or 'work'}"[:120], body)
+    pr['repo'], pr['checks'], pr['checked_at'] = repo, None, None
+    _save_pr(store, task_id, pr, actor)
+    store.audit('task', task_id, 'pr_opened', actor, detail={'repo': repo, 'number': pr['number']})
+    logger.info(f'PR #{pr["number"]} opened for task {task_id} ({repo} {branch} -> {base})')
+    return pr
+
+
+def _where(store, task_id: int):
+    """(cwd, repo, base, branch) for a task with a session - everything the two landing
+    roads both need, and the same refusals for both."""
+    from . import terminal as hub_term
+    ses = hub_term.session_for(task_id)
+    cwd = getattr(ses, 'cwd', None)
+    if not cwd: raise RuntimeError('no session on this task to read a checkout from')
+    repo, _ = hub_term.guess_repo(store, task_id, {})
+    repo = repo or _cfg(store).get('default_repo')
+    if not repo: raise RuntimeError('no repository known for this task')
+    base = _cfg(store).get('default_base') or 'master'
+    return cwd, repo, base, branch_for(store, task_id, cwd)
+
+
+def push_direct(store, task_id: int, actor='owner') -> dict:
+    """Land the work straight on the default branch - no pull request. What the owner of
+    their own repo usually wants, and never the default.
+
+    Deliberately narrow: it pushes COMMITS THAT ALREADY EXIST. A dirty tree is refused
+    rather than committed on the agent's behalf (a generated commit message over changes
+    nobody read is exactly the step this product does not take), and nothing ahead of the
+    remote is 'nothing to do', not an error. Force is never passed: a rejected push means
+    the branch moved underneath you, and the answer is to pull, not to overwrite."""
+    from .agents import _git
+    from .store import task_ref
+    if store.get_settings().get('agent_push_enabled') != '1':
+        raise RuntimeError("pushing is off - flip 'Agents may push / deploy' on the GitHub card first")
+    cwd, repo, base, branch = _where(store, task_id)
+    if _git(cwd, 'status', '--porcelain').strip():
+        raise RuntimeError('the checkout has uncommitted changes - the agent should commit them first '
+                           '(Taskuary will not write a commit message for work nobody has read)')
+    _git(cwd, 'fetch', 'origin', base)
+    ahead = (_git(cwd, 'rev-list', '--count', f'origin/{base}..HEAD') or '0').strip()
+    if ahead in ('', '0'):
+        raise RuntimeError(f'nothing to push - HEAD is not ahead of origin/{base}')
+    sha = (_git(cwd, 'rev-parse', 'HEAD') or '').strip()
+    out = _git(cwd, 'push', 'origin', f'HEAD:{base}')
+    # git says nothing useful on success; a rejection is what we must not swallow
+    if re.search(r'rejected|error:|fatal:', out or '', re.I):
+        raise RuntimeError('git refused the push: ' + TOKEN_URL.sub('https://', out)[:300]
+                           + ' - pull and rebase, then push again (Taskuary never force-pushes)')
+    info = {'repo': repo, 'branch': base, 'from': branch, 'sha': sha, 'commits': int(ahead),
+            'url': f'https://github.com/{repo}/commit/{sha}', 'state': 'pushed',
+            'checks': None, 'checked_at': None}
+    _save_push(store, task_id, info, actor)
+    store.add_comment(task_id, actor, 'human',
+                      f"Pushed {ahead} commit(s) straight to {base} ({sha[:7]}) - no pull request.")
+    store.audit('task', task_id, 'pushed_direct', actor,
+                detail={'repo': repo, 'base': base, 'sha': sha, 'commits': int(ahead)})
+    logger.info(f'task {task_id}: {ahead} commit(s) pushed to {repo} {base} ({sha[:7]})')
+    return info
+
+
+def land(store, task_id: int, actor='owner') -> dict:
+    """Publish this task's work the way the owner configured it: a draft pull request, or
+    straight onto the default branch. One door, so the button, the endpoint and an approved
+    proposal cannot disagree about which flow is in force."""
+    return (push_direct if flow(store) == 'direct' else open_for_task)(store, task_id, actor)
+
+
+def _already_fed(store, task_id: int) -> set:
+    """Which failures this task has already been told about - a red build must reach the
+    agent once, not on every poll until it is fixed."""
+    out = set()
+    for c in store.list_comments(task_id):
+        b = str(c.get('Body') or '')
+        if b.startswith(CI_MARK): out.add(b.split('\n', 1)[0][len(CI_MARK):].strip())
+    return out
+
+
+def check_task(store, task_id: int, llm=None) -> dict:
+    """Poll where this task's work landed - a PR or a direct push - refresh its checks, and
+    when they are RED hand the failure back to the live session (or put the task back on
+    the owner when nothing is running). Never raises into the poller."""
+    from . import github, terminal as hub_term
+    at = landing_of(store, task_id)
+    if not at: return {'state': 'not-landed'}
+    try:
+        c = _conn(store)
+        if at['kind'] == 'pr':
+            fresh = github.pr(c['Secret'], at['repo'], at['number'])
+            at = {**at, **fresh}
+        ck = github.checks(c['Secret'], at['repo'], at['sha'])
+    except Exception as e:
+        logger.warning(f'ci check failed for task {task_id}: {e}')
+        return {'state': 'error', 'error': str(e)[:200]}
+    at = {**at, 'checks': ck, 'checked_at': datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+    where = f"the pull request for this task (#{at['number']}" if at['kind'] == 'pr' \
+        else f"{at['branch']} (the commit this task pushed"
+    (_save_pr if at['kind'] == 'pr' else _save_push)(store, task_id, {k: v for k, v in at.items() if k != 'kind'})
+    ref = at.get('number') if at['kind'] == 'pr' else at['sha'][:7]
+    if ck['state'] != 'failure': return {'state': ck['state'], 'at': ref, 'kind': at['kind']}
+    key = f"{at['sha'][:10]}:{','.join(sorted(f['name'] or '?' for f in ck['failed']))}"
+    if key in _already_fed(store, task_id): return {'state': 'failure', 'fed': False, 'at': ref}
+    named = '\n'.join(f"- {f['name']}: {f['summary'] or 'see the run log'}" for f in ck['failed'])
+    # direct mode has no PR to hold the change back, so the instruction changes with it:
+    # the broken commit is ALREADY on the branch, and that is the thing to say out loud
+    tail = ('Fix the cause and push again; do not merge.' if at['kind'] == 'pr'
+            else 'This commit is ALREADY on the branch - fix it forward and push again.')
+    text = (f"CI is failing on {where}, commit {at['sha'][:7]}). "
+            f"The failing checks are:\n{named}\n{tail}")
+    store.add_comment(task_id, 'ci', 'agent', f'{CI_MARK} {key}\n{text}')
+    handed = hub_term.say_to_task(store, task_id, {'FromName': 'CI', 'Channel': 'github', 'BodyText': text}, 'ci')
+    if not handed:
+        # nobody is at the keyboard: it becomes work waiting on the owner, not a silent red
+        store.update_task(task_id, {'Status': 'open'}, 'ci')
+    store.audit('task', task_id, 'ci_failure', 'ci', detail={'at': ref, 'kind': at['kind'],
+                                                             'checks': [f['name'] for f in ck['failed']],
+                                                             'handed_to_agent': handed})
+    return {'state': 'failure', 'fed': True, 'handed': handed, 'at': ref, 'kind': at['kind']}
+
+
+def poll(store, llm=None) -> int:
+    """Every task whose work has landed - PR or direct push - checked once. Called from the
+    same sync as everything else; off unless the owner turned ci_watch on."""
+    if store.get_settings().get('ci_watch', 'off') == 'off': return 0
+    n = 0
+    for t in store.list_tasks():
+        if t['Status'] in ('done', 'dropped'): continue
+        at = landing_of(store, t['TaskId'])
+        # a merged/closed PR is finished business; a direct push is only ever checked while
+        # its checks could still be running, which the state below settles
+        if not at or at.get('state') == 'closed': continue
+        out = check_task(store, t['TaskId'], llm)
+        n += 1 if out.get('fed') else 0
+    return n

taskuary/cli.py

@@ -0,0 +1,47 @@
+"""`taskuary` - start the local server and open the app. Everything lives in ~/.taskuary."""
+import argparse, socket, threading, time, webbrowser
+import uvicorn
+from . import __version__, config
+
+
+def _busy(host, port):
+    with socket.socket() as s: return s.connect_ex((host, port)) == 0
+
+def _is_taskuary(url):
+    try:
+        import requests
+        return requests.get(f'{url}/api/settings', timeout=2).status_code in (200, 401)
+    except Exception:
+        return False
+
+
+def main():
+    ap = argparse.ArgumentParser(prog='taskuary', description='Automate your job - the local-first agent work hub.')
+    ap.add_argument('--port', type=int, help='override [server].port')
+    ap.add_argument('--no-browser', action='store_true')
+    ap.add_argument('--debug', action='store_true', help='verbose console logging (requests, report runs, errors)')
+    ap.add_argument('--version', action='version', version=f'taskuary {__version__}')
+    args = ap.parse_args()
+    from .logs import setup as setup_logs
+    setup_logs(args.debug)
+    cfg = config.load()
+    host, port = cfg['server']['host'], args.port or cfg['server']['port']
+    url = f'http://{host}:{port}'
+    if _busy(host, port):
+        if _is_taskuary(url):
+            # don't crash into 'address already in use' - reuse the running instance
+            print(f'Taskuary is already running at {url} - opening it.')
+            if not args.no_browser: webbrowser.open(url)
+            return
+        from .desktop import free_port
+        old, port = port, free_port(host)
+        url = f'http://{host}:{port}'
+        print(f'port {old} is in use by something else - using {port} instead')
+    print(f'Taskuary {__version__} - {url}  (data: {config.db_path()})')
+    if not args.no_browser:
+        threading.Thread(target=lambda: (time.sleep(1.2), webbrowser.open(url)), daemon=True).start()
+    uvicorn.run('taskuary.server:app', host=host, port=port, log_level='warning')
+
+
+if __name__ == '__main__':
+    main()

taskuary/coder.py

@@ -0,0 +1,132 @@
+"""How a coding task ENDS. The work itself happens in a live session you watch (terminal.py);
+this closes the loop: the transcript becomes the report, the responder drafts the reply the
+sender gets, and the task waits on you to send it.
+"""
+import json, re
+from loguru import logger
+
+FIELDS = ('determination', 'actions', 'summary')
+
+
+TRANSCRIPT_SYSTEM = (
+    'You are reading the terminal transcript of a coding agent that has just worked a task for '
+    "the owner, who has now closed the session. Write the owner's record of what happened, from "
+    'the transcript ALONE - never a step it did not take, never a claim it did not make.\n'
+    'Output ONLY this JSON: {"determination": "...", "actions": "...", "summary": "..."} - '
+    'determination is what was decided and why, actions is what was actually changed (files, '
+    'commands, records, ids), summary is the two-sentence version for someone who read none of it.')
+
+
+def report_from_transcript(store, task_id: int, transcript: str, agent: str = 'coder') -> dict:
+    """The report, written from what is already on screen. The agent is never asked for prose:
+    by the time you click Done you are done talking to it, and a transcript cannot argue. No AI
+    configured (or a bad answer) files the transcript tail itself - the record never disappears."""
+    from .llm import build_llm
+    blank = dict.fromkeys(FIELDS, '')
+    if not (transcript or '').strip(): return blank | {'summary': '(the session ended with nothing on screen)'}
+    try:
+        llm = build_llm(store)
+        if not llm: raise RuntimeError('no AI connector is set up to write the report')
+        out = llm(TRANSCRIPT_SYSTEM, f"Task: {(store.get_task(task_id) or {}).get('Title') or ''}\n\n"
+                                     f'Transcript:\n{transcript}', max_tokens=900)
+        j = json.loads(re.sub(r'^```(json)?|```$', '', (out or '').strip(), flags=re.M))
+        rep = blank | {k: str(j.get(k) or '') for k in ('determination', 'actions', 'summary')}
+        if not any(rep.values()): raise ValueError('empty report')
+        return rep
+    except Exception as e:
+        logger.warning(f'transcript report failed for task {task_id}: {e}')
+        return blank | {'summary': transcript[-2000:]}
+
+
+PAUSE_MARKER = 'HANDOVER NOTE'
+PAUSE_SYSTEM = (
+    'You are reading the terminal transcript of a coding agent that has been PAUSED mid-task - the '
+    'owner is stopping for now and the same work will be picked up later, by an agent with no memory '
+    'of this session. Write the handover note it will be given. From the transcript ALONE.\n'
+    'Output ONLY this JSON: {"found": "...", "did": "...", "next": "..."} - found is what it worked '
+    'out about the problem (causes, file and record names, ids, dead ends worth not repeating), did '
+    'is what it already changed, next is the concrete next step it was about to take. Say "nothing '
+    'yet" in a field rather than inventing.')
+
+
+def pause_note(store, task_id: int, transcript: str) -> str:
+    """What a paused session knew, in the words the next session needs. A pty has no resumable
+    id (no --resume for a TUI), so the note IS the continuity - it gets typed into the next
+    session by terminal.seed_text. No AI, or a bad answer, keeps the transcript tail instead."""
+    from .llm import build_llm
+    if not (transcript or '').strip(): return 'Nothing on screen - the session was paused before it did anything.'
+    try:
+        llm = build_llm(store)
+        if not llm: raise RuntimeError('no AI connector is set up to write the note')
+        out = llm(PAUSE_SYSTEM, f"Task: {(store.get_task(task_id) or {}).get('Title') or ''}\n\n"
+                                f'Transcript:\n{transcript}', max_tokens=900)
+        j = json.loads(re.sub(r'^```(json)?|```$', '', (out or '').strip(), flags=re.M))
+        note = '\n'.join(f'{k.capitalize()}: {j[k]}' for k in ('found', 'did', 'next') if str(j.get(k) or '').strip())
+        if not note: raise ValueError('empty note')
+        return note
+    except Exception as e:
+        logger.warning(f'pause note failed for task {task_id}: {e}')
+        return f'(no AI note - the last of the session, verbatim)\n{transcript[-2000:]}'
+
+
+def resolution_text(rep: dict) -> str:
+    return '\n'.join(f'{k.capitalize()}: {rep[k]}' for k in ('determination', 'actions', 'summary') if rep.get(k))
+
+
+def reply_target(store, task_id: int):
+    """Which message a reply answers: the last one that came IN. Our own sent mail rides in
+    the chain as 'context', and answering that would mail ourselves."""
+    return next((m['MessageId'] for m in reversed(store.list_messages(task_id)) if m.get('Status') != 'context'), None)
+
+
+def finish(store, task_id: int, rep: dict, run_id: int = None, actor: str = 'coder') -> dict:
+    """The end of finished work: the responder drafts the reply the sender gets and the task waits
+    on you to send it. Nothing to reply to means nothing to wait for, so it just closes."""
+    # a held draft is itself proof there is someone waiting on an answer, so it names the message
+    # to reply to when reply_target cannot find one (a chat thread, a promoted feed item)
+    held = store.held_review(task_id) or {}
+    mid = reply_target(store, task_id) or held.get('MessageId')
+    # can this channel carry a reply at all? outbound.can_reply is the ONE answer - the
+    # owner's per-channel setting, plus the rules that are not theirs to change (a public
+    # GitHub comment needs that card's switch; a tracker is read-only by design). With it
+    # off, finished work just closes: the report lands on the task, no dead-end draft.
+    if mid:
+        from .outbound import can_reply
+        if not can_reply(store, (store.get_message(mid) or {}).get('Channel')): mid = None
+    if mid: raise_reply(store, task_id, mid, run_id, rep)
+    store.update_task(task_id, {'Status': 'waiting' if mid else 'done'}, actor)
+    return {'drafting': bool(mid), 'message_id': mid}
+
+
+def raise_reply(store, task_id: int, mid: int, run_id: int, rep: dict) -> None:
+    """The session reported; the responder writes what the sender actually reads. One voice for
+    every reply the owner sends - and no coding CLI drafting prose from inside a repo. A draft
+    that fails to write still leaves the review standing: 'Draft with AI' retries it.
+
+    A reply triage already drafted from the mail alone was HELD when the session started - it
+    promised what the agent had not looked at yet. That same review comes back here and is
+    rewritten from the report, so the sender gets one answer, and it is the true one."""
+    from . import responder
+    held = store.held_review(task_id, mid) or store.held_review(task_id)
+    if held:
+        rid = held['ReviewId']
+        store.unhold_review(rid, 'the agent finished - the reply is rewritten from what it found')
+        store.update_review_reason(rid, 'the agent finished - the reply is rewritten from what it found', run_id)
+    else:
+        rid = store.add_review({'TaskId': task_id, 'MessageId': mid, 'RunId': run_id, 'Kind': 'draft_reply',
+                                'Status': 'pending', 'Reason': 'coder finished the work - reply awaiting approval'})
+    try: responder.write_draft(store, task_id, rid, resolution_text(rep), 'coder')
+    except Exception as e: logger.warning(f'reply draft failed for task {task_id}: {e}')
+    # the ping that matters most: work FINISHED and its reply is sitting in Review on you
+    if (store.get_settings().get('notify_level') or 'needs_me') != 'off':
+        from .outbound import notify
+        from .phone import ping_tail
+        from .store import task_ref
+        t = store.get_task(task_id) or {}
+        head = (t.get('Title') or '')[:100]
+        # with phone approvals on, the ping carries the draft and the [rvN] tag - replying
+        # 'approve' in the chat sends it (phone.py), so 'done' really can mean done
+        tail = ping_tail(store, rid, (store.get_review(rid) or {}).get('DraftText'))
+        try: notify(store, f'{task_ref(task_id)} is done - the reply is drafted and waiting on '
+                           f'your approval in Review.\n{head}{tail}')
+        except Exception as e: logger.warning(f'notify failed for task {task_id}: {e}')

taskuary/config.py

@@ -0,0 +1,62 @@
+"""Config: ~/.taskuary/config.toml (or TASKUARY_HOME) - zero assumptions, all defaults sane.
+
+[server] port/host/token; [agents.<name>] cmd/args/resume_args/timeout/cwd/cwd_map;
+[github] token/default_repo. Everything is optional: `taskuary` runs with no config at all
+(SQLite store, stub agent, localhost server).
+"""
+import json, os
+try: import tomllib
+except ImportError: import tomli as tomllib  # py3.10
+from pathlib import Path
+
+def home() -> Path:
+    p = Path(os.getenv('TASKUARY_HOME') or Path.home() / '.taskuary')
+    old = Path.home() / '.taskhub'
+    # one-time migration from the pre-rename data dir
+    if not os.getenv('TASKUARY_HOME') and not p.exists() and old.exists(): old.rename(p)
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+def load() -> dict:
+    f = home() / 'config.toml'
+    cfg = tomllib.loads(f.read_text(encoding='utf-8')) if f.exists() else {}
+    cfg.setdefault('server', {})
+    cfg['server'].setdefault('host', '127.0.0.1')
+    cfg['server'].setdefault('port', 7787)
+    # --dangerously-skip-permissions matters: without it a headless claude waits forever
+    # for permission approvals nobody can click. stream-json (+ required --verbose) makes
+    # claude emit events AS IT WORKS so the Board can stream the run live.
+    cfg.setdefault('agents', {'coder': {'cmd': 'claude',
+                                        'args': ['-p', '--dangerously-skip-permissions',
+                                                 '--output-format', 'stream-json', '--verbose'],
+                                        'resume_args': ['--resume'], 'timeout': 1500}})
+    cfg.setdefault('github', {})
+    return cfg
+
+def db_path() -> str:
+    return str(home() / 'taskuary.db')
+
+
+def _tval(v):
+    if isinstance(v, bool): return 'true' if v else 'false'
+    if isinstance(v, (int, float)): return str(v)
+    if isinstance(v, list): return '[' + ', '.join(_tval(o) for o in v) + ']'
+    return json.dumps(str(v))  # json string escaping == toml basic string escaping
+
+def dumps_toml(d: dict, prefix='') -> str:
+    """Minimal TOML writer for our config shapes (scalars, string lists, nested tables).
+    tomllib is stdlib-read-only; this keeps the UI able to persist config with no new deps."""
+    lines, tables = [], []
+    for k, v in d.items():
+        key = k if k.replace('_', '').replace('-', '').isalnum() else json.dumps(k)
+        if isinstance(v, dict): tables.append((key, v))
+        else: lines.append(f'{key} = {_tval(v)}')
+    out = (f'[{prefix}]\n' if prefix and lines else '') + '\n'.join(lines)
+    for key, v in tables:
+        sub = dumps_toml(v, f'{prefix}.{key}' if prefix else key)
+        if sub: out += ('\n\n' if out else '') + sub
+    return out
+
+def save(cfg: dict):
+    """Persist config to ~/.taskuary/config.toml (round-trips through tomllib in tests)."""
+    (home() / 'config.toml').write_text(dumps_toml(cfg) + '\n', encoding='utf-8')

taskuary/db.py

@@ -0,0 +1,63 @@
+"""Any database by connection string - one card, every engine. Two roads by shape:
+a URL ('postgresql://user:pw@host/db', 'mysql+pymysql://...', 'snowflake://...') runs
+through SQLAlchemy; anything else ('DRIVER={...};SERVER=...;') is a raw ODBC string via
+pyodbc. A {password} placeholder in the string is filled from the card's write-only
+secret, so the saved config never carries the password itself.
+"""
+
+
+def conn_str(cfg: dict) -> str:
+    cs = (cfg.get('conn_str') or '').strip()
+    if not cs: raise RuntimeError('no connection string set - Connectors → Any database (connection string)')
+    return cs.replace('{password}', cfg.get('password') or '')
+
+
+def is_url(cs: str) -> bool: return '://' in cs
+
+
+def _rows_sqlalchemy(cs, query, n):
+    try: import sqlalchemy
+    except ImportError:
+        # name the package, not the extra: `taskuary[db]` silently no-ops when the install's
+        # metadata predates the extra (see aws._boto3)
+        raise RuntimeError('sqlalchemy is not installed - run: pip install sqlalchemy, plus the engine '
+                           'driver (psycopg2-binary for postgres, pymysql for mysql, snowflake-sqlalchemy…)')
+    eng = sqlalchemy.create_engine(cs, pool_pre_ping=True)
+    try:
+        with eng.connect() as cx:
+            return [dict(r._mapping) for r in cx.execute(sqlalchemy.text(query)).fetchmany(n)]
+    finally:
+        eng.dispose()
+
+
+def _rows_odbc(cs, query, n):
+    import pyodbc
+    with pyodbc.connect(cs, timeout=10) as cx:
+        cur = cx.cursor().execute(query)
+        cols = [c[0] for c in cur.description or []]
+        return [dict(zip(cols, r)) for r in cur.fetchmany(n)]
+
+
+def run_query(cfg: dict, limit: int) -> list:
+    cs = conn_str(cfg)
+    return (_rows_sqlalchemy if is_url(cs) else _rows_odbc)(cs, cfg['query'], limit)
+
+
+def test(cfg: dict) -> dict:
+    """Connect and run a probe; never raises - errors come back as data. Engines with no
+    bare SELECT 1 (Oracle wants FROM DUAL) can set 'test_query' on the card."""
+    try:
+        cs = conn_str(cfg)
+        rows = (_rows_sqlalchemy if is_url(cs) else _rows_odbc)(cs, cfg.get('test_query') or 'SELECT 1', 1)
+        eng = cs.split('://', 1)[0] if is_url(cs) else 'odbc'
+        return {'ok': True, 'engine': eng, 'detail': f'connected ({eng}) · probe returned {len(rows)} row(s)'}
+    except Exception as e:
+        return {'ok': False, 'error': str(e)[:500]}
+
+
+def run_report(cfg: dict):
+    """Report executor: (headline, body). One row past the limit is fetched so the
+    headline can admit when the result was cut (see reports.rows_out)."""
+    from .reports import row_limit, rows_out
+    lim, mine = row_limit(cfg)
+    return rows_out(run_query(cfg, lim + 1), lim, mine=mine)

taskuary/desktop.py

@@ -0,0 +1,72 @@
+"""Taskuary desktop: the same server + UI in a native window, shipped as one executable.
+
+The FastAPI app runs on a free localhost port in a background thread; pywebview (Edge
+WebView2 on Windows) hosts the UI. No pywebview -> graceful fallback to the default
+browser, so `taskuary-desktop` is useful even from a bare pip install. Build the single
+exe with `pyinstaller taskuary.spec` (see the spec at the repo root).
+"""
+import io, socket, sys, threading, time, webbrowser
+
+# Windowed (console=False) exe: std streams are None, but uvicorn's logging setup calls
+# sys.stdout.isatty() and loguru writes to stderr - shim BEFORE importing uvicorn.
+for _s in ('stdout', 'stderr'):
+    if getattr(sys, _s) is None: setattr(sys, _s, io.StringIO())
+
+import uvicorn
+
+
+def free_port(host='127.0.0.1') -> int:
+    with socket.socket() as s:
+        s.bind((host, 0)); return s.getsockname()[1]
+
+
+def start_server(host='127.0.0.1', port=None):
+    """Run the app in a daemon thread; returns (server, url) once it accepts connections."""
+    from taskuary.server import app  # absolute: PyInstaller runs this file as a script
+    port = port or free_port(host)
+    server = uvicorn.Server(uvicorn.Config(app, host=host, port=port, log_level='warning'))
+    threading.Thread(target=server.run, daemon=True).start()
+    for _ in range(200):
+        if server.started: break
+        time.sleep(0.05)
+    return server, f'http://{host}:{port}'
+
+
+def main():
+    from taskuary import __version__, config
+    argv = sys.argv[1:]
+    from taskuary.logs import setup as setup_logs
+    setup_logs('--debug' in argv)
+    port = int(argv[argv.index('--port') + 1]) if '--port' in argv else None
+    try:
+        server, url = start_server(port=port)
+    except Exception:
+        import traceback
+        try: (config.home() / 'desktop-error.log').write_text(traceback.format_exc(), encoding='utf-8')
+        except OSError: pass
+        raise
+    print(f'Taskuary {__version__} desktop - {url}  (data: {config.db_path()})')
+    if '--server-only' in argv:  # headless mode: CI smoke tests, or run as a service
+        try:
+            while not server.should_exit: time.sleep(1)
+        except KeyboardInterrupt: pass
+        return
+    try:
+        import webview
+        webview.create_window('Taskuary', url, width=1280, height=840, min_size=(900, 600))
+        webview.start()
+    except Exception:
+        # no native window (pywebview missing or its runtime broke) -> browser fallback,
+        # never an error dialog; the traceback lands next to the data for diagnosis
+        import traceback
+        try: (config.home() / 'desktop-error.log').write_text(traceback.format_exc(), encoding='utf-8')
+        except OSError: pass
+        webbrowser.open(url)
+        try:
+            while True: time.sleep(3600)
+        except KeyboardInterrupt: pass
+    server.should_exit = True
+
+
+if __name__ == '__main__':
+    main()