@cruxy/cli 0.22.0 → 0.23.0

package/dist/vcs/types.d.ts

@@ -3,14 +3,21 @@
  * interface is the swap seam — GitHub ships first, GitLab/Bitbucket slot in later
  * without touching call sites (same discipline as `VectorStore`/`Embedder`).
  */
-/** Where a repository lives and who owns it, parsed from the `origin` remote. */
-export interface RepoInfo {
+/**
+ * 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;
 }
@@ -40,6 +47,15 @@ export interface ForgeProvider {
     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>;
 }

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;

package/dist/workspace/workspace.js

@@ -0,0 +1,180 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { rootAmbiguous, rootOverlap, rootUnknown, usageError, } from "../errors/index.js";
+import { isInside } from "./resolve.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 class Workspace {
+    rootsByName;
+    ordered;
+    primaryRoot;
+    constructor(roots) {
+        if (roots.length === 0) {
+            throw usageError("a workspace needs at least one root");
+        }
+        const byName = new Map();
+        for (const r of roots)
+            byName.set(r.name, Object.freeze({ ...r }));
+        const primary = roots.filter((r) => r.primary);
+        if (primary.length !== 1) {
+            throw usageError(`a workspace must have exactly one primary root (found ${primary.length})`);
+        }
+        this.ordered = Object.freeze([...roots]);
+        this.rootsByName = byName;
+        this.primaryRoot = primary[0];
+    }
+    /** All declared roots, in declaration order. */
+    roots() {
+        return this.ordered;
+    }
+    /** The primary root — the default for bare relative paths and git/instructions. */
+    primary() {
+        return this.primaryRoot;
+    }
+    /** True when more than one root is declared (i.e. a genuine multi-repo session). */
+    get isMultiRoot() {
+        return this.ordered.length > 1;
+    }
+    /**
+     * 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) {
+        const found = this.rootsByName.get(name);
+        if (!found) {
+            throw rootUnknown(name, this.ordered.map((r) => r.name));
+        }
+        return found;
+    }
+    /** Like {@link rootByName} but returns undefined instead of throwing. */
+    tryRootByName(name) {
+        return this.rootsByName.get(name);
+    }
+    /**
+     * 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) {
+        const target = path.resolve(absPath);
+        const hits = this.ordered.filter((r) => isInside(r.absPath, target));
+        if (hits.length === 0) {
+            throw rootUnknown(absPath, this.ordered.map((r) => r.name));
+        }
+        if (hits.length > 1) {
+            // Unreachable while overlap is refused at declaration — belt-and-suspenders.
+            throw rootAmbiguous(absPath, hits.map((r) => r.name));
+        }
+        return hits[0];
+    }
+}
+/** A valid root name: non-empty, no path separators, not a traversal token. */
+function assertValidName(name) {
+    if (name.length === 0 ||
+        name.includes("/") ||
+        name.includes("\\") ||
+        name === "." ||
+        name === "..") {
+        throw usageError(`invalid workspace root name "${name}"`, [
+            "root names must be non-empty and contain no path separators",
+        ]);
+    }
+}
+/** Derive a stable, unique name from a path basename, deduping with -2, -3, … */
+function uniqueBasename(absPath, taken) {
+    const base = path.basename(absPath) || "root";
+    if (!taken.has(base))
+        return base;
+    for (let i = 2;; i++) {
+        const candidate = `${base}-${i}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+}
+/**
+ * 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 async function buildWorkspace(specs, opts = {}) {
+    if (specs.length === 0) {
+        throw usageError("no workspace roots declared");
+    }
+    const baseCwd = opts.cwd ?? process.cwd();
+    const taken = new Set();
+    const resolved = [];
+    for (const spec of specs) {
+        const absPath = path.resolve(baseCwd, spec.path);
+        let stat;
+        try {
+            stat = await fs.stat(absPath);
+        }
+        catch {
+            throw usageError(`workspace root does not exist: ${spec.path}`, [
+                `resolved to ${absPath}`,
+            ]);
+        }
+        if (!stat.isDirectory()) {
+            throw usageError(`workspace root is not a directory: ${spec.path}`, [
+                `resolved to ${absPath}`,
+            ]);
+        }
+        if (spec.name !== undefined) {
+            assertValidName(spec.name);
+            if (taken.has(spec.name)) {
+                throw usageError(`duplicate workspace root name "${spec.name}"`);
+            }
+            taken.add(spec.name);
+        }
+        resolved.push({ absPath, name: spec.name });
+    }
+    // Overlap/nesting refusal (⚖︎#5): any pair where one contains or equals the
+    // other is rejected at declaration.
+    for (let i = 0; i < resolved.length; i++) {
+        for (let j = i + 1; j < resolved.length; j++) {
+            const a = resolved[i].absPath;
+            const b = resolved[j].absPath;
+            if (a === b || isInside(a, b) || isInside(b, a)) {
+                throw rootOverlap(a, b);
+            }
+        }
+    }
+    // Assign names (explicit first so basenames dedupe around them), then declare.
+    for (const r of resolved) {
+        if (r.name === undefined) {
+            r.name = uniqueBasename(r.absPath, taken);
+            taken.add(r.name);
+        }
+    }
+    const declared = resolved.map((r, i) => ({
+        name: r.name,
+        absPath: r.absPath,
+        primary: i === 0,
+    }));
+    return new Workspace(declared);
+}
+/**
+ * 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 function singleRootWorkspace(absPath) {
+    const abs = path.resolve(absPath);
+    return new Workspace([
+        { name: path.basename(abs) || "root", absPath: abs, primary: true },
+    ]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {