@cruxy/cli 0.22.0 → 0.22.1

package/dist/sandbox/policy.js

@@ -7,8 +7,12 @@ import { globalDir } from "../config/paths.js";
  * {@link IsolationPolicy}. This is where the security posture is decided, and
  * every default here is deny/minimal:
  *
- * - the ONLY read-write mount is the project workdir (at its identical absolute
- *   path, so paths stay coherent with the host and the C.32 checkpoint);
+ * - the DEFAULT read-write mount is the command's own project workdir (at its
+ *   identical absolute path, so paths stay coherent with the host and the C.32
+ *   checkpoint);
+ * - other declared roots in a multi-repo session (C.26, R5) are mounted READ-ONLY
+ *   — readable for legit cross-repo builds, never writable unless an explicit
+ *   per-command escalation names that root in `writableRoots`;
  * - extra mounts come solely from `sandbox.mounts` (explicit by construction),
  *   and a mount of the docker socket, the cruxy home, or the user's home root
  *   is rejected — those are the escape hatches we refuse to open;
@@ -16,12 +20,21 @@ import { globalDir } from "../config/paths.js";
  *   writable and never left root-owned;
  * - network defaults to `none`; any widening can only come from explicit config.
  */
-export function buildPolicy(cfg, cwd) {
+export function buildPolicy(cfg, cwd, opts = {}) {
     const workdir = {
         source: cwd,
         target: cwd,
         readonly: false,
     };
+    const writable = new Set((opts.writableRoots ?? []).map((r) => resolvePath(r)));
+    const siblingRoots = (opts.siblingRoots ?? [])
+        .map((r) => resolvePath(r))
+        .filter((r) => r !== resolvePath(cwd)) // the workdir is never a sibling
+        .map((source) => ({
+        source,
+        target: source, // identical path, like the workdir, for path coherence
+        readonly: !writable.has(source), // RO unless explicitly escalated (R5)
+    }));
     return {
         image: cfg.image,
         network: cfg.network,
@@ -30,6 +43,7 @@ export function buildPolicy(cfg, cwd) {
         pids: cfg.pids,
         cpus: cfg.cpus,
         workdir,
+        siblingRoots,
         mounts: cfg.mounts.map((spec) => parseMount(spec, cwd)),
         tmpfs: "/tmp",
     };

package/dist/sandbox/types.d.ts

@@ -43,8 +43,17 @@ export interface IsolationPolicy {
     readonly pids: number;
     /** CPU cap (`--cpus`, fractional allowed). */
     readonly cpus: number;
-    /** The project workdir, mounted read-write at the identical absolute path. */
+    /** The command's OWN workspace root, mounted read-write at its absolute path. */
     readonly workdir: BindMount;
+    /**
+     * The OTHER declared workspace roots in a multi-repo session (C.26, R5). Each
+     * is mounted **read-only** so a legit build can *read* a sibling (e.g. generated
+     * client types) — but never write it. A sibling flips to read-write ONLY when an
+     * explicit per-command cross-root-write escalation was approved for that exact
+     * root; ambient cross-root write authority is never the default. Empty in a
+     * single-root session (identical to the pre-C.26 posture).
+     */
+    readonly siblingRoots?: readonly BindMount[];
     /** Extra explicit mounts beyond the workdir (from `sandbox.mounts`). */
     readonly mounts: readonly BindMount[];
     /** Writable in-memory tmp mount point; the rest of the root fs is read-only. */

package/dist/tools/file/paths.d.ts

@@ -1,26 +1,19 @@
-import { CruxyError } from "../../errors/index.js";
+import { PathEscapeError } from "../../workspace/index.js";
 import type { ToolContext } from "../types.js";
 /**
- * Thrown when a tool argument resolves to a path outside the project root —
- * whether via `../` traversal, an absolute path, or a symlink pointing outward.
- * 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 }`.
+ * Path confinement for file tools. The confinement kernel now lives in
+ * `src/workspace` so multi-root (C.26) and single-root callers share ONE
+ * implementation. This module keeps the single-root `resolveInRoot` entry point
+ * (and re-exports {@link PathEscapeError}) so existing call sites are unchanged:
+ * they confine to `ctx.cwd`, which is the workspace's primary root.
  */
-export declare class PathEscapeError extends CruxyError {
-    constructor(message: string);
-}
+export { PathEscapeError };
 /**
  * Resolve a tool-supplied path against the project root (`ctx.cwd`) and prove it
- * stays inside — the single security boundary every file tool funnels through.
+ * stays inside — the single-root funnel. Delegates to {@link confineToRoot}; see
+ * there for the 2-layer (lexical + symlink) confinement logic.
  *
- * 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 (e.g. macOS `/var → /private/var`).
- *
- * @returns the resolved absolute path (lexical, not realpath'd — so callers
- *   operate on the intended location).
+ * @returns the resolved absolute path (lexical, not realpath'd).
  * @throws {PathEscapeError} if the path escapes the root.
  */
 export declare function resolveInRoot(ctx: ToolContext, p: string): Promise<string>;

package/dist/tools/file/paths.js

@@ -1,67 +1,20 @@
-import { promises as fs } from "node:fs";
-import path from "node:path";
-import { CruxyError, ErrorCode } from "../../errors/index.js";
+import { confineToRoot, PathEscapeError } from "../../workspace/index.js";
 /**
- * Thrown when a tool argument resolves to a path outside the project root —
- * whether via `../` traversal, an absolute path, or a symlink pointing outward.
- * 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 }`.
+ * Path confinement for file tools. The confinement kernel now lives in
+ * `src/workspace` so multi-root (C.26) and single-root callers share ONE
+ * implementation. This module keeps the single-root `resolveInRoot` entry point
+ * (and re-exports {@link PathEscapeError}) so existing call sites are unchanged:
+ * they confine to `ctx.cwd`, which is the workspace's primary root.
  */
-export class PathEscapeError extends CruxyError {
-    constructor(message) {
-        super({ code: ErrorCode.PathEscape, title: message });
-        this.name = "PathEscapeError";
-    }
-}
-/** Is `target` the root itself or a descendant of it? */
-function isInside(root, target) {
-    return target === root || target.startsWith(root + path.sep);
-}
-/**
- * realpath `p`, or — if it doesn't exist yet — the realpath of its nearest
- * existing ancestor directory. Lets us validate a not-yet-created path by the
- * directory it would be created in (catching outward symlinked parents).
- */
-async function realpathOfNearestExisting(p) {
-    let cur = p;
-    for (;;) {
-        try {
-            return await fs.realpath(cur);
-        }
-        catch (err) {
-            if (err.code !== "ENOENT")
-                throw err;
-            const parent = path.dirname(cur);
-            if (parent === cur)
-                return cur; // reached the filesystem root
-            cur = parent;
-        }
-    }
-}
+export { PathEscapeError };
 /**
  * Resolve a tool-supplied path against the project root (`ctx.cwd`) and prove it
- * stays inside — the single security boundary every file tool 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 (e.g. macOS `/var → /private/var`).
+ * stays inside — the single-root funnel. Delegates to {@link confineToRoot}; see
+ * there for the 2-layer (lexical + symlink) confinement logic.
  *
- * @returns the resolved absolute path (lexical, not realpath'd — so callers
- *   operate on the intended location).
+ * @returns the resolved absolute path (lexical, not realpath'd).
  * @throws {PathEscapeError} if the path escapes the root.
  */
 export async function resolveInRoot(ctx, p) {
-    const root = path.resolve(ctx.cwd);
-    const resolved = path.resolve(root, p);
-    if (!isInside(root, resolved)) {
-        throw new PathEscapeError(`path "${p}" resolves outside the project root`);
-    }
-    const realRoot = await fs.realpath(root);
-    const realTarget = await realpathOfNearestExisting(resolved);
-    if (!isInside(realRoot, realTarget)) {
-        throw new PathEscapeError(`path "${p}" resolves outside the project root (via a symlink)`);
-    }
-    return resolved;
+    return confineToRoot(ctx.cwd, p);
 }

package/dist/workspace/index.d.ts

@@ -0,0 +1,5 @@
+export type { DeclaredRoot, RootSpec } from "./types.js";
+export { Workspace, buildWorkspace, singleRootWorkspace } from "./workspace.js";
+export { PathEscapeError, confineToRoot, isInside, resolveInWorkspace, } from "./resolve.js";
+export { selectRoot } from "./select.js";
+export type { RootRef, SelectedRoot } from "./select.js";

package/dist/workspace/index.js

@@ -0,0 +1,3 @@
+export { Workspace, buildWorkspace, singleRootWorkspace } from "./workspace.js";
+export { PathEscapeError, confineToRoot, isInside, resolveInWorkspace, } from "./resolve.js";
+export { selectRoot } from "./select.js";

package/dist/workspace/resolve.d.ts

@@ -0,0 +1,54 @@
+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/resolve.js

@@ -0,0 +1,96 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { CruxyError, ErrorCode } from "../errors/index.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 class PathEscapeError extends CruxyError {
+    constructor(message) {
+        super({ code: ErrorCode.PathEscape, title: message });
+        this.name = "PathEscapeError";
+    }
+}
+/** Is `target` the root itself or a descendant of it? */
+export function isInside(root, target) {
+    return target === root || target.startsWith(root + path.sep);
+}
+/**
+ * realpath `p`, or — if it doesn't exist yet — the realpath of its nearest
+ * existing ancestor directory. Lets us validate a not-yet-created path by the
+ * directory it would be created in (catching outward symlinked parents).
+ */
+async function realpathOfNearestExisting(p) {
+    let cur = p;
+    for (;;) {
+        try {
+            return await fs.realpath(cur);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return cur; // reached the filesystem root
+            cur = parent;
+        }
+    }
+}
+/**
+ * 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 async function confineToRoot(rootAbsPath, p) {
+    const root = path.resolve(rootAbsPath);
+    const resolved = path.resolve(root, p);
+    if (!isInside(root, resolved)) {
+        throw new PathEscapeError(`path "${p}" resolves outside the project root`);
+    }
+    const realRoot = await fs.realpath(root);
+    const realTarget = await realpathOfNearestExisting(resolved);
+    if (!isInside(realRoot, realTarget)) {
+        throw new PathEscapeError(`path "${p}" resolves outside the project root (via a symlink)`);
+    }
+    return resolved;
+}
+/**
+ * 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 async function resolveInWorkspace(ws, rootName, p) {
+    const root = ws.rootByName(rootName); // fail-loud on unknown name (R1)
+    return confineToRoot(root.absPath, p);
+}

package/dist/workspace/select.d.ts

@@ -0,0 +1,41 @@
+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/select.js

@@ -0,0 +1,44 @@
+import path from "node:path";
+import { rootAmbiguous } from "../errors/index.js";
+/**
+ * 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 function selectRoot(ws, ref, opts = {}) {
+    // 1. Explicit root name wins.
+    if (ref.root !== undefined) {
+        return { root: ws.rootByName(ref.root), relPath: ref.path };
+    }
+    // 2. Absolute path → the unique containing root.
+    if (path.isAbsolute(ref.path)) {
+        return { root: ws.rootContaining(ref.path), relPath: ref.path };
+    }
+    // 3. `name/rest` where `name` is a declared root (only meaningful multi-root).
+    const firstSeg = ref.path.split(/[/\\]/, 1)[0];
+    if (firstSeg && ref.path !== firstSeg) {
+        const named = ws.tryRootByName(firstSeg);
+        if (named) {
+            const rest = ref.path.slice(firstSeg.length).replace(/^[/\\]+/, "");
+            return { root: named, relPath: rest };
+        }
+    }
+    // 4. Bare relative path → primary root, unless a mutation must be explicit.
+    if (opts.requireExplicit && ws.isMultiRoot) {
+        throw rootAmbiguous(ref.path, ws.roots().map((r) => r.name));
+    }
+    return { root: ws.primary(), relPath: ref.path };
+}

package/dist/workspace/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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/types.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+export {};

package/dist/workspace/workspace.d.ts

@@ -0,0 +1,56 @@
+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 a trivial single-root workspace from one absolute path — the back-compat
+ * bridge for the many call sites that still pass a single `cwd`. The one root is
+ * primary and named by its basename.
+ */
+export declare function singleRootWorkspace(absPath: string): Workspace;