Skip to content

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

fix: install refuses a path that does not exist unless --create (#155)

Francois du Plessisaf555a2bbb89
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.
### Fixed
diff --git a/src/hyperresearch/cli/install.py b/src/hyperresearch/cli/install.py
index 7321e41..80a6273 100644
--- a/src/hyperresearch/cli/install.py
+++ b/src/hyperresearch/cli/install.py
@@ -10,6 +10,7 @@ from __future__ import annotations
from pathlib import Path
import typer
+from rich.markup import escape
from hyperresearch.cli._output import console, output
from 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 None
steps_profile = _default_profile(steps_config_path)
@@ -202,6 +263,7 @@ def install(
return
root = 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.py
index 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.py
index 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, monkey
def 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.stdout
diff --git a/tests/test_cli/test_install_missing_path.py b/tests/test_cli/test_install_missing_path.py
new file mode 100644
index 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]