@cruxy/cli 0.21.0 → 0.22.1

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.21.0",
+  "version": "0.22.1",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
@@ -34,6 +34,7 @@
     "fastembed": "^2.1.0",
     "picocolors": "^1.1.1",
     "tinyglobby": "^0.2.10",
+    "undici": "^6.21.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5",
     "@cruxy/sdk": "0.2.0"