deepvista-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{deepvista_cli-0.3.0 → deepvista_cli-0.5.0}/.github/workflows/ci.yml

@@ -47,3 +47,29 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: gh skill publish --dry-run
+
+  windows-smoke:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Parse install.ps1 (syntax check)
+        shell: pwsh
+        run: |
+          $errors = $null
+          [System.Management.Automation.Language.Parser]::ParseFile("$PWD/install.ps1", [ref]$null, [ref]$errors) | Out-Null
+          if ($errors.Count -gt 0) {
+            $errors | ForEach-Object { Write-Error $_.Message }
+            exit 1
+          }
+          Write-Host "install.ps1 parses cleanly"
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install deepvista CLI from checkout
+        run: uv tool install ".[ui]"
+
+      - name: Smoke test - deepvista --help
+        run: deepvista --help

deepvista_cli-0.5.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.5.0"
+}

{deepvista_cli-0.3.0 → deepvista_cli-0.5.0}/CHANGELOG.md

@@ -37,6 +37,21 @@ users what's new between the version they have installed and the latest release.
   adopts a pre-existing server-side row instead of failing when the local
   file is missing.
 
+## [0.5.0](https://github.com/DeepVista-AI/deepvista-cli/compare/v0.4.0...v0.5.0) (2026-06-04)
+
+
+### Features
+
+* **DV-936:** task_queue run/list/setup commands ([#155](https://github.com/DeepVista-AI/deepvista-cli/issues/155)) ([0d90691](https://github.com/DeepVista-AI/deepvista-cli/commit/0d9069106d14068d657e16415be80dec95f12085))
+
+## [0.4.0](https://github.com/DeepVista-AI/deepvista-cli/compare/v0.3.0...v0.4.0) (2026-06-03)
+
+
+### Features
+
+* **DV-941:** add windows install script and trampoline troubleshooting docs ([#156](https://github.com/DeepVista-AI/deepvista-cli/issues/156)) ([eed7335](https://github.com/DeepVista-AI/deepvista-cli/commit/eed7335ffdc1dfcfd84523ed0e77be066b7fe9c3))
+* **DV-942:** print next-step hints after auth login ([#157](https://github.com/DeepVista-AI/deepvista-cli/issues/157)) ([0fca6c9](https://github.com/DeepVista-AI/deepvista-cli/commit/0fca6c9309623ee690c2c9e16870d528b558fd80))
+
 ## [0.3.0](https://github.com/DeepVista-AI/deepvista-cli/compare/v0.2.0...v0.3.0) (2026-05-31)
 
 

{deepvista_cli-0.3.0 → deepvista_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepvista-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: CLI for DeepVista — chat, notes, skills, and memory from your terminal.
 Project-URL: Homepage, https://deepvista.ai
 Project-URL: Repository, https://github.com/DeepVista-AI/deepvista-cli
@@ -164,14 +164,52 @@ then `deepvista auth login`).
 
 ### For non-Claude-Code agents (Cursor, OpenCode, OpenClaw, …)
 
+**macOS / Linux (bash):**
+
 ```bash
 curl -sSL https://raw.githubusercontent.com/DeepVista-AI/deepvista-cli/main/install.sh | bash
 ```
 
+**Windows (PowerShell):**
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/DeepVista-AI/deepvista-cli/main/install.ps1 | iex"
+```
+
 The script auto-detects your package manager (`uv`, `pipx`, or `pip`) and copies the consolidated `deepvista` skill into your agent's skill directory (Cursor, OpenCode, OpenClaw, and Claude Code as a fallback). If you upgraded from an earlier release, it also sweeps out the 12 legacy `deepvista-*` skills so you don't end up with both.
 
 Prefer GitHub's CLI? `gh skill install DeepVista-AI/deepvista-cli` works too (GitHub CLI ≥ 2.90, preview).
 
+#### Windows troubleshooting: `uv trampoline failed to canonicalize script path`
+
+On Windows, running `deepvista` may fail with:
+
+```
+error: uv trampoline failed to canonicalize script path
+```
+
+This is a [known uv-on-Windows issue](https://github.com/astral-sh/uv/issues): the launcher (trampoline) that `uv tool install` creates can fail to resolve its own path. It is aggravated by working directories that contain **spaces** (e.g. `C:\Users\you\Claude Folder`) or are inside **OneDrive**-synced folders.
+
+Fixes, in order of preference:
+
+1. **Update uv and reinstall the launcher:**
+
+   ```powershell
+   uv self update
+   uv tool install --reinstall "deepvista-cli[ui]"
+   ```
+
+2. **Run via `uv tool run` as a fallback** (bypasses the broken trampoline entirely):
+
+   ```powershell
+   uv tool run deepvista auth login
+   uv tool run deepvista notes +quick "My first note"
+   ```
+
+3. **Avoid spaces / OneDrive in your working directory.** Run from a path without spaces, e.g. `C:\dev`, rather than `C:\Users\you\Claude Folder`.
+
+The `install.ps1` script performs this check automatically: after installing it runs `deepvista --version`, and if it hits the trampoline error it falls back to `uv tool run deepvista` and prints the guidance above. It also adds `%USERPROFILE%\.local\bin` (uv's tool bin directory) to your user PATH if it isn't already there — restart your shell afterward so new terminals pick it up.
+
 ### Get Started
 
 Open your agent and paste:

{deepvista_cli-0.3.0 → deepvista_cli-0.5.0}/README.md

@@ -135,14 +135,52 @@ then `deepvista auth login`).
 
 ### For non-Claude-Code agents (Cursor, OpenCode, OpenClaw, …)
 
+**macOS / Linux (bash):**
+
 ```bash
 curl -sSL https://raw.githubusercontent.com/DeepVista-AI/deepvista-cli/main/install.sh | bash
 ```
 
+**Windows (PowerShell):**
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/DeepVista-AI/deepvista-cli/main/install.ps1 | iex"
+```
+
 The script auto-detects your package manager (`uv`, `pipx`, or `pip`) and copies the consolidated `deepvista` skill into your agent's skill directory (Cursor, OpenCode, OpenClaw, and Claude Code as a fallback). If you upgraded from an earlier release, it also sweeps out the 12 legacy `deepvista-*` skills so you don't end up with both.
 
 Prefer GitHub's CLI? `gh skill install DeepVista-AI/deepvista-cli` works too (GitHub CLI ≥ 2.90, preview).
 
+#### Windows troubleshooting: `uv trampoline failed to canonicalize script path`
+
+On Windows, running `deepvista` may fail with:
+
+```
+error: uv trampoline failed to canonicalize script path
+```
+
+This is a [known uv-on-Windows issue](https://github.com/astral-sh/uv/issues): the launcher (trampoline) that `uv tool install` creates can fail to resolve its own path. It is aggravated by working directories that contain **spaces** (e.g. `C:\Users\you\Claude Folder`) or are inside **OneDrive**-synced folders.
+
+Fixes, in order of preference:
+
+1. **Update uv and reinstall the launcher:**
+
+   ```powershell
+   uv self update
+   uv tool install --reinstall "deepvista-cli[ui]"
+   ```
+
+2. **Run via `uv tool run` as a fallback** (bypasses the broken trampoline entirely):
+
+   ```powershell
+   uv tool run deepvista auth login
+   uv tool run deepvista notes +quick "My first note"
+   ```
+
+3. **Avoid spaces / OneDrive in your working directory.** Run from a path without spaces, e.g. `C:\dev`, rather than `C:\Users\you\Claude Folder`.
+
+The `install.ps1` script performs this check automatically: after installing it runs `deepvista --version`, and if it hits the trampoline error it falls back to `uv tool run deepvista` and prints the guidance above. It also adds `%USERPROFILE%\.local\bin` (uv's tool bin directory) to your user PATH if it isn't already there — restart your shell afterward so new terminals pick it up.
+
 ### Get Started
 
 Open your agent and paste:

{deepvista_cli-0.3.0 → deepvista_cli-0.5.0}/deepvista_cli/commands/auth.py

@@ -14,6 +14,7 @@ from deepvista_cli.auth.tokens import (
     remove_account,
     switch_active_account,
 )
+from deepvista_cli.client.origin import detect_agent_tool
 from deepvista_cli.config import credentials_path
 from deepvista_cli.output.formatter import format_output, output_error
 
@@ -23,6 +24,37 @@ def auth_group() -> None:
     """Authenticate with DeepVista."""
 
 
+def _print_next_steps() -> None:
+    """Print actionable next-step options after a successful login (DV-942).
+
+    Written to stderr so the JSON result on stdout stays machine-parseable.
+    Suggestions adapt to whoever is driving the CLI (agent vs. terminal).
+    """
+    tool, _version = detect_agent_tool()
+    if tool == "claude-code":
+        steps = [
+            "/refresh-skills — sync the DeepVista skill catalog",
+            'say "Help me get started with DeepVista."',
+            'deepvista notes +quick "<fact>" — capture your first note',
+        ]
+    elif tool == "deepvista-cli":  # direct terminal usage
+        steps = [
+            'deepvista notes +quick "My first note" — capture a note',
+            "deepvista skill list — browse your workflow skills",
+            "deepvista ui — launch the terminal UI",
+            "deepvista chat — talk to your DeepVista agent",
+        ]
+    else:  # some other AI agent is driving us
+        steps = [
+            'deepvista notes +quick "<fact>" — capture a note for the user',
+            "deepvista skill list — discover available workflow skills",
+            'deepvista vistabase +search "<topic>" — recall the user\'s stored context',
+        ]
+    click.echo("\n  What's next? Pick one:", err=True)
+    for step in steps:
+        click.echo(f"    - {step}", err=True)
+
+
 @auth_group.command("login")
 @click.option("--code", default=None, help="One-time auth code from the browser.")
 @click.option("--dry-run", is_flag=True, default=False, help="Preview what would happen without making any changes.")
@@ -64,6 +96,7 @@ def auth_login(ctx: click.Context, code: str | None, dry_run: bool) -> None:
     }
     format_output(result, ctx.obj.output_format)
     click.echo(f"  Logged in as {tokens.email or tokens.user_id}", err=True)
+    _print_next_steps()
 
 
 @auth_group.command("status")

{deepvista_cli-0.3.0 → deepvista_cli-0.5.0}/deepvista_cli/commands/skill.py

@@ -133,9 +133,37 @@ def skill_get(ctx: click.Context, skill_id: str) -> None:
         "tool_plan."
     ),
 )
+@click.option(
+    "--webhook",
+    is_flag=True,
+    default=False,
+    help=(
+        "Mark this as a webhook-queued run (DV-955). Appends the task-queue "
+        "completion contract so the host agent reports the queue task after "
+        "`skill complete`. Set automatically on commands the webhook enqueues."
+    ),
+)
+@click.option(
+    "--best-effort",
+    is_flag=True,
+    default=False,
+    help=(
+        "Unattended run: instruct the host agent to answer open questions "
+        "from the vistabase instead of stalling, note assumptions, and only "
+        "pause on hard blockers (DV-955)."
+    ),
+)
 @click.option("--dry-run", is_flag=True, default=False, help="Preview what would happen without making any changes.")
 @click.pass_context
-def skill_run(ctx: click.Context, skill_id: str, user_input: str | None, mode: str, dry_run: bool) -> None:
+def skill_run(
+    ctx: click.Context,
+    skill_id: str,
+    user_input: str | None,
+    mode: str,
+    webhook: bool,
+    best_effort: bool,
+    dry_run: bool,
+) -> None:
     """Run a Skill — host mode by default; ``--mode deepvista`` delegates the whole run server-side.
 
     > [!CAUTION] This is a write command — host mode acquires the parent
@@ -160,6 +188,36 @@ def skill_run(ctx: click.Context, skill_id: str, user_input: str | None, mode: s
         _skill_run_deepvista(ctx, skill_id, user_input, dry_run=dry_run)
         return
 
+    emit_host_run_packet(
+        ctx,
+        skill_id,
+        user_input,
+        mode,
+        dry_run=dry_run,
+        webhook=webhook,
+        best_effort=best_effort,
+    )
+
+
+def emit_host_run_packet(
+    ctx: click.Context,
+    skill_id: str,
+    user_input: str | None,
+    mode: str = "host",
+    *,
+    dry_run: bool = False,
+    webhook: bool = False,
+    best_effort: bool = False,
+    task_id: str | None = None,
+) -> None:
+    """Fetch the skill, acquire the run lock, and print the host run packet.
+
+    Shared by ``skill run`` (host / auto modes) and ``task_queue run --host``
+    (DV-955), which emits packets for webhook-queued workflow tasks instead
+    of subprocess-executing them — a queued workflow needs the surrounding
+    host agent to drive it. ``task_id`` (only known on the task-queue path)
+    threads the queue entry into the completion contract.
+    """
     # host / auto: fetch the card, optionally acquire the lock, and emit a
     # run packet the host agent drives.
     card = _client(ctx).post("/get_context_card", {"card_id": skill_id, "card_type": "skill"})
@@ -196,7 +254,11 @@ def skill_run(ctx: click.Context, skill_id: str, user_input: str | None, mode: s
         "phase_routes": phase_routes,
         "user_input": user_input or "",
         "skill_status": card.get("status", ""),
+        "webhook": webhook,
+        "best_effort": best_effort,
     }
+    if task_id:
+        run_header["task_id"] = task_id
 
     if dry_run:
         format_output(
@@ -222,6 +284,12 @@ def skill_run(ctx: click.Context, skill_id: str, user_input: str | None, mode: s
     click.echo("---")
     click.echo()
     click.echo(_load_host_runtime_contract())
+    if best_effort:
+        click.echo()
+        click.echo(_BEST_EFFORT_STANZA)
+    if webhook:
+        click.echo()
+        click.echo(_webhook_task_stanza(task_id))
 
 
 def _skill_run_deepvista(
@@ -258,6 +326,45 @@ def _load_host_runtime_contract() -> str:
     return resources.files("deepvista_cli.resources").joinpath("workflow_host_runtime.md").read_text(encoding="utf-8")
 
 
+# Appended to the runtime contract for unattended runs (DV-955). The run was
+# triggered by a webhook — there is no human in the loop to answer questions.
+_BEST_EFFORT_STANZA = """\
+## Best-effort mode (unattended run)
+
+This run was triggered without a human in the loop. Do NOT stall waiting
+for answers:
+
+- When a step needs information, search the vistabase first:
+  `deepvista card +search "…"`, `deepvista vistabase +search "…"`,
+  `deepvista notes list`. Prefer an answer found there over asking.
+- When nothing answers, make the most reasonable assumption, state it in
+  the phase's artifact note, and move to the next step.
+- Reserve `deepvista skill phase pause` for hard blockers only (missing
+  credentials, unavailable tools) — never for open questions.
+- Anything that would normally be sent externally (emails, invites) must
+  be left as a DRAFT for human review, never dispatched."""
+
+
+def _webhook_task_stanza(task_id: str | None) -> str:
+    """Completion contract for webhook-queued runs (DV-955).
+
+    The queue entry stays ``running`` until the host agent reports it —
+    nothing else will, so skipping this leaves a permanently stuck task.
+    """
+    task_ref = task_id or "<task_id from `deepvista task_queue list`>"
+    return f"""\
+## Webhook task completion
+
+This run came off the agent task queue. The queue entry stays `running`
+until YOU report it — after `deepvista skill complete` (or on failure):
+
+```
+deepvista task_queue complete {task_ref} --status completed
+# or, when the run could not finish:
+deepvista task_queue complete {task_ref} --status failed --note "<one short sentence>"
+```"""
+
+
 # ---------------------------------------------------------------------------
 # Phase mutators — used by host agents driving the workflow themselves
 # ---------------------------------------------------------------------------