@cruxy/cli 1.0.2 → 1.0.4

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;