Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Single source of truth for where the OpenCompany *application tree* lives.
The backend ships as a sibling layout that the npm tarball, a source
checkout, and the desktop app bundle all share::
<app root>/
.env.template canonical env defaults (SSOT for ports etc.)
.env operator overrides (optional)
package.json published version (``company version sync``)
.opencompany/workflows/ shipped example workflow seeds
client/dist/ built SPA the backend serves on one port
server/ this code
Historically every module that needed the root climbed
``Path(__file__).resolve().parents[N]`` on its own. That works only while
the code sits at a fixed depth inside a checkout. A desktop shell relocates
the tree into an app bundle and needs to point user-writable files (the
``.env`` overrides) somewhere the bundle is not, so the root and the two
env files are resolved *here* and nowhere else:
- ``OPENCOMPANY_APP_ROOT`` overrides :func:`app_root` (default: the
checkout root, i.e. two levels above this file).
- ``OPENCOMPANY_CLIENT_DIST`` overrides :func:`client_dist`
(default: ``<app root>/client/dist``).
- ``OPENCOMPANY_ENV_FILE`` overrides :func:`env_file_path`
(default: ``<app root>/.env``). The desktop shell points this at a file
in its writable data directory because the bundle is read-only.
- ``OPENCOMPANY_ENV_TEMPLATE`` overrides :func:`env_template_path`
(default: ``<app root>/.env.template``).
Stdlib-only and import-side-effect-free: ``core.env_defaults`` and
``core.config`` import this at module load, before logging exists, and
the stubbed-core test environment file-loads it directly.
``tests/test_no_root_climb.py`` locks the contract: no other module under
``server/`` may climb above ``server/`` with ``parents[N]`` or a
``.parent`` chain.
"""
from __future__ import annotations
import functools
import json
import os
from pathlib import Path
# server/core/approot.py -> parents[1] is server/, parents[2] is the checkout root.
_SERVER_ROOT = Path(__file__).resolve().parents[1]
_DEFAULT_APP_ROOT = _SERVER_ROOT.parent
def _env_path(name: str) -> Path | None:
raw = os.environ.get(name, "").strip()
if not raw:
return None
return Path(raw).expanduser().resolve()
def app_root() -> Path:
"""Absolute path of the application tree root (see module docstring)."""
return _env_path("OPENCOMPANY_APP_ROOT") or _DEFAULT_APP_ROOT
def server_root() -> Path:
"""Absolute path of the ``server/`` package directory.
Always the directory this code actually runs from — never derived from
:func:`app_root`, so a mis-set ``OPENCOMPANY_APP_ROOT`` cannot make the
backend look for its own config files somewhere else.
"""
return _SERVER_ROOT
def client_dist() -> Path:
"""Directory holding the built SPA (``index.html`` + ``assets/``)."""
return _env_path("OPENCOMPANY_CLIENT_DIST") or (app_root() / "client" / "dist")
def resolve_static_asset(base_dir: Path, relative: str) -> str | None:
"""Return the absolute path of ``relative`` inside ``base_dir``, or ``None``.
Built for the SPA fallback route, which maps a request path onto the
built client directory. The request path is attacker-controlled, so the
joined path is normalised with :func:`os.path.normpath` and then
required to start with the (real) base directory plus a separator; a
``..`` escape, an absolute path, or a prefix-sibling such as
``client/dist2`` all fail that test. ``None`` also covers a path that
resolves inside the directory but is not a regular file, so callers
fall through to their default (the SPA shell).
"""
if not relative:
return None
root = os.path.realpath(str(base_dir))
candidate = os.path.normpath(os.path.join(root, relative))
if not candidate.startswith(root + os.sep):
return None
if not os.path.isfile(candidate):
return None
return candidate
def is_spa_route(relative: str) -> bool:
"""True when a request path that matched no file should get the SPA shell.
The "dot rule" of connect-history-api-fallback (webpack-dev-server's SPA
fallback): a last segment with a dot names a file (a script, a
stylesheet, a stale chunk), and a missing file is a 404. Answering it with
the HTML shell gives a browser HTML under a script URL: the module is
refused ("Expected a JavaScript module script but the server responded
with a MIME type of text/html"), and a cached copy keeps failing after the
real file is back. The client has no URL routes with dots.
"""
return "." not in relative.rsplit("/", 1)[-1]
def env_template_path() -> Path:
"""The canonical ``.env.template`` (baseline for every env var)."""
return _env_path("OPENCOMPANY_ENV_TEMPLATE") or (app_root() / ".env.template")
def env_file_path() -> Path:
"""The operator's ``.env`` overrides. May not exist."""
return _env_path("OPENCOMPANY_ENV_FILE") or (app_root() / ".env")
def package_json_path() -> Path:
"""The root ``package.json`` carrying the published version."""
return app_root() / "package.json"
@functools.lru_cache(maxsize=1)
def app_version() -> str:
"""The published OpenCompany version, read from the root ``package.json``.
That file is the single source of truth (``company version sync`` writes it
from the git tag), and it ships inside the npm package one level above
``server/``. Never hardcode a literal here: ``/health`` once reported a
stale ``3.3.0`` while the package was ``0.1.1``.
"""
try:
pkg = json.loads(package_json_path().read_text(encoding="utf-8"))
return str(pkg.get("version") or "0.0.0")
except (OSError, json.JSONDecodeError):
return "0.0.0"
def example_workflows_root() -> Path:
"""Parent of the shipped seed workflows (``<app root>/.opencompany``)."""
return app_root() / ".opencompany"
__all__ = [
"app_root",
"server_root",
"client_dist",
"resolve_static_asset",
"env_template_path",
"env_file_path",
"package_json_path",
"app_version",
"example_workflows_root",
]