Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
fix: install refuses a path that does not exist unless --create (#155)
Francois du Plessisaf555a2bbb89
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex abcc740..3133d71 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,7 @@## [Unreleased]+- **BEHAVIOR CHANGE — `install <path>` refuses a path that does not exist unless `--create` (#155, contributed by @fduple).** `hyperresearch install` and `install --steps-only` create missing parents, and with no TTY nothing stood in between, so a stale or mistyped path came back as a new empty vault with exit 0 while the real vault kept its old skills. Both now check the path before writing anything: a missing path fails with `PATH_NOT_FOUND`, and a file, as the path itself or as one of its parents, fails with `NOT_A_DIRECTORY`. `--create` makes the directory and any missing parents first (a failure there is `CREATE_FAILED`); it cannot help when a file is in the way. The check runs before the interactive setup route too, so from a terminal `install <new-dir>`, which used to open setup and create the directory, is now refused the same way; `hyperresearch setup <path>` still creates it, and setup's non-TTY / `--json` handoff to install passes `--create`. An existing directory without a vault is the normal first-time install and is unchanged, as is `--global`. Scripts that install into a directory they have not made yet need `--create`.- **The Codex Stop hook stays in the project.** A vault at the home directory (where `install` or the first-run bootstrap was run from `~`) made `<root>/.codex/hooks.json` Codex's user-level hooks file, so the stop gate ran in every Codex session. It finds a vault by walking up from the session's directory, so a home-vault run that was mid-pipeline would force-continue unrelated sessions anywhere under `~`. The hook is now skipped, with a "NOT installed" note, whenever the project's `.codex/` is `$CODEX_HOME` (default `~/.codex`). Separately, the first-run bootstrap inside a Codex session crashed with `OSError: Read-only file system`, after writing the step files, because the workspace-write sandbox keeps `.codex/` read-only. It now reports the hook as NOT installed together with the command to run outside the sandbox, and the entry skill tells the orchestrator to re-run that command once with escalated permissions.### Fixeddiff --git a/src/hyperresearch/cli/install.py b/src/hyperresearch/cli/install.pyindex 7321e41..80a6273 100644--- a/src/hyperresearch/cli/install.py+++ b/src/hyperresearch/cli/install.py@@ -10,6 +10,7 @@ from __future__ import annotationsfrom pathlib import Pathimport typer+from rich.markup import escapefrom hyperresearch.cli._output import console, outputfrom hyperresearch.models.output import error, success@@ -30,6 +31,11 @@ def install("--steps-only",help="Install only the 16 step skills to <PATH>/.claude/skills/. Used internally by the entry skill bootstrap on first /hyperresearch invocation in a project. Not normally invoked by users.",),+ create: bool = typer.Option(+ False,+ "--create",+ help="Create <PATH>, and any missing parents, if it does not exist. Without it a missing path is an error, so a stale or mistyped path cannot become a new empty vault.",+ ),profile: str | None = typer.Option(None,"--profile",@@ -91,12 +97,67 @@ def install(console.print(f"[red]Error:[/] {e}")raise typer.Exit(1)+ # A missing directory is refused before anything is written. Both the+ # steps-only and the full install create parents (the step-skill installer,+ # `Vault.init`), and with no TTY there is no setup TUI in between, so a stale+ # or mistyped path used to come back as a new empty vault with exit 0 while+ # the real vault kept its old skills. An existing directory with no+ # `.hyperresearch/` is the normal first-time install and is not affected.+ # The check sits before the interactive setup route on purpose, so a typed+ # path is refused the same way from a terminal; `hyperresearch setup <path>`+ # still creates one. A file in the way, as the path itself or as one of+ # its parents (afile/sub), is refused too, and --create cannot help there.+ # That is decided from the path before any mkdir, not from the exception a+ # mkdir under a file raises, which differs between platforms+ # (NotADirectoryError on POSIX, FileExistsError on Windows:+ # python/cpython#87038). With --create the directory is made here rather+ # than left to the installers' own mkdir(parents=True), so a failure stays+ # inside the JSON envelope.+ def _require_directory(target_path: Path) -> None:+ if target_path.is_dir():+ return+ # The nearest thing that exists on the way to the path.+ nearest = next((p for p in (target_path, *target_path.parents) if p.exists()), None)+ if nearest is not None and not nearest.is_dir():+ if nearest == target_path:+ msg = f"{target_path} is not a directory, so nothing was installed."+ else:+ msg = (+ f"{target_path} is under {nearest}, which is not a directory, "+ "so nothing was installed."+ )+ code = "NOT_A_DIRECTORY"+ elif create:+ try:+ target_path.mkdir(parents=True, exist_ok=True)+ return+ except OSError as e:+ msg = (+ f"{target_path} could not be created ({e.strerror or e}), "+ "so nothing was installed."+ )+ code = "CREATE_FAILED"+ else:+ msg = (+ f"{target_path} does not exist, so nothing was installed. Check the path, "+ "or pass --create to make the directory and install into it."+ )+ code = "PATH_NOT_FOUND"+ if json_output:+ output(error(msg, code), json_mode=True)+ else:+ # The message carries the path: escaped, or Rich reads `[x]` in it+ # as markup.+ console.print(f"[red]Error:[/] {escape(msg)}")+ raise typer.Exit(1)+# Steps-only path: lazy install of the 16 step skills to a project's# .claude/skills/ (Codex: step files in .hyperresearch/codex/steps/).# Called by the entry skill's bootstrap on first /hyperresearch in a# project (after a global install). Cheap no-op on subsequent invocations.if steps_only:target_dir = Path(path).resolve()+ _require_directory(target_dir)steps_config = target_dir / ".hyperresearch" / "config.toml"steps_config_path = steps_config if steps_config.exists() else Nonesteps_profile = _default_profile(steps_config_path)@@ -202,6 +263,7 @@ def install(returnroot = Path(path).resolve()+ _require_directory(root)# First-time install in an interactive terminal → run the setup TUI instead# (The setup TUI configures a Claude Code install; other targets skip it.)diff --git a/src/hyperresearch/cli/setup.py b/src/hyperresearch/cli/setup.pyindex 8ffbf6a..9262039 100644--- a/src/hyperresearch/cli/setup.py+++ b/src/hyperresearch/cli/setup.py@@ -23,7 +23,9 @@ def setup(if json_output or not sys.stdin.isatty():import subprocess- cmd = [sys.executable, "-m", "hyperresearch", "install", path]+ # `setup <path>` makes the directory when it runs interactively, so+ # it asks install to as well rather than meet its missing-path refusal.+ cmd = [sys.executable, "-m", "hyperresearch", "install", path, "--create"]if json_output:cmd.append("--json")raise typer.Exit(subprocess.call(cmd))diff --git a/tests/test_cli/test_install_codex.py b/tests/test_cli/test_install_codex.pyindex 35f0ae1..01448dc 100644--- a/tests/test_cli/test_install_codex.py+++ b/tests/test_cli/test_install_codex.py@@ -43,6 +43,7 @@ def test_install_target_codex(tmp_vault, monkeypatch):def test_codex_only_install_on_fresh_dir_writes_no_claude_files(tmp_path, monkeypatch):root = tmp_path / "fresh"+ root.mkdir()monkeypatch.chdir(tmp_path)result = runner.invoke(app, ["install", str(root), "--target", "codex", "--json"])assert result.exit_code == 0, result.stdout@@ -54,6 +55,7 @@ def test_codex_only_install_on_fresh_dir_writes_no_claude_files(tmp_path, monkeydef test_fresh_all_install_writes_both_docs(tmp_path, monkeypatch):root = tmp_path / "fresh"+ root.mkdir()monkeypatch.chdir(tmp_path)result = runner.invoke(app, ["install", str(root), "--target", "all", "--json"])assert result.exit_code == 0, result.stdoutdiff --git a/tests/test_cli/test_install_missing_path.py b/tests/test_cli/test_install_missing_path.pynew file mode 100644index 0000000..917c83a--- /dev/null+++ b/tests/test_cli/test_install_missing_path.py@@ -0,0 +1,246 @@+"""`hyperresearch install <path>` must not turn a missing path into a vault.++With no TTY (every agent session) install skips the setup TUI and falls through+to `Vault.init`, which creates parents. A stale or mistyped path then became a+new empty vault with exit 0, and the real vault kept its stale skills.+"""++from __future__ import annotations++import io+import json+import os+from pathlib import Path++import pytest+import typer+from typer.testing import CliRunner++from hyperresearch.cli import app++runner = CliRunner()+++def test_install_refuses_a_missing_path(tmp_path: Path, monkeypatch):+ monkeypatch.chdir(tmp_path)+ missing = tmp_path / "renamed-away" / "vault"++ result = runner.invoke(app, ["install", str(missing), "--json"])++ assert result.exit_code == 1+ payload = json.loads(result.output)+ assert payload["error_code"] == "PATH_NOT_FOUND"+ assert "--create" in payload["error"]+ # The refusal is only worth anything if nothing was written.+ assert not missing.exists()+ assert not missing.parent.exists()+++def test_install_refuses_a_missing_path_on_the_console(tmp_path: Path, monkeypatch):+ """The refusal is not a --json feature: the console branch exits 1 with the+ same message and writes nothing either."""+ monkeypatch.chdir(tmp_path)+ missing = tmp_path / "renamed-away"++ result = runner.invoke(app, ["install", str(missing)])++ assert result.exit_code == 1+ out = " ".join(result.output.split())+ assert "Error:" in out+ assert "does not exist" in out+ assert "--create" in out+ assert not missing.exists()++[email protected]("name", ["[old] notes", "notes [/old]"], ids=["open-tag", "close-tag"])+def test_install_refusal_keeps_square_brackets_in_the_path(tmp_path: Path, monkeypatch, name):+ """The console line goes through Rich, which reads `[old]` in the path as+ markup and drops it from the message, and raises MarkupError on a `[/old]`+ that closes nothing, where the refusal should print."""+ monkeypatch.chdir(tmp_path)+ missing = tmp_path / name++ result = runner.invoke(app, ["install", str(missing)])++ assert result.exit_code == 1+ assert result.exception is None or isinstance(result.exception, SystemExit), result.exception+ # The console folds a long path, so compare with all whitespace removed.+ out = "".join(result.output.split())+ assert "".join(str(Path(name)).split()) in out+ assert "doesnotexist" in out+ assert not missing.exists()++[email protected]("extra", [[], ["--create"]], ids=["plain", "create"])+def test_install_refuses_a_path_that_is_a_file(tmp_path: Path, monkeypatch, extra):+ """A regular file is not a directory to install into, and --create cannot+ make it one. The refusal must be the structured kind, not a traceback from+ `mkdir(parents=True)` under the file."""+ monkeypatch.chdir(tmp_path)+ afile = tmp_path / "notes.md"+ afile.write_text("keep me", encoding="utf-8")++ result = runner.invoke(app, ["install", str(afile), *extra, "--json"])++ assert result.exit_code == 1+ assert result.output.startswith("{"), result.output+ payload = json.loads(result.output)+ assert payload["error_code"] == "NOT_A_DIRECTORY"+ assert "not a directory" in payload["error"]+ assert afile.read_text(encoding="utf-8") == "keep me"+ assert sorted(p.name for p in tmp_path.iterdir()) == ["notes.md"]+++ "extra",+ [["--create"], ["--create", "--steps-only"], []],+ ids=["full", "steps-only", "plain"],+)+def test_install_refuses_a_file_as_a_parent(tmp_path: Path, monkeypatch, extra):+ """A file in the way of the path is refused with the same structured error,+ with `--create` and without it (where "pass --create" would be a false+ hint). The refusal is decided from the path, so no mkdir is attempted: the+ exception a mkdir under a file raises differs between platforms."""+ monkeypatch.chdir(tmp_path)+ afile = tmp_path / "notes.md"+ afile.write_text("keep me", encoding="utf-8")+ made: list[str] = []+ real_mkdir = os.mkdir++ def spy_mkdir(path, *args, **kwargs):+ made.append(os.fspath(path))+ return real_mkdir(path, *args, **kwargs)++ monkeypatch.setattr(os, "mkdir", spy_mkdir)++ result = runner.invoke(app, ["install", str(afile / "sub"), *extra, "--json"])++ assert result.exit_code == 1+ assert result.output.startswith("{"), result.output+ payload = json.loads(result.output)+ assert payload["error_code"] == "NOT_A_DIRECTORY"+ assert "not a directory" in payload["error"]+ assert "--create" not in payload["error"]+ assert made == []+ assert afile.read_text(encoding="utf-8") == "keep me"+ assert sorted(p.name for p in tmp_path.iterdir()) == ["notes.md"]+++def test_install_steps_only_refuses_a_missing_path(tmp_path: Path, monkeypatch):+ """Same shape on the bootstrap branch: it creates `.claude/skills` with+ parents, so a missing target became a directory holding only step skills."""+ monkeypatch.chdir(tmp_path)+ missing = tmp_path / "renamed-away"++ result = runner.invoke(app, ["install", str(missing), "--steps-only", "--json"])++ assert result.exit_code == 1+ assert json.loads(result.output)["error_code"] == "PATH_NOT_FOUND"+ assert not missing.exists()+++def test_install_create_flag_makes_the_directory(tmp_path: Path, monkeypatch):+ """Parents included: both levels are missing here."""+ monkeypatch.chdir(tmp_path)+ fresh = tmp_path / "new-parent" / "new-project"++ result = runner.invoke(app, ["install", str(fresh), "--create", "--json"])++ assert result.exit_code == 0+ assert json.loads(result.output)["data"]["vault"] == "created"+ assert (fresh / ".hyperresearch").is_dir()+++def test_install_create_reports_any_other_mkdir_error(tmp_path: Path, monkeypatch):+ """A read-only parent, a full disk: whatever else the mkdir raises comes+ back in the envelope as CREATE_FAILED with the OS message, not as a+ traceback."""+ monkeypatch.chdir(tmp_path)+ fresh = tmp_path / "new-project"++ def refuse(self, *args, **kwargs):+ raise PermissionError(13, "Permission denied", str(self))++ monkeypatch.setattr(Path, "mkdir", refuse)++ result = runner.invoke(app, ["install", str(fresh), "--create", "--json"])++ assert result.exit_code == 1+ assert result.output.startswith("{"), result.output+ payload = json.loads(result.output)+ assert payload["error_code"] == "CREATE_FAILED"+ assert "Permission denied" in payload["error"]+ assert not fresh.exists()+++class _Terminal(io.StringIO):+ """Stdin that says it is a terminal, which is what routes a first-time+ install into the setup TUI."""++ def isatty(self) -> bool:+ return True+++def test_install_refuses_a_missing_path_at_a_terminal(tmp_path: Path, monkeypatch, capsys):+ """The check comes before the route into the setup TUI, so a mistyped path+ is refused at a terminal too and the TUI, which would create it, never+ opens. Called directly: the test runner replaces stdin with one that is+ not a terminal."""+ from hyperresearch.cli.install import install++ monkeypatch.chdir(tmp_path)+ opened = []+ monkeypatch.setattr("hyperresearch.cli.setup.setup", lambda **kwargs: opened.append(kwargs))+ monkeypatch.setattr("sys.stdin", _Terminal())+ missing = tmp_path / "renamed-away"++ with pytest.raises(typer.Exit) as refused:+ install(+ path=str(missing),+ name="Research Base",+ json_output=False,+ global_install=False,+ steps_only=False,+ create=False,+ profile=None,+ target="claude",+ )++ assert refused.value.exit_code == 1+ assert opened == []+ assert "does not exist" in " ".join(capsys.readouterr().out.split())+ assert not missing.exists()+++def test_install_in_an_existing_empty_directory_still_creates(tmp_path: Path, monkeypatch):+ """The documented first-time flow (`cd <new-project> && hyperresearch install .`)+ hands install a directory that exists and holds no vault. The guard is+ about the directory, not about `.hyperresearch/`, so this needs no flag."""+ fresh = tmp_path / "new-project"+ fresh.mkdir()+ monkeypatch.chdir(fresh)++ result = runner.invoke(app, ["install", ".", "--json"])++ assert result.exit_code == 0+ assert json.loads(result.output)["data"]["vault"] == "created"+ assert (fresh / ".hyperresearch").is_dir()++[email protected]("args", [[], ["--json"]], ids=["no-tty", "json"])+def test_setup_without_a_terminal_still_makes_its_directory(tmp_path: Path, monkeypatch, args):+ """Interactive `setup <path>` creates the path, and without a terminal it+ hands off to install, so it passes --create rather than get a refusal+ that names an option `setup` does not have."""+ import subprocess++ monkeypatch.chdir(tmp_path)+ calls: list[list[str]] = []+ monkeypatch.setattr(subprocess, "call", lambda cmd: calls.append(cmd) or 0)+ target = str(tmp_path / "new-vault")++ result = runner.invoke(app, ["setup", target, *args], input="")++ assert result.exit_code == 0+ assert len(calls) == 1+ assert calls[0][-len(args) - 3 :] == ["install", target, "--create", *args]