agent-nuvira 3.3.7 → 3.3.9

package/dist/utils/project-env.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Project interpreter canonicalization + pre-run environment guard.
+ *
+ * WHY THIS EXISTS (the live Aukat_check failure):
+ * One chat session built a macOS app by running `python3 -m venv venv` and
+ * `pip install …` against the SYSTEM interpreter, while a project virtualenv sat
+ * in the same directory. A later rebuild therefore used an interpreter that did
+ * not have the project's own dependencies, produced an app that crashed with
+ * `ModuleNotFoundError: No module named 'PyQt6'`, and the run still reported
+ * success. The root cause was not a missing dependency — it was that NOTHING
+ * pinned "which interpreter is this project's" for the run, so each command
+ * guessed and the guesses disagreed.
+ *
+ * This module makes the guess unnecessary, deterministically and LLM-free:
+ *
+ *   1. DISCOVER — find the project's virtualenv (`.venv` preferred, then
+ *      `venv`/`env`), walking up a bounded number of parent directories.
+ *   2. PIN — remember it for the whole process (keyed by directory), so every
+ *      command in the run sees the SAME interpreter.
+ *   3. APPLY — prepend its `bin/` to PATH and set `VIRTUAL_ENV`, so a bare
+ *      `python`/`pip`/`pyinstaller` resolves to the project env.
+ *   4. GUARD — refuse the two mistakes that caused the failure: installing
+ *      Python packages into an interpreter OUTSIDE the project venv, and
+ *      building/running with an interpreter that LACKS the project's declared
+ *      dependencies.
+ *
+ * All checks are best-effort: a probe failure reports, it never breaks a run.
+ * `NUVIRA_ENV_GUARD=off` disables the refusals (the escape hatch a deployment
+ * with a deliberate system-Python setup needs).
+ */
+/** A discovered project virtualenv. */
+export interface ProjectVenv {
+    /** Absolute path to the venv directory. */
+    dir: string;
+    /** Absolute path to the interpreter inside it. */
+    python: string;
+    /** `bin` (POSIX) or `Scripts` (Windows). */
+    binDir: string;
+}
+/**
+ * Find the project's virtualenv, starting at `startDir` and walking up a
+ * bounded number of parents (nearest wins, so a monorepo package's own env
+ * beats the repo root's).
+ */
+export declare function findProjectVenv(startDir: string): ProjectVenv | null;
+/** The project venv for `dir`, discovered once and reused for the run. */
+export declare function getPinnedProjectVenv(dir: string): ProjectVenv | null;
+/** Forget pinned interpreters (tests; also after creating a venv mid-run). */
+export declare function clearPinnedProjectVenv(): void;
+/** Name of the venv the sandbox creates when a project has none. */
+export declare const SANDBOX_VENV_NAME = ".venv";
+/** Injection point so tests can exercise provisioning without spawning Python. */
+export type VenvProvisioner = (dir: string) => ProjectVenv | null;
+/**
+ * Provision a project-scoped virtualenv (`C3` install sandbox).
+ *
+ * The live failure's 4th finding: a project-scoped fix mutated the machine's
+ * GLOBAL Python. Refusing such installs protects the machine but blocks the
+ * work; the better answer is to give the install a sandbox to land in. When no
+ * project venv exists, create `.venv` from the interpreter on PATH, PIN it for
+ * the run, and hand it back — so the following `pip install` populates the
+ * project env and the global interpreter is never touched.
+ *
+ * Returns null when the venv cannot be created (no base interpreter, or venv
+ * creation failed) — the caller then refuses rather than falling back to a
+ * global install.
+ */
+export declare function ensureProjectVenv(dir: string): ProjectVenv | null;
+/**
+ * Apply the pinned interpreter to a command's environment: prepend its `bin/`
+ * to PATH and set `VIRTUAL_ENV`, so a bare `python`/`pip`/`pyinstaller`
+ * resolves to the project env instead of whatever the shell would have found.
+ * A no-op when there is no venv (the environment is returned unchanged).
+ */
+export declare function applyProjectEnvironment(env: Record<string, string | undefined>, venv: ProjectVenv | null): Record<string, string | undefined>;
+/**
+ * The distribution names a project declares, from `requirements.txt`, a
+ * best-effort scan of `pyproject.toml` (PEP 621 `dependencies = [ … ]` AND
+ * poetry's `[tool.poetry.dependencies]` tables), and a `Pipfile`/`Pipfile.lock`
+ * (pipenv). Returns [] when there is nothing to check — the guard then does
+ * nothing.
+ */
+export declare function projectRequirementNames(projectDir: string): string[];
+/** Does this directory look like it declares Python dependencies? */
+export declare function hasPythonManifest(dir: string): boolean;
+/**
+ * Does any segment of this command invoke the Python toolchain? (A bare
+ * `python`/`pip`/`pyinstaller`/`pytest`, or `python -m …`.)
+ */
+export declare function isPythonToolchainCommand(command: string): boolean;
+/** Does any segment of this command install Python packages? */
+export declare function isPythonInstallCommand(command: string): boolean;
+/**
+ * Does the command name an absolute interpreter OUTSIDE the pinned venv
+ * (e.g. `/usr/local/bin/python3 -m pip install …`)? A bare `python3` does NOT
+ * count: with the venv on PATH it resolves to the project env, which is the
+ * outcome we want.
+ */
+export declare function targetsForeignInterpreter(command: string, venv: ProjectVenv | null): boolean;
+/** Probe signature — injectable so tests need no real interpreter. */
+export type EnvironmentProbe = (python: string, names: string[]) => string[];
+/**
+ * Which declared distributions are NOT installed in `python`?
+ * A probe that fails to run returns [] — an unavailable interpreter is not
+ * evidence that a dependency is missing, and the guard must never refuse on a
+ * guess.
+ */
+export declare const defaultEnvironmentProbe: EnvironmentProbe;
+/** What the guard decided for a command. */
+export type EnvironmentVerdict = {
+    action: 'not-applicable';
+} | {
+    action: 'proceed';
+    venv: ProjectVenv | null;
+    note?: string;
+} | {
+    action: 'refuse';
+    reason: string;
+    hint: string;
+};
+/** Is the guard disabled by the deployment? */
+export declare function envGuardDisabled(): boolean;
+/**
+ * Decide whether a command may run against the project's environment.
+ *
+ * Two refusals, both drawn from the live failure:
+ *   1. a Python PACKAGE INSTALL that would land outside the project venv (or
+ *      with no venv at all while the project declares dependencies);
+ *   2. a BUILD/RUN with an interpreter that is missing the project's declared
+ *      dependencies — the `PyQt6` case, caught before the build instead of
+ *      after a successful-looking bundle.
+ * Everything else proceeds, with the pinned venv applied to the environment.
+ */
+export declare function guardCommandEnvironment(command: string, cwd: string, options?: {
+    probe?: EnvironmentProbe;
+    provision?: VenvProvisioner;
+}): EnvironmentVerdict;
+/** Forget memoized probes (tests; also after an install changes the env). */
+export declare function clearEnvironmentProbeCache(): void;
+/**
+ * A one-line description of the project interpreter for the ambient project
+ * context, so the model USES the pinned env instead of re-deriving it. '' when
+ * the directory declares nothing Python.
+ */
+export declare function describeProjectInterpreter(dir: string): string;
+//# sourceMappingURL=project-env.d.ts.map

package/dist/utils/project-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-env.d.ts","sourceRoot":"","sources":["../../src/utils/project-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAoCH,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AA6BD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAoBpE;AAYD,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAWpE;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,WAAW,GAAG,IAAI,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA6BjE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,IAAI,EAAE,WAAW,GAAG,IAAI,GACvB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAapC;AA2GD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CA6CpE;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtD;AAgBD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEjE;AAKD,gEAAgE;AAChE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAW5F;AAID,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;AAmB7E;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,gBAcrC,CAAC;AAqBF,4CAA4C;AAC5C,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAC5B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,+CAA+C;AAC/C,wBAAgB,gBAAgB,IAAI,OAAO,CAG1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAAC,SAAS,CAAC,EAAE,eAAe,CAAA;CAAO,GACtE,kBAAkB,CAkEpB;AAED,6EAA6E;AAC7E,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ9D"}