@skillsmith/core 0.12.0 → 0.12.2

package/dist/src/install/workspace-scope.d.ts

@@ -0,0 +1,207 @@
+/**
+ * ADR-139: Global-vs-Workspace Install Scope Resolution, Keyed by (Scope, Client, Name).
+ *
+ * @see docs/internal/adr/139-global-vs-workspace-install-scope-resolution.md
+ * @see SMI-6266, SMI-6274 (Wave 4), SMI-5894 (the (client, name) keying precedent this
+ *   extends to scope), SMI-1630 (the repo-local-overrides-global promise this generalizes)
+ *
+ * Two scopes, both per-client:
+ *   - `global`    — `CLIENT_NATIVE_PATHS[client]` (unchanged).
+ *   - `workspace` — `<workspace-root>/<client's workspace segments>`, from
+ *     {@link CLIENT_WORKSPACE_SEGMENTS} (a sibling table to `CLIENT_NATIVE_PATHS`
+ *     in `./paths.ts`).
+ *
+ * {@link findWorkspaceRoot} is deliberately NOT a reuse of
+ * `findMainRepoRoot()` (`packages/doc-retrieval-mcp/src/retrieval-log/project-dir.ts`).
+ * That helper requires `.git` to be a real DIRECTORY, specifically so it skips
+ * worktrees and returns the *main* repo root — correct for its own purpose
+ * (telemetry attribution) and exactly wrong here: `.git` is a *file* in both
+ * worktrees and submodules, and this repo's own default development workflow
+ * is worktree-based, so requiring a directory would resolve every worktree's
+ * workspace installs back to the main checkout. `findWorkspaceRoot()` tests
+ * path EXISTENCE (`existsSync`), never `isDirectory()`, for `.git` — the two
+ * walks are near-neighbours with deliberately OPPOSITE `.git` predicates; see
+ * `findMainRepoRoot()`'s own header note pointing back here.
+ */
+import { type ClientId } from './paths.js';
+export type InstallScope = 'global' | 'workspace';
+/**
+ * Workspace-relative path segments per client, sibling table to
+ * `CLIENT_NATIVE_PATHS` (`./paths.ts`). `null` means the client has no
+ * documented workspace convention and can only ever resolve to `global`
+ * scope — adding one later is a table entry here, not a code change
+ * (ADR-139 Consequences / Neutral).
+ *
+ * Verified 2026-08-29 against `docs/internal/research/smi-5386-opencode-antigravity-skill-dirs.md`
+ * and ADR-139's own Decision §1: `antigravity` and `agents` deliberately
+ * share the SAME segments (`.agents/skills`) — AntiGravity reads project
+ * skills from the same open-standard cross-agent convention `agents`'
+ * GLOBAL path (`~/.agents/skills`) already uses, which is exactly the
+ * pathological case ADR-139 point 4's termination-before-candidacy fix
+ * exists for (see `findWorkspaceRoot` below).
+ */
+export declare const CLIENT_WORKSPACE_SEGMENTS: Readonly<Record<ClientId, readonly string[] | null>>;
+/** An explicit `--scope`/`SKILLSMITH_SCOPE` value that isn't `global`/`workspace`. */
+export declare class InvalidScopeValueError extends Error {
+    constructor(message: string);
+}
+/**
+ * An explicit workspace-scope request (flag, env var, or config default)
+ * that cannot be satisfied — the client has no workspace convention, or no
+ * workspace root exists above `cwd`. ADR-139 point 2: this is a HARD ERROR,
+ * never a silent downgrade to global.
+ */
+export declare class UnsatisfiableWorkspaceScopeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a raw `--scope`/`SKILLSMITH_SCOPE` string. Returns `undefined` for
+ * an absent/empty value (meaning "no opinion at this rank" — the caller
+ * falls through to the next precedence rank), and throws for anything
+ * present but not `global`/`workspace`.
+ */
+export declare function parseInstallScope(raw: string | undefined | null): InstallScope | undefined;
+/**
+ * Per-client persisted default scope from `~/.skillsmith/config.json`
+ * (`defaultScope.<client>`, e.g. `defaultScope.antigravity = "workspace"`).
+ * Fails soft (`undefined`) on any read/parse error — a corrupt config file
+ * must never crash scope resolution, only fall through to auto-detection.
+ */
+export declare function getDefaultScopeForClient(client: ClientId): InstallScope | undefined;
+export interface WorkspaceRootResult {
+    /** Absolute path to the resolved workspace root. */
+    root: string;
+    /** Which tier matched: the client's own marker directory, or a `.git` VCS boundary. */
+    via: 'marker' | 'vcs';
+}
+export interface FindWorkspaceRootOptions {
+    /**
+     * Override for `os.homedir()`'s return value. Defaults to the real
+     * `os.homedir()`. This is a test seam only (mirrors `agent-home-relocate.ts`'s
+     * `homeDir` override precedent elsewhere in this package) — production
+     * callers never pass it, and the walk otherwise ALWAYS sources home via
+     * `os.homedir()`, never manual `~` expansion (ADR-139 point 4,
+     * Windows-safety).
+     */
+    homeDirOverride?: string;
+}
+/**
+ * Resolve the nearest workspace root for `client` above (and including)
+ * `cwd`, or `null` when `cwd` is outside any workspace for that client.
+ *
+ * Implements ADR-139 point 4's algorithm EXACTLY, including its load-bearing
+ * ordering: at every directory in the walk, **termination is evaluated
+ * before candidacy**. An earlier draft of ADR-139 checked candidacy first,
+ * which meant a walk reaching `$HOME` would test `$HOME/<segments>` for a
+ * marker BEFORE applying "stop, no match" — and for the `agents` client,
+ * `$HOME/.agents/skills` IS the GLOBAL path, so that ordering collapsed
+ * global and workspace scope for that client. Termination-before-candidacy
+ * is the fix; do not reorder these two phases.
+ *
+ * `$HOME` is an EXCLUSIVE bound: the walk stops AT it without ever
+ * considering it as a candidate. `.git` existence is checked via
+ * `existsSync` (file OR directory) — see the module header for why this is
+ * the opposite predicate from `findMainRepoRoot()`.
+ */
+export declare function findWorkspaceRoot(cwd: string, client: ClientId, options?: FindWorkspaceRootOptions): WorkspaceRootResult | null;
+/** `<workspaceRoot>/.skillsmith/manifest.json` — self-scoping, self-cleaning (ADR-139 point 1). */
+export declare function resolveWorkspaceManifestPath(workspaceRoot: string): string;
+export interface ResolveScopeParams {
+    client: ClientId;
+    /** Defaults to `process.cwd()`. */
+    cwd?: string;
+    /**
+     * Rank 1 — explicit `--scope` flag value, if the caller parsed one. Typed
+     * `| undefined` explicitly (not just optional `?:`) so callers can pass
+     * `parseInstallScope(raw)`'s own `InstallScope | undefined` return value
+     * straight through under this repo's `exactOptionalPropertyTypes`.
+     */
+    explicitScope?: InstallScope | undefined;
+    /**
+     * Rank 2 — raw `SKILLSMITH_SCOPE` value. Defaults to
+     * `process.env.SKILLSMITH_SCOPE` when omitted (mirrors `resolveClientPath()`'s
+     * own override convention in `./paths.ts`). Pass `''` explicitly to force
+     * "no env value" in tests without touching real process env.
+     */
+    envScope?: string | undefined;
+    /**
+     * Rank 3 — per-client persisted default. Three states, distinguished by
+     * value (not by whether the key is present, since an optional TS property
+     * can't tell "present as undefined" from "absent" at runtime):
+     *   - omitted / `undefined` — read the real default via
+     *     `getDefaultScopeForClient(client)` (`~/.skillsmith/config.json`).
+     *   - `null` — explicitly "no config default configured", WITHOUT
+     *     touching the real config file. The test seam for isolating ranks
+     *     4-5 from a developer's real `~/.skillsmith/config.json`.
+     *   - an actual `InstallScope` — used directly, also without touching disk.
+     */
+    configDefaultScope?: InstallScope | null;
+    /** Test seam — see {@link FindWorkspaceRootOptions.homeDirOverride}. */
+    homeDirOverride?: string;
+}
+export interface ResolvedSkillScope {
+    scope: InstallScope;
+    /** Absolute path to the resolved skills directory for this scope. */
+    dir: string;
+    /** Present only when `scope === 'workspace'`. */
+    workspaceRoot?: string;
+    /** Present only when `scope === 'workspace'`. */
+    via?: 'marker' | 'vcs';
+    /**
+     * `true` only when THIS call created the workspace directory — always
+     * `false` for `global` and for an already-existing workspace marker.
+     * Callers must print the absolute path they wrote when this is `true`
+     * (ADR-139 point 5).
+     */
+    created: boolean;
+}
+/**
+ * Resolve the install scope for one `(client, cwd)` pair per ADR-139 point 2's
+ * five-rank precedence:
+ *
+ *   1. Explicit `--scope` flag
+ *   2. `SKILLSMITH_SCOPE` env var
+ *   3. Per-client `~/.skillsmith/config.json` default
+ *   4. Auto-detection of an EXISTING workspace marker (read-only, never creates)
+ *   5. Global (default)
+ *
+ * Ranks 1-3 all represent an explicit request for a scope: requesting
+ * `workspace` at any of these ranks resolves via {@link findWorkspaceRoot}
+ * and, when the walk found a VCS boundary but no marker yet, CREATES the
+ * marker directory (`mkdirSync(..., { recursive: true })`) — this is the
+ * ONLY path that ever creates a workspace directory (ADR-139 point 5).
+ * Requesting `workspace` for a client with no workspace convention, or from
+ * outside any workspace entirely (no marker AND no ancestor `.git`), throws
+ * {@link UnsatisfiableWorkspaceScopeError} — never a silent downgrade.
+ *
+ * Rank 4 (auto-detection) is deliberately narrower: it only matches an
+ * EXISTING marker directory (`findWorkspaceRoot(...).via === 'marker'`) — a
+ * bare VCS boundary with no marker does NOT count as an auto-detected hit,
+ * and this rank never creates anything. Falling through this rank with no
+ * match resolves to rank 5 (global) silently and successfully — the
+ * ordinary case, not a warning-worthy one (ADR-139 point 6).
+ */
+export declare function resolveSkillScope(params: ResolveScopeParams): ResolvedSkillScope;
+export interface ScopedInstallTarget extends ResolvedSkillScope {
+    /**
+     * The manifest to record this install in: the workspace-local
+     * `<workspaceRoot>/.skillsmith/manifest.json` when `scope === 'workspace'`,
+     * else the global `~/.skillsmith/manifest.json` (or `globalManifestPath`
+     * when the caller passed one — CLI/MCP callers with their own resolved
+     * default should pass their own constant here so it stays byte-identical
+     * to `DEFAULT_MANIFEST_PATH` elsewhere, per ADR-139 point 1's requirement
+     * that the global manifest and `manifestKeyFor()`'s key shape are left
+     * completely untouched by this change).
+     */
+    manifestPath: string;
+}
+/**
+ * Convenience wrapper over {@link resolveSkillScope} that also resolves the
+ * manifest path to record the install in — the one call CLI/MCP commands
+ * need for `install`/`list`/`update`/`remove` (ADR-139 point 7: "One shared
+ * resolver, in core, for every command").
+ */
+export declare function resolveScopedSkillsDir(params: ResolveScopeParams & {
+    globalManifestPath?: string;
+}): ScopedInstallTarget;
+//# sourceMappingURL=workspace-scope.d.ts.map

