@paths.design/caws-cli 11.1.6 → 11.1.8

package/dist/shell/binding/resolve-binding.js

@@ -140,6 +140,73 @@ function findRegistryMatch(cwdReal, registry) {
     }
     return best;
 }
+// SCOPE-CHECK-CWD-BINDING-RESOLUTION-001 helpers ─────────────────────────
+//
+// These power the target-path fallback (steps 2 and 3) when cwd does not
+// resolve a worktree. They are pure functions of (targetPath, registry,
+// specs) — no process.cwd(), no I/O beyond the realpath the caller already
+// did — so the binding for a path is identical from any invocation cwd.
+/**
+ * Normalize a repo-root-relative path to POSIX separators with no leading
+ * "./" or trailing slash, for stable matching against scope.in entries.
+ */
+function normalizeRel(p) {
+    return p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+/**
+ * Anchored glob match supporting `*` (any run of non-separator or separator
+ * chars within a segment-agnostic match) and `?` (single char). A bare
+ * directory entry (no glob meta) matches the entry itself OR any descendant
+ * (prefix match on a path boundary) — mirroring how scope.in directory
+ * entries admit files beneath them. No dependency on minimatch.
+ */
+function scopeEntryMatches(entry, target) {
+    const e = normalizeRel(entry);
+    const t = normalizeRel(target);
+    if (e === t)
+        return true;
+    if (!/[*?]/.test(e)) {
+        // Directory/prefix entry: admit descendants on a path boundary.
+        return t.startsWith(e + '/');
+    }
+    // Glob entry: translate to an anchored RegExp. `*` → [^/]-agnostic any,
+    // `?` → single char. Escape all other regex meta.
+    const rx = e
+        .split('')
+        .map((ch) => {
+        if (ch === '*')
+            return '.*';
+        if (ch === '?')
+            return '.';
+        return ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    })
+        .join('');
+    return new RegExp(`^${rx}$`).test(t);
+}
+/**
+ * Step (3): find every active bound spec whose scope.in admits `targetPath`.
+ * Returns one claimant per matching spec, naming the spec, its worktree, and
+ * the exact scope.in entry that matched (for the actionable refusal).
+ */
+function findScopeInClaimants(targetPath, input) {
+    const claimants = [];
+    for (const [name, record] of Object.entries(input.registry)) {
+        const specId = record?.specId;
+        if (typeof specId !== 'string' || specId.length === 0)
+            continue;
+        const spec = input.specs.find((s) => s.id === specId);
+        if (spec === undefined)
+            continue;
+        if (spec.lifecycle_state !== 'active')
+            continue;
+        const scopeIn = spec.scope?.in ?? [];
+        const matched = scopeIn.find((entry) => scopeEntryMatches(entry, targetPath));
+        if (matched !== undefined) {
+            claimants.push({ specId, worktreeName: name, matchedScopeInEntry: matched });
+        }
+    }
+    return claimants;
+}
 function resolveBinding(input) {
     const cwdReal = safeRealpath(input.cwd);
     const repoRootReal = safeRealpath(input.repoRoot);
@@ -182,7 +249,44 @@ function resolveBinding(input) {
         }
     }
     if (candidate === null) {
-        return { binding: { kind: 'unbound' }, source: 'none' };
+        // SCOPE-CHECK-CWD-BINDING-RESOLUTION-001: cwd resolved no worktree.
+        // Before falling to `unbound`, try to resolve the binding from the
+        // TARGET PATH so the verdict is cwd-independent.
+        if (typeof input.targetPath === 'string' && input.targetPath.length > 0) {
+            const targetAbs = safeRealpath(path.isAbsolute(input.targetPath)
+                ? input.targetPath
+                : path.join(repoRootReal, input.targetPath));
+            // Step (2): target-path worktree-location. If the absolute path lies
+            // under a registered worktree's path, that worktree binds. Unambiguous
+            // (a path is inside at most one worktree dir); take the deepest match.
+            const locMatch = findRegistryMatch(targetAbs, input.registry);
+            if (locMatch !== null) {
+                candidate = locMatch;
+                source = 'target_worktree_location';
+            }
+            else {
+                // Step (3): target-path scope.in claim.
+                const claimants = findScopeInClaimants(input.targetPath, input);
+                if (claimants.length === 1) {
+                    const only = claimants[0];
+                    candidate = { name: only.worktreeName, path: '' };
+                    source = 'target_scope_in_claim';
+                }
+                else if (claimants.length > 1) {
+                    // Refuse-on-conflict: name every claimant, pick none. `binding`
+                    // stays `unbound` (safe default); the ambiguity rides in the
+                    // dedicated `ambiguous` field that scope check inspects.
+                    return {
+                        binding: { kind: 'unbound' },
+                        ambiguous: { targetPath: normalizeRel(input.targetPath), claimants },
+                        source: 'target_scope_in_claim',
+                    };
+                }
+            }
+        }
+        if (candidate === null) {
+            return { binding: { kind: 'unbound' }, source: 'none' };
+        }
     }
     // We have a worktree name. Now find the bound spec for kernel evaluation.
     const record = input.registry[candidate.name];

package/dist/shell/binding/resolve-binding.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-binding.js","sourceRoot":"","sources":["../../../src/shell/binding/resolve-binding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolve-binding.js","sourceRoot":"","sources":["../../../src/shell/binding/resolve-binding.ts"],"names":[],"mappings":"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"}

package/dist/shell/binding/types.d.ts

@@ -18,6 +18,16 @@ export interface ResolveBindingInput {
      * cannot be invoked. Production injects a real git runner.
      */
     readonly gitWorktreeList?: (repoRoot: string) => readonly GitWorktreeEntry[];
+    /**
+     * SCOPE-CHECK-CWD-BINDING-RESOLUTION-001: the repo-root-relative path whose
+     * binding is being resolved. When set and the cwd does NOT match a worktree
+     * (step 1 yields no candidate), resolution falls back to (2) the path's
+     * worktree-location and (3) the bound spec(s) whose `scope.in` admits this
+     * path. This makes `caws scope check <path>` cwd-independent: the governing
+     * binding is a property of the PATH, not of where the command ran. Omitted
+     * → pre-existing cwd-only behavior.
+     */
+    readonly targetPath?: string;
 }
 export interface GitWorktreeEntry {
     /** Absolute path of the worktree on disk. */
@@ -25,18 +35,52 @@ export interface GitWorktreeEntry {
     /** Branch name (may be `(detached)` or `refs/heads/<x>`). */
     readonly branch?: string;
 }
+/**
+ * SCOPE-CHECK-CWD-BINDING-RESOLUTION-001: one spec that claims a target path
+ * via its `scope.in`. Carried in the `ambiguous` result so the refusal is
+ * actionable — the agent can name and inspect each contender.
+ */
+export interface BindingClaimant {
+    readonly specId: string;
+    readonly worktreeName: string;
+    /** The exact `scope.in` entry that matched the target path. */
+    readonly matchedScopeInEntry: string;
+}
+/**
+ * SCOPE-CHECK-CWD-BINDING-RESOLUTION-001: refuse-on-conflict detail surfaced
+ * when step-(3) scope.in-claim resolution finds MORE THAN ONE active bound
+ * spec claiming the same target path. Carried in a DEDICATED `ambiguous`
+ * field on `ResolvedBinding` (not inside `binding`) so that consumers which
+ * never pass a targetPath — e.g. `caws status`, which resolves from cwd —
+ * continue to see only the kernel `BindingState` and need no narrowing. Only
+ * `caws scope check/show`, which passes a targetPath, inspects `ambiguous`.
+ */
+export interface AmbiguousBindingDetail {
+    readonly targetPath: string;
+    readonly claimants: readonly BindingClaimant[];
+}
 export interface ResolvedBinding {
-    /** The kernel's `BindingState`. */
+    /** The kernel's `BindingState`. For an ambiguous result this is `unbound`
+     * (the safe default for non-scope-check consumers); inspect `ambiguous`. */
     readonly binding: BindingState;
+    /**
+     * Refuse-on-conflict detail. Present ONLY when step-(3) resolution found
+     * >1 claimant for the target path. When set, `binding` is `unbound` and
+     * `worktreeName` is undefined — no single owner was selected, by design.
+     * `caws scope check` keys its ambiguous-binding refusal off this field.
+     */
+    readonly ambiguous?: AmbiguousBindingDetail;
     /**
      * The resolved worktree name, if any. `undefined` when cwd is in the main
-     * checkout (no worktree).
+     * checkout with no resolvable target-path binding, or when ambiguous.
      */
     readonly worktreeName?: string;
     /**
      * Where the worktree-name resolution came from. Helps explain `bound`
      * vs `one_sided` decisions to the user.
+     *   - target_worktree_location: step (2), path under .caws/worktrees/<name>/
+     *   - target_scope_in_claim:    step (3), a bound spec's scope.in admits path
      */
-    readonly source: 'registry_path_match' | 'git_porcelain_match' | 'none';
+    readonly source: 'registry_path_match' | 'git_porcelain_match' | 'target_worktree_location' | 'target_scope_in_claim' | 'none';
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/shell/binding/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/shell/binding/types.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,YAAY,EACZ,IAAI,EACJ,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,SAAS,gBAAgB,EAAE,CAAC;CAC9E;AAED,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,MAAM,CAAC;CACzE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/shell/binding/types.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,YAAY,EACZ,IAAI,EACJ,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,SAAS,gBAAgB,EAAE,CAAC;IAC7E;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,eAAe;IAC9B;gFAC4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EACX,qBAAqB,GACrB,qBAAqB,GACrB,0BAA0B,GAC1B,uBAAuB,GACvB,MAAM,CAAC;CACZ"}

package/dist/shell/command-metadata.d.ts

@@ -0,0 +1,93 @@
+/** A positional argument on a command (this CLI uses at most one per command). */
+export interface CommandArgMeta {
+    /** Argument name as it appears in usage, e.g. "id" or "path". */
+    readonly name: string;
+    /** Whether the argument is required (`<name>`) or optional (`[name]`). */
+    readonly required: boolean;
+    /** Help text for the argument. */
+    readonly description: string;
+}
+/**
+ * A Commander option. The `flag` string is authored verbatim (e.g.
+ * "--mode <mode>" or "--apply") so register.ts calls
+ * `.option(flag, description, defaultValue?)` with no string literal of its
+ * own.
+ */
+export interface CommandOptionMeta {
+    /** Full Commander flag string, e.g. "--mode <mode>", "--ack <sha>", "--apply". */
+    readonly flag: string;
+    /** When true, register.ts uses `.requiredOption()` (Commander pre-validates). */
+    readonly required?: boolean;
+    /**
+     * Help prose. When `allowedValues` is set, register.ts appends
+     * ": <v1> | <v2> | ..." and the lock test asserts that list equals the
+     * kernel/schema enum — so the value list is the derived, locked part and
+     * this string is only the prose prefix.
+     */
+    readonly description: string;
+    /**
+     * Enum-backed value list (e.g. SPEC_MODES). Present only for options whose
+     * accepted values come from a kernel enum / JSON-schema enum. The lock test
+     * asserts deep-equality against that authority; drift becomes a test failure.
+     */
+    readonly allowedValues?: readonly (string | number)[];
+    /** Commander default value, passed as the 3rd arg to `.option()`. */
+    readonly defaultValue?: string | boolean | readonly string[];
+    /**
+     * True for repeatable options that accumulate (e.g. `--ack <sha>` collected
+     * into an array). register.ts supplies the collector; this flag records the
+     * intent so the metadata is self-describing.
+     */
+    readonly collect?: boolean;
+}
+/** A leaf command (one that has an `.action()` handler). */
+export interface LeafCommandMeta {
+    readonly kind: 'leaf';
+    /** Command name as passed to `.command()` (without the `<arg>` suffix). */
+    readonly name: string;
+    /** The positional argument, if any. */
+    readonly argument?: CommandArgMeta;
+    /** The `.description()` text. */
+    readonly description: string;
+    /** Declared options, in display order. */
+    readonly options: readonly CommandOptionMeta[];
+}
+/** A group command whose subcommands carry the `.action()` handlers. */
+export interface GroupCommandMeta {
+    readonly kind: 'group';
+    /** Group name as passed to `.command()`, e.g. "specs". */
+    readonly name: string;
+    /** The group-level `.description()` (shown in `caws --help` and `caws <group> --help`). */
+    readonly description: string;
+    /** The group's subcommands. */
+    readonly subcommands: readonly LeafCommandMeta[];
+}
+/** Either a flat leaf command or a group with subcommands. */
+export type CommandMeta = LeafCommandMeta | GroupCommandMeta;
+export declare const SPECS_COMMAND_META: GroupCommandMeta;
+export declare const WORKTREE_COMMAND_META: GroupCommandMeta;
+export declare const INIT_COMMAND_META: LeafCommandMeta;
+export declare const DOCTOR_COMMAND_META: LeafCommandMeta;
+export declare const STATUS_COMMAND_META: LeafCommandMeta;
+export declare const CLAIM_COMMAND_META: LeafCommandMeta;
+export declare const PREPUSH_COMMAND_META: LeafCommandMeta;
+export declare const SCOPE_COMMAND_META: GroupCommandMeta;
+export declare const GATES_COMMAND_META: GroupCommandMeta;
+export declare const EVIDENCE_COMMAND_META: GroupCommandMeta;
+export declare const EVENTS_COMMAND_META: GroupCommandMeta;
+export declare const WAIVER_COMMAND_META: GroupCommandMeta;
+export declare const AGENTS_COMMAND_META: GroupCommandMeta;
+/**
+ * The complete v11 command-surface metadata — the single authority for every
+ * `.description()` / `.argument()` / `.option()` in register.ts.
+ *
+ * SLICE 3: all thirteen surface entries are populated and consumed by
+ * register.ts — the five flat top-level commands (init/doctor/status/claim/
+ * prepush) as LeafCommandMeta, and eight groups (scope/gates/evidence/events/
+ * waiver/agents/specs/worktree). The lock test enforces full set-equality with
+ * REGISTERED_COMMAND_GROUPS (L1), enum/value-list parity (L3), non-empty
+ * descriptions (L4), and the global no-inline-strings invariant on register.ts
+ * (L5).
+ */
+export declare const COMMAND_SURFACE_METADATA: readonly CommandMeta[];
+//# sourceMappingURL=command-metadata.d.ts.map

package/dist/shell/command-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-metadata.d.ts","sourceRoot":"","sources":["../../src/shell/command-metadata.ts"],"names":[],"mappings":"AAqCA,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IACtD,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC;IAC7D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAChD;AAED,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;CAClD;AAED,8DAA8D;AAC9D,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAgB7D,eAAO,MAAM,kBAAkB,EAAE,gBA8KhC,CAAC;AAMF,eAAO,MAAM,qBAAqB,EAAE,gBAsFnC,CAAC;AAOF,eAAO,MAAM,iBAAiB,EAAE,eAuB/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAKjC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAMjC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,eAmBhC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmBlC,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,gBAoBhC,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,gBAqBhC,CAAC;AAGF,eAAO,MAAM,qBAAqB,EAAE,gBAsBnC,CAAC;AAGF,eAAO,MAAM,mBAAmB,EAAE,gBA+DjC,CAAC;AAGF,eAAO,MAAM,mBAAmB,EAAE,gBAiEjC,CAAC;AAGF,eAAO,MAAM,mBAAmB,EAAE,gBAoGjC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,WAAW,EAczD,CAAC"}