@cruxy/cli 1.0.3 → 1.0.5

package/dist/vcs/types.d.ts

@@ -1,73 +0,0 @@
-/**
- * Version-control / forge types for PR generation (C.15). The {@link ForgeProvider}
- * interface is the swap seam — GitHub ships first, GitLab/Bitbucket slot in later
- * without touching call sites (same discipline as `VectorStore`/`Embedder`).
- */
-/**
- * The forge-target identity parsed from the `origin` remote — just host/owner/repo,
- * no network lookup. This is the value the C.26 Step-4 wrong-repo guard compares
- * across the preview→API-call window (see {@link ForgeProvider.resolveRepoIdentity}).
- */
-export interface RepoIdentity {
-    /** Forge host, e.g. `github.com`. */
-    readonly host: string;
-    /** Repository owner (user or org). */
-    readonly owner: string;
-    /** Repository name (no `.git` suffix). */
-    readonly repo: string;
-}
-/** Where a repository lives and who owns it, parsed from the `origin` remote. */
-export interface RepoInfo extends RepoIdentity {
-    /** Default branch, when the provider can resolve it (PR base fallback). */
-    readonly defaultBranch?: string;
-}
-/** Everything needed to open one pull request. */
-export interface PullRequestSpec {
-    readonly title: string;
-    readonly body: string;
-    /** The branch carrying the change. */
-    readonly head: string;
-    /** The branch to merge into. */
-    readonly base: string;
-    readonly draft?: boolean;
-}
-/** The outcome of opening (or finding an already-open) pull request. */
-export interface PullRequestResult {
-    readonly url: string;
-    readonly number: number;
-    /** True when a PR for this head already existed and we returned it. */
-    readonly alreadyExists: boolean;
-}
-/**
- * An abstract forge. The orchestrator depends only on this; the concrete
- * GitHub/GitLab implementation is chosen by {@link createForgeProvider}.
- */
-export interface ForgeProvider {
-    /** Stable id, e.g. `"github"`. */
-    readonly id: string;
-    /** Parse the repository's `origin` remote into structured {@link RepoInfo}. */
-    getRepoInfo(cwd: string): Promise<RepoInfo>;
-    /**
-     * Re-parse just the `origin` remote's {@link RepoIdentity} — LOCAL only, no
-     * network. The C.26 Step-4 wrong-repo guard calls this immediately before the
-     * pull-request API call and compares it against the identity shown at approval;
-     * a mismatch (a mid-run `git remote set-url`) refuses the PR. It stays local so
-     * the re-check is cheap and cannot fail on a network hiccup. Throws the same
-     * coded usage errors as {@link getRepoInfo} when there is no parseable `origin`.
-     */
-    resolveRepoIdentity(cwd: string): RepoIdentity;
-    /** Open a pull request and return its URL (idempotent on already-exists). */
-    createPullRequest(repo: RepoInfo, spec: PullRequestSpec): Promise<PullRequestResult>;
-}
-/**
- * The full set of fields a PR publish needs, produced by `generate.ts`. The
- * commit subject and PR title are the same conventional-commit line; the bodies
- * may differ (the PR body is the richer, structured summary).
- */
-export interface GeneratedContent {
-    readonly branchName: string;
-    readonly commitSubject: string;
-    readonly commitBody: string;
-    readonly prTitle: string;
-    readonly prBody: string;
-}

package/dist/web/demarcate.d.ts

@@ -1,13 +0,0 @@
-import type { SearchResult } from "./types.js";
-/**
- * Wrap a list of already-bounded search results as untrusted data for the model.
- * Each field (title/url/snippet) is sanitized; the whole block is fenced so the
- * model treats it as reference data, never commands.
- */
-export declare function demarcateSearchResults(query: string, results: SearchResult[]): string;
-/**
- * Wrap a fetched page's text as untrusted data for the model. Same discipline as
- * search results: sanitized, fence-neutralized, and clearly boxed as data. The
- * caller passes the FINAL url (post-redirect) and any truncation note.
- */
-export declare function demarcatePage(url: string, rawText: string, note?: string): string;

package/dist/web/fetch.d.ts

@@ -1,11 +0,0 @@
-import type { FetchResult, WebConfig, WebDeps } from "./types.js";
-/**
- * Fetch one URL as text, enforcing every bound. Returns a {@link FetchResult}.
- * Throws {@link webBlockedHost} for an SSRF-refused URL (never dispatched),
- * {@link webFetchFailed} for a network error / timeout / non-text or over-redirect
- * response. A page fetched successfully but empty of text is a valid result with
- * empty `text` (the tool surfaces it as `ok:true`, not an error).
- */
-export declare function fetchUrl(rawUrl: string, config: WebConfig, deps?: WebDeps): Promise<FetchResult>;
-/** Fetch a URL and render it as a demarcated, scrubbed, untrusted-data block. */
-export declare function runWebFetch(rawUrl: string, config: WebConfig, deps?: WebDeps): Promise<string>;

package/dist/web/index.d.ts

@@ -1,7 +0,0 @@
-export * from "./types.js";
-export * from "./provider.js";
-export * from "./search.js";
-export * from "./fetch.js";
-export * from "./ssrf.js";
-export * from "./demarcate.js";
-export * from "./tools.js";

package/dist/web/provider.d.ts

@@ -1,29 +0,0 @@
-import type { SearchProvider, SearchResult, WebConfig, WebDeps } from "./types.js";
-/**
- * Search-provider seam (C.20). `createSearchProvider` resolves the configured
- * backend and its API key. There is no gateway search endpoint today (the SDK
- * Provider only streams chat), so the direct Tavily provider sits behind the seam;
- * a gateway-backed provider would slot in here with no change to the tools.
- *
- * A missing key or unknown provider throws {@link webUnavailable} — a coded,
- * actionable failure, NEVER a silent empty result (the honesty rule: "no provider"
- * must not read as "no results").
- */
-export declare function createSearchProvider(config: WebConfig, deps?: WebDeps): SearchProvider;
-/**
- * Tavily direct provider. The API key travels ONLY in the `Authorization` header
- * (never in the query text or URL, never logged), so the outbound query carries no
- * secret. Any non-2xx / network / timeout outcome becomes a thrown
- * {@link webSearchFailed}; an empty `results` array is a legitimate zero-result
- * outcome and is returned as `[]` (the tool renders "no results" as `ok:true`).
- */
-export declare class TavilyProvider implements SearchProvider {
-    private readonly apiKey;
-    private readonly fetchImpl;
-    readonly name = "tavily";
-    constructor(apiKey: string, fetchImpl: typeof fetch);
-    search(query: string, opts: {
-        maxResults: number;
-        signal: AbortSignal;
-    }): Promise<SearchResult[]>;
-}

package/dist/web/search.d.ts

@@ -1,17 +0,0 @@
-import type { SearchResult, WebConfig, WebDeps } from "./types.js";
-/**
- * Apply the top-N and per-snippet caps. The provider is asked for `maxResults`,
- * but we re-cap defensively (a provider may over-return) and truncate each snippet
- * with a visible marker so a long body can't blow the context budget.
- */
-export declare function boundResults(results: SearchResult[], config: WebConfig): SearchResult[];
-/**
- * Run one web search and return the demarcated, bounded, scrubbed result block.
- *
- * Throws coded errors for the two failure modes the caller must NOT collapse into
- * an empty result: {@link webUnavailable} (no provider/key — via
- * `createSearchProvider`) and {@link webSearchFailed} (the search errored — via the
- * provider). A search that runs and finds nothing returns a demarcated "(no
- * results)" block — an ordinary success the tool surfaces as `ok:true`.
- */
-export declare function runWebSearch(query: string, config: WebConfig, deps?: WebDeps): Promise<string>;

package/dist/web/ssrf.d.ts

@@ -1,41 +0,0 @@
-import { type Dispatcher } from "undici";
-import type { HostResolver } from "./types.js";
-/**
- * SSRF guard (C.20). A URL the MODEL chose must not be able to reach the user's
- * internal network, cloud metadata service, or loopback interface. Three layers:
- *
- * 1. Scheme allowlist — only `http`/`https` (blocks `file:`, `data:`, `gopher:`…).
- * 2. Address check — the hostname is RESOLVED and every returned address is
- *    checked against private/loopback/link-local/reserved ranges (v4 and v6,
- *    including IPv4-mapped and alternate IP encodings).
- * 3. Connection pinning — the connection is pinned to the exact address the check
- *    validated (see {@link createPinnedDispatcher}). Without this, resolving-then-
- *    fetching re-resolves the hostname at connect time, so a DNS-rebind attacker
- *    can pass the check with a public IP and have the socket land on 127.0.0.1
- *    (a TOCTOU hole). Pinning closes it: the connection can only reach a validated
- *    address, and the host header / TLS SNI still carry the original hostname.
- *
- * The check runs BEFORE any request is dispatched, and again on every redirect hop
- * (see fetch.ts). A block is a security refusal, distinct from a network failure.
- *
- * The IP range math, the pin shim, and the error types now live in the shared
- * {@link ../net/ip-guard ip-guard} module (JC-A) — the ONE owner of "is this IP
- * allowed"; this file keeps only the web-specific policy (scheme + the
- * `allowPrivateHosts` escape hatch) and the web one-shot dispatcher.
- */
-export { BlockedHostError, HostUnresolvedError, isBlockedAddress, defaultResolveHost, pinnedLookup, } from "../net/ip-guard.js";
-/** An undici dispatcher whose connections are pinned to `addresses`. */
-export declare function createPinnedDispatcher(addresses: string[]): Dispatcher;
-/**
- * Assert that `url` may be fetched and return the validated addresses to pin the
- * connection to. Throws {@link BlockedHostError} for a bad scheme or a host
- * resolving into a blocked range, or `HostUnresolvedError` if the host cannot be
- * resolved.
- *
- * The returned list is the exact set of addresses the caller must restrict the
- * connection to (via {@link createPinnedDispatcher}). An empty list means "do not
- * pin" — only returned under `allowPrivate`, the deliberate internal-network escape
- * hatch (from `web.allowPrivateHosts`), which bypasses the address check and lets
- * the transport resolve normally. The scheme check always applies.
- */
-export declare function assertFetchable(url: URL, resolveHost: HostResolver, allowPrivate: boolean): Promise<string[]>;

package/dist/web/tools.d.ts

@@ -1,20 +0,0 @@
-import { z } from "zod";
-import type { Tool } from "../tools/types.js";
-import type { WebDeps } from "./types.js";
-declare const searchParams: z.ZodObject<{
-    query: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-}, {
-    query: string;
-}>;
-export declare function createWebSearchTool(deps?: WebDeps): Tool<typeof searchParams>;
-declare const fetchParams: z.ZodObject<{
-    url: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    url: string;
-}, {
-    url: string;
-}>;
-export declare function createWebFetchTool(deps?: WebDeps): Tool<typeof fetchParams>;
-export {};

package/dist/web/types.d.ts

@@ -1,64 +0,0 @@
-import type { HostResolver } from "../net/ip-guard.js";
-import type { WebConfig } from "../config/index.js";
-/**
- * Web subtool seams + shapes (C.20). Everything the `web_search`/`web_fetch`
- * tools touch is defined here so the injectable dependencies (HTTP, DNS) have one
- * home and tests can substitute them without patching globals.
- */
-/** One ranked search hit — the only fields we surface to the model. */
-export interface SearchResult {
-    title: string;
-    url: string;
-    snippet: string;
-}
-/** The outcome of reading a single URL as text. */
-export interface FetchResult {
-    /** The final URL actually read (after any followed, re-validated redirects). */
-    url: string;
-    /** The response's declared content type (lower-cased, params stripped). */
-    contentType: string;
-    /** The decoded, size-capped body text. */
-    text: string;
-    /** True when the body was truncated at the byte cap. */
-    truncated: boolean;
-}
-/**
- * The swappable search backend. A direct provider (Tavily) implements this today;
- * a gateway-backed provider would implement the SAME interface if the backend ever
- * proxies search. Implementations translate provider errors into thrown
- * {@link CruxyError}s (never a silent empty) — the tool layer owns the honesty
- * split between "search failed" and "search found nothing".
- */
-export interface SearchProvider {
-    /** Stable id for logging/tests (e.g. "tavily"). */
-    readonly name: string;
-    /**
-     * Run one query. Returns the provider's results (the tool applies the top-N and
-     * snippet caps). Throws on provider/network/timeout failure. An empty array is a
-     * legitimate "no results" — NOT an error.
-     */
-    search(query: string, opts: {
-        maxResults: number;
-        signal: AbortSignal;
-    }): Promise<SearchResult[]>;
-}
-/**
- * Resolve a hostname to its IP addresses. Injected so the SSRF guard can be tested
- * deterministically (a hostname that "resolves" to an internal IP) without real
- * DNS. Owned by the shared {@link ../net/ip-guard ip-guard} module (JC-A) and
- * re-exported here for web importers.
- */
-export type { HostResolver } from "../net/ip-guard.js";
-/**
- * Injectable dependencies for the web tools. Defaults wire the real `fetch` and
- * DNS; tests pass spies/fakes. No global is ever patched.
- */
-export interface WebDeps {
-    /** HTTP transport (default: global `fetch`). */
-    fetchImpl?: typeof fetch;
-    /** DNS resolver used by the SSRF guard (default: `dns.lookup`, all addresses). */
-    resolveHost?: HostResolver;
-    /** Read the provider API key from the environment (default: `process.env`). */
-    env?: NodeJS.ProcessEnv;
-}
-export type { WebConfig };

package/dist/workspace/add-root.d.ts

@@ -1,27 +0,0 @@
-import type { RootSpec } from "./types.js";
-import { Workspace } from "./workspace.js";
-/**
- * The interactive add-root path (C.26 step 5). Adding a workspace root is an
- * EXPLICIT HUMAN act — it grows the trust surface (a new root can carry its own
- * hooks / MCP / project memory), so it is:
- *
- *   - reachable ONLY from the REPL command and the CLI, never as a model tool.
- *     The model can act only through the tool registry (`registry.get(name)`),
- *     and no tool is registered for this — the allowlist argument is unchanged.
- *   - TTY-only: refused (coded) when there is no interactive human to vouch.
- *   - held to the SAME validation as `--root`: the new root must exist, be a
- *     directory, have a unique name, and NOT nest/overlap an existing root
- *     (CRUXY_E_ROOT_OVERLAP) — reusing {@link buildWorkspace}, the single
- *     Workspace constructor from user input.
- *
- * Returns the NEW immutable Workspace (the root set only ever grows by
- * constructing a new one). A freshly added root starts UNTRUSTED; its hooks and
- * project memory stay inert until explicitly trusted.
- */
-export interface AddRootOptions {
-    /** Base dir for resolving a relative `path` (the session's primary root). */
-    cwd: string;
-    /** Whether stdin is a TTY — add-root is refused without an interactive human. */
-    tty: boolean;
-}
-export declare function addRootToWorkspace(current: Workspace, spec: RootSpec, opts: AddRootOptions): Promise<Workspace>;

package/dist/workspace/index.d.ts

@@ -1,6 +0,0 @@
-export type { DeclaredRoot, RootSpec } from "./types.js";
-export { Workspace, buildWorkspace, sessionWorkspace } from "./workspace.js";
-export { PathEscapeError, confineToRoot, isInside, resolveInWorkspace, } from "./resolve.js";
-export { selectRoot } from "./select.js";
-export type { RootRef, SelectedRoot } from "./select.js";
-export { addRootToWorkspace, type AddRootOptions } from "./add-root.js";

package/dist/workspace/resolve.d.ts

@@ -1,54 +0,0 @@
-import { CruxyError } from "../errors/index.js";
-import type { Workspace } from "./workspace.js";
-/**
- * The single path-confinement funnel for the whole CLI (C.26). Two things live
- * here so there is exactly ONE confinement implementation, not several:
- *   • {@link confineToRoot} — the pure 2-layer check (lexical + symlink) against
- *     ONE root. It never sees any other root, which is the structural argument
- *     that a validated target can't cross into a sibling root.
- *   • {@link resolveInWorkspace} — select the one named root, then confine to it.
- */
-/**
- * Thrown when a tool argument resolves to a path outside the root it is acting in
- * — via `../` traversal, an absolute path, an outward symlink, OR a path that
- * lands in a *different* declared root. A cross-root path is deliberately the
- * SAME error as any other escape (R2): a distinct code would wrongly imply
- * "less bad". A {@link CruxyError} (code CRUXY_E_PATH_ESCAPE) so it carries a code
- * if it reaches the boundary; tools still catch it and surface `{ ok:false }`.
- */
-export declare class PathEscapeError extends CruxyError {
-    constructor(message: string);
-}
-/** Is `target` the root itself or a descendant of it? */
-export declare function isInside(root: string, target: string): boolean;
-/**
- * Resolve `p` against a SINGLE root and prove it stays inside — the pure kernel
- * every file tool ultimately funnels through.
- *
- * Two layers: (1) a lexical check that the resolved absolute path is within root
- * (rejects `../` and absolute-outside before touching the FS); (2) a symlink
- * check that the real target — or, for a new path, its nearest existing parent —
- * resolves inside the *real* root. The root is realpath'd too, so this is correct
- * even when the root itself sits under a symlink (macOS `/var → /private/var`).
- *
- * Crucially, this function is a pure function of `(one root, the path)`. The rest
- * of the declared root set is NOT in scope here, so there is no code path by
- * which a target validated against this root can be accepted into another root.
- *
- * @returns the resolved absolute path (lexical, not realpath'd — so callers
- *   operate on the intended location).
- * @throws {PathEscapeError} if the path escapes the root.
- */
-export declare function confineToRoot(rootAbsPath: string, p: string): Promise<string>;
-/**
- * Resolve a tool-supplied path against ONE named root of the workspace and prove
- * it stays inside that root. Selection happens first (by exact name — see
- * {@link Workspace.rootByName}, which fail-loud refuses an unknown name), and
- * confinement runs against only that one root's path. A `../otherRoot/x` that
- * would land in a sibling declared root is refused exactly as any escape is (R2),
- * because {@link confineToRoot} is only ever handed this one root.
- *
- * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN if `rootName` is not declared.
- * @throws {PathEscapeError} if `p` escapes the selected root.
- */
-export declare function resolveInWorkspace(ws: Workspace, rootName: string, p: string): Promise<string>;

package/dist/workspace/select.d.ts

@@ -1,41 +0,0 @@
-import type { DeclaredRoot } from "./types.js";
-import type { Workspace } from "./workspace.js";
-/**
- * How a tool call addresses a workspace root (C.26, R1). Either an explicit `root`
- * name plus a root-relative `path`, or just a `path` that may carry a leading
- * root-name segment. Bare relative paths fall back to the primary root; absolute
- * paths select the unique root that contains them.
- */
-export interface RootRef {
-    /** Explicit root name (`root: "service"`). Wins over any name in `path`. */
-    readonly root?: string;
-    /** The path argument (root-relative, name-prefixed, or absolute). */
-    readonly path: string;
-}
-/** The outcome of resolving a {@link RootRef}: the chosen root + a path within it. */
-export interface SelectedRoot {
-    readonly root: DeclaredRoot;
-    /** The path to hand to `confineToRoot` (root-relative or absolute-inside). */
-    readonly relPath: string;
-}
-/**
- * Resolve a {@link RootRef} to exactly one declared root and a path within it —
- * the selection half of confinement, run BEFORE any resolution so a call always
- * commits to a single root first (§1.1). Precedence:
- *
- *   1. explicit `root` name → that root, exactly (fail-loud on unknown name);
- *   2. absolute `path` → the unique declared root containing it (fail-loud on
- *      unknown / — defensively — ambiguous);
- *   3. `path` whose first segment exactly matches a declared root name → that
- *      root, with the segment stripped (only when the name is unambiguous);
- *   4. bare relative `path` → the primary root.
- *
- * `requireExplicit` (set by mutating tools per ⚖︎#3) refuses the case-4 default
- * in a multi-root session: a write must NAME its root rather than silently land
- * in the primary. Read/enumeration tools leave it false.
- *
- * @throws CRUXY_E_ROOT_UNKNOWN / CRUXY_E_ROOT_AMBIGUOUS per the rules above.
- */
-export declare function selectRoot(ws: Workspace, ref: RootRef, opts?: {
-    requireExplicit?: boolean;
-}): SelectedRoot;

package/dist/workspace/types.d.ts

@@ -1,30 +0,0 @@
-/**
- * Multi-repo workspace model (C.26). A session may operate across N repo/package
- * roots. The {@link Workspace} is the single value that carries the declared root
- * set; every path-taking tool resolves *through* it rather than through a bare
- * `cwd` string.
- *
- * Two invariants the type system helps enforce:
- *   • The root set is **immutable for the session** — a {@link Workspace} exposes
- *     no mutator, so nothing the model can call adds a root. The set only grows by
- *     the CLI constructing a *new* Workspace from an explicit human act (argv, or
- *     an interactive add-root that prompts + trusts first).
- *   • Roots are addressed by a stable **name** (R1), matched **exactly** — never
- *     by prefix or nearest-match. An unknown name is a fail-loud refusal.
- */
-/** One declared workspace root: a stable name + its resolved absolute path. */
-export interface DeclaredRoot {
-    /** Stable, user-facing identifier (assigned at declaration, unique per session). */
-    readonly name: string;
-    /** Absolute, lexically-resolved path (realpath is applied at confinement time). */
-    readonly absPath: string;
-    /** Exactly one root is primary — the default for bare relative paths + git info. */
-    readonly primary: boolean;
-}
-/** A root as declared on the CLI (or interactively), before resolution/validation. */
-export interface RootSpec {
-    /** Explicit name (`--root name=path`); defaults to a deduped basename of `path`. */
-    readonly name?: string;
-    /** Path as supplied (resolved against `process.cwd()` by `buildWorkspace`). */
-    readonly path: string;
-}

package/dist/workspace/workspace.d.ts

@@ -1,61 +0,0 @@
-import type { DeclaredRoot, RootSpec } from "./types.js";
-/**
- * The declared workspace root set for a session (C.26). Immutable by design: it
- * exposes readers only, no mutator. The root set grows solely by the CLI building
- * a *new* Workspace from an explicit human act — so no tool, and nothing the model
- * emits, can add a root. Roots are addressed by exact name (R1).
- */
-export declare class Workspace {
-    private readonly rootsByName;
-    private readonly ordered;
-    private readonly primaryRoot;
-    constructor(roots: readonly DeclaredRoot[]);
-    /** All declared roots, in declaration order. */
-    roots(): readonly DeclaredRoot[];
-    /** The primary root — the default for bare relative paths and git/instructions. */
-    primary(): DeclaredRoot;
-    /** True when more than one root is declared (i.e. a genuine multi-repo session). */
-    get isMultiRoot(): boolean;
-    /**
-     * Look up a root by EXACT name (R1). Never fuzzy-, prefix-, or nearest-matched
-     * — a silent near-match would be a cross-root misfire.
-     * @throws {CruxyError} CRUXY_E_ROOT_UNKNOWN if no root has that exact name.
-     */
-    rootByName(name: string): DeclaredRoot;
-    /** Like {@link rootByName} but returns undefined instead of throwing. */
-    tryRootByName(name: string): DeclaredRoot | undefined;
-    /**
-     * The single declared root that contains `absPath`. Roots never overlap (that's
-     * refused at declaration), so at most one can match.
-     * @throws CRUXY_E_ROOT_UNKNOWN if the path is inside no declared root.
-     * @throws CRUXY_E_ROOT_AMBIGUOUS if — defensively — it matches more than one.
-     */
-    rootContaining(absPath: string): DeclaredRoot;
-}
-/**
- * Build a {@link Workspace} from declared specs (R1, ⚖︎#5). Each path is resolved
- * against `process.cwd()`, must exist and be a directory, and the set must not
- * overlap (a root nested in / equal to another is refused — declare the monorepo
- * root OR its packages, never both). The first spec is primary unless one is
- * marked. Names are explicit-or-basename, validated, and deduped.
- *
- * This is the ONLY constructor of a Workspace from user input; it is called by the
- * CLI from argv and by the interactive add-root path — never from a tool.
- *
- * @throws CRUXY_E_ROOT_OVERLAP on a nested/overlapping/duplicate root.
- * @throws CRUXY_E_USAGE on a missing path, non-directory, or bad/duplicate name.
- */
-export declare function buildWorkspace(specs: readonly RootSpec[], opts?: {
-    cwd?: string;
-}): Promise<Workspace>;
-/**
- * Build THE session's workspace from a single absolute path — the trivial
- * single-root case. This is a *session construction* primitive, not a per-call
- * fallback: after C.26 Step 6 it is called ONLY at the two CLI entry points that
- * turn argv into a session (`cli/commands/run.ts`, `cli/onboard.ts`), never in the
- * middle of a subsystem. Synthesizing one elsewhere would silently scope that
- * subsystem to its own cwd while the fan tools see N roots (a split-brain) — the
- * `no-split-brain` guard fails on any `sessionWorkspace(` outside those two files.
- * The one root is primary and named by its basename.
- */
-export declare function sessionWorkspace(absPath: string): Workspace;