package/dist/src/install/workspace-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-scope.d.ts","sourceRoot":"","sources":["../../../src/install/workspace-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAOH,OAAO,EAAuB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAA;AAM/D,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC,CAU1F,CAAA;AAMD,sFAAsF;AACtF,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;gBAC7C,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,YAAY,GAAG,SAAS,CAI1F;AAMD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,QAAQ,GAAG,YAAY,GAAG,SAAS,CAQnF;AAiBD,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,uFAAuF;IACvF,GAAG,EAAE,QAAQ,GAAG,KAAK,CAAA;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,QAAQ,EAChB,OAAO,GAAE,wBAA6B,GACrC,mBAAmB,GAAG,IAAI,CA2B5B;AAED,mGAAmG;AACnG,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE1E;AAUD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,QAAQ,CAAA;IAChB,mCAAmC;IACnC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,SAAS,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IACxC,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,YAAY,CAAA;IACnB,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAA;IACX,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,iDAAiD;IACjD,GAAG,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IACtB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAyEhF;AAED,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D;;;;;;;;;OASG;IACH,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,kBAAkB,GAAG;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3D,mBAAmB,CAOrB"}

package/dist/src/install/workspace-scope.js

@@ -0,0 +1,275 @@
+/**
+ * ADR-139: Global-vs-Workspace Install Scope Resolution, Keyed by (Scope, Client, Name).
+ *
+ * @see docs/internal/adr/139-global-vs-workspace-install-scope-resolution.md
+ * @see SMI-6266, SMI-6274 (Wave 4), SMI-5894 (the (client, name) keying precedent this
+ *   extends to scope), SMI-1630 (the repo-local-overrides-global promise this generalizes)
+ *
+ * Two scopes, both per-client:
+ *   - `global`    — `CLIENT_NATIVE_PATHS[client]` (unchanged).
+ *   - `workspace` — `<workspace-root>/<client's workspace segments>`, from
+ *     {@link CLIENT_WORKSPACE_SEGMENTS} (a sibling table to `CLIENT_NATIVE_PATHS`
+ *     in `./paths.ts`).
+ *
+ * {@link findWorkspaceRoot} is deliberately NOT a reuse of
+ * `findMainRepoRoot()` (`packages/doc-retrieval-mcp/src/retrieval-log/project-dir.ts`).
+ * That helper requires `.git` to be a real DIRECTORY, specifically so it skips
+ * worktrees and returns the *main* repo root — correct for its own purpose
+ * (telemetry attribution) and exactly wrong here: `.git` is a *file* in both
+ * worktrees and submodules, and this repo's own default development workflow
+ * is worktree-based, so requiring a directory would resolve every worktree's
+ * workspace installs back to the main checkout. `findWorkspaceRoot()` tests
+ * path EXISTENCE (`existsSync`), never `isDirectory()`, for `.git` — the two
+ * walks are near-neighbours with deliberately OPPOSITE `.git` predicates; see
+ * `findMainRepoRoot()`'s own header note pointing back here.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { loadConfig } from '../config/index.js';
+import { CLIENT_NATIVE_PATHS } from './paths.js';
+/**
+ * Workspace-relative path segments per client, sibling table to
+ * `CLIENT_NATIVE_PATHS` (`./paths.ts`). `null` means the client has no
+ * documented workspace convention and can only ever resolve to `global`
+ * scope — adding one later is a table entry here, not a code change
+ * (ADR-139 Consequences / Neutral).
+ *
+ * Verified 2026-08-29 against `docs/internal/research/smi-5386-opencode-antigravity-skill-dirs.md`
+ * and ADR-139's own Decision §1: `antigravity` and `agents` deliberately
+ * share the SAME segments (`.agents/skills`) — AntiGravity reads project
+ * skills from the same open-standard cross-agent convention `agents`'
+ * GLOBAL path (`~/.agents/skills`) already uses, which is exactly the
+ * pathological case ADR-139 point 4's termination-before-candidacy fix
+ * exists for (see `findWorkspaceRoot` below).
+ */
+export const CLIENT_WORKSPACE_SEGMENTS = {
+    'claude-code': ['.claude', 'skills'],
+    cursor: ['.cursor', 'skills'],
+    copilot: null,
+    windsurf: null,
+    agents: ['.agents', 'skills'],
+    opencode: ['.opencode', 'skills'],
+    hermes: null,
+    grok: null,
+    antigravity: ['.agents', 'skills'],
+};
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+/** An explicit `--scope`/`SKILLSMITH_SCOPE` value that isn't `global`/`workspace`. */
+export class InvalidScopeValueError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidScopeValueError';
+    }
+}
+/**
+ * An explicit workspace-scope request (flag, env var, or config default)
+ * that cannot be satisfied — the client has no workspace convention, or no
+ * workspace root exists above `cwd`. ADR-139 point 2: this is a HARD ERROR,
+ * never a silent downgrade to global.
+ */
+export class UnsatisfiableWorkspaceScopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnsatisfiableWorkspaceScopeError';
+    }
+}
+/**
+ * Parse a raw `--scope`/`SKILLSMITH_SCOPE` string. Returns `undefined` for
+ * an absent/empty value (meaning "no opinion at this rank" — the caller
+ * falls through to the next precedence rank), and throws for anything
+ * present but not `global`/`workspace`.
+ */
+export function parseInstallScope(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    if (raw === 'global' || raw === 'workspace')
+        return raw;
+    throw new InvalidScopeValueError(`Invalid scope '${raw}'. Valid values: global | workspace.`);
+}
+function isInstallScope(value) {
+    return value === 'global' || value === 'workspace';
+}
+/**
+ * Per-client persisted default scope from `~/.skillsmith/config.json`
+ * (`defaultScope.<client>`, e.g. `defaultScope.antigravity = "workspace"`).
+ * Fails soft (`undefined`) on any read/parse error — a corrupt config file
+ * must never crash scope resolution, only fall through to auto-detection.
+ */
+export function getDefaultScopeForClient(client) {
+    try {
+        const config = loadConfig();
+        const raw = config.defaultScope?.[client];
+        return isInstallScope(raw) ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Ancestor-search boundary (ADR-139 points 3 + 4)
+// ---------------------------------------------------------------------------
+/**
+ * Loop guard against symlink cycles / pathological mounts — matches the cap
+ * `findMainRepoRoot()` (`project-dir.ts`) already uses, so the two walks
+ * agree on their one shared parameter rather than picking independent
+ * numbers. NOT a configurable max depth (ADR-139 point 4): a configurable
+ * cap makes the same command behave differently on two machines and is
+ * effectively undebuggable when it silently stops one level short of a
+ * marker.
+ */
+const MAX_ANCESTOR_WALK_DEPTH = 64;
+/**
+ * Resolve the nearest workspace root for `client` above (and including)
+ * `cwd`, or `null` when `cwd` is outside any workspace for that client.
+ *
+ * Implements ADR-139 point 4's algorithm EXACTLY, including its load-bearing
+ * ordering: at every directory in the walk, **termination is evaluated
+ * before candidacy**. An earlier draft of ADR-139 checked candidacy first,
+ * which meant a walk reaching `$HOME` would test `$HOME/<segments>` for a
+ * marker BEFORE applying "stop, no match" — and for the `agents` client,
+ * `$HOME/.agents/skills` IS the GLOBAL path, so that ordering collapsed
+ * global and workspace scope for that client. Termination-before-candidacy
+ * is the fix; do not reorder these two phases.
+ *
+ * `$HOME` is an EXCLUSIVE bound: the walk stops AT it without ever
+ * considering it as a candidate. `.git` existence is checked via
+ * `existsSync` (file OR directory) — see the module header for why this is
+ * the opposite predicate from `findMainRepoRoot()`.
+ */
+export function findWorkspaceRoot(cwd, client, options = {}) {
+    const segments = CLIENT_WORKSPACE_SEGMENTS[client];
+    if (!segments)
+        return null;
+    const home = options.homeDirOverride ?? homedir();
+    let current = resolve(cwd);
+    let vcsFallback = null;
+    for (let depth = 0; depth < MAX_ANCESTOR_WALK_DEPTH; depth += 1) {
+        // ---- PHASE 1: TERMINATION (always first — see doc comment above) ----
+        if (current === home)
+            break;
+        // ---- PHASE 2: CANDIDACY (only for directories that survived phase 1) ----
+        if (existsSync(join(current, ...segments))) {
+            return { root: current, via: 'marker' };
+        }
+        if (existsSync(join(current, '.git'))) {
+            vcsFallback = current;
+            break; // the first VCS boundary also terminates the marker search
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break; // filesystem root
+        current = parent;
+    }
+    return vcsFallback ? { root: vcsFallback, via: 'vcs' } : null;
+}
+/** `<workspaceRoot>/.skillsmith/manifest.json` — self-scoping, self-cleaning (ADR-139 point 1). */
+export function resolveWorkspaceManifestPath(workspaceRoot) {
+    return join(workspaceRoot, '.skillsmith', 'manifest.json');
+}
+function defaultGlobalManifestPath() {
+    return join(homedir(), '.skillsmith', 'manifest.json');
+}
+/**
+ * Resolve the install scope for one `(client, cwd)` pair per ADR-139 point 2's
+ * five-rank precedence:
+ *
+ *   1. Explicit `--scope` flag
+ *   2. `SKILLSMITH_SCOPE` env var
+ *   3. Per-client `~/.skillsmith/config.json` default
+ *   4. Auto-detection of an EXISTING workspace marker (read-only, never creates)
+ *   5. Global (default)
+ *
+ * Ranks 1-3 all represent an explicit request for a scope: requesting
+ * `workspace` at any of these ranks resolves via {@link findWorkspaceRoot}
+ * and, when the walk found a VCS boundary but no marker yet, CREATES the
+ * marker directory (`mkdirSync(..., { recursive: true })`) — this is the
+ * ONLY path that ever creates a workspace directory (ADR-139 point 5).
+ * Requesting `workspace` for a client with no workspace convention, or from
+ * outside any workspace entirely (no marker AND no ancestor `.git`), throws
+ * {@link UnsatisfiableWorkspaceScopeError} — never a silent downgrade.
+ *
+ * Rank 4 (auto-detection) is deliberately narrower: it only matches an
+ * EXISTING marker directory (`findWorkspaceRoot(...).via === 'marker'`) — a
+ * bare VCS boundary with no marker does NOT count as an auto-detected hit,
+ * and this rank never creates anything. Falling through this rank with no
+ * match resolves to rank 5 (global) silently and successfully — the
+ * ordinary case, not a warning-worthy one (ADR-139 point 6).
+ */
+export function resolveSkillScope(params) {
+    const { client } = params;
+    const cwd = params.cwd ?? process.cwd();
+    const segments = CLIENT_WORKSPACE_SEGMENTS[client];
+    const findOpts = params.homeDirOverride !== undefined ? { homeDirOverride: params.homeDirOverride } : {};
+    const fromFlag = params.explicitScope;
+    const envRaw = params.envScope !== undefined ? params.envScope : process.env['SKILLSMITH_SCOPE'];
+    const fromEnv = fromFlag === undefined ? parseInstallScope(envRaw) : undefined;
+    const fromConfig = fromFlag === undefined && fromEnv === undefined
+        ? params.configDefaultScope === undefined
+            ? getDefaultScopeForClient(client)
+            : (params.configDefaultScope ?? undefined)
+        : undefined;
+    const requested = fromFlag ?? fromEnv ?? fromConfig;
+    const requestSource = fromFlag !== undefined
+        ? 'the --scope flag'
+        : fromEnv !== undefined
+            ? 'the SKILLSMITH_SCOPE environment variable'
+            : fromConfig !== undefined
+                ? `the ~/.skillsmith/config.json default for '${client}'`
+                : undefined;
+    if (requested === 'global') {
+        return { scope: 'global', dir: CLIENT_NATIVE_PATHS[client], created: false };
+    }
+    if (requested === 'workspace') {
+        if (!segments) {
+            throw new UnsatisfiableWorkspaceScopeError(`Workspace scope was requested (via ${requestSource}) but client '${client}' has no ` +
+                `documented workspace convention — it can only be installed at global scope.`);
+        }
+        const found = findWorkspaceRoot(cwd, client, findOpts);
+        if (!found) {
+            throw new UnsatisfiableWorkspaceScopeError(`Workspace scope was requested (via ${requestSource}) but no workspace root was found ` +
+                `at or above '${cwd}' — no existing ${segments.join('/')} directory and no ancestor ` +
+                `.git. Run this from inside a repository, or drop --scope to install globally.`);
+        }
+        const dir = join(found.root, ...segments);
+        if (found.via === 'marker') {
+            return { scope: 'workspace', dir, workspaceRoot: found.root, via: 'marker', created: false };
+        }
+        // via === 'vcs': no marker exists on disk yet. An explicit workspace
+        // request (any of ranks 1-3) is the ONLY thing permitted to create one.
+        mkdirSync(dir, { recursive: true });
+        return { scope: 'workspace', dir, workspaceRoot: found.root, via: 'vcs', created: true };
+    }
+    // Rank 4: auto-detection. Only an EXISTING marker counts — never the bare
+    // VCS fallback, and this rank never creates anything.
+    if (segments) {
+        const found = findWorkspaceRoot(cwd, client, findOpts);
+        if (found && found.via === 'marker') {
+            return {
+                scope: 'workspace',
+                dir: join(found.root, ...segments),
+                workspaceRoot: found.root,
+                via: 'marker',
+                created: false,
+            };
+        }
+    }
+    // Rank 5: global, silently and successfully.
+    return { scope: 'global', dir: CLIENT_NATIVE_PATHS[client], created: false };
+}
+/**
+ * Convenience wrapper over {@link resolveSkillScope} that also resolves the
+ * manifest path to record the install in — the one call CLI/MCP commands
+ * need for `install`/`list`/`update`/`remove` (ADR-139 point 7: "One shared
+ * resolver, in core, for every command").
+ */
+export function resolveScopedSkillsDir(params) {
+    const resolved = resolveSkillScope(params);
+    const manifestPath = resolved.scope === 'workspace' && resolved.workspaceRoot
+        ? resolveWorkspaceManifestPath(resolved.workspaceRoot)
+        : (params.globalManifestPath ?? defaultGlobalManifestPath());
+    return { ...resolved, manifestPath };
+}
+//# sourceMappingURL=workspace-scope.js.map

package/dist/src/install/workspace-scope.js.map

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

package/dist/src/install/workspace-scope.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workspace-scope.test.d.ts.map

package/dist/src/install/workspace-scope.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-scope.test.d.ts","sourceRoot":"","sources":["../../../src/install/workspace-scope.test.ts"],"names":[],"mappings":""}