@microwiseai/snapshot 0.9.1 → 0.9.3

package/node_modules/@microwiseai/skit/dist/lib.d.ts

@@ -4,31 +4,325 @@
  * Programmatic access to skit installation functionality.
  * Designed for use by other packages that need to install skits programmatically.
  */
-import { type InstallSummary, type SkitManifest } from './types/skit.js';
+export declare const REGISTRY_PROXY_URL = "https://registry-proxy.sisung-kim1.workers.dev";
+import { type InstallSummary, type SkitManifest, type NpmDependencySpec, type NpmDependencySource, type ScopeRegistryMapping, POLICY_NAME_PATTERN, isValidPolicyName, readManifestPolicy } from './types/skit.js';
+import { resolveGenericTarget, execFetchGeneric } from '@glpkg/cli';
+import { type DepsMode, type DepPlanEntry, type DeclaredDep } from './utils/dep-plan.js';
 import { type InstalledRegistry, type InstalledKit } from './utils/installed-registry.js';
 /**
- * Get registry URL (from env or default)
- * @internal Exported for testing
+ * Resolve the registry/proxy base URL via the P1 generalization chain
+ * (docs/p1-registry-generalization-design.md). Precedence, highest first:
+ *   ① `IST_REGISTRY_URL` env  — the shared cross-tool override (installer).
+ *   ② `SKIT_REGISTRY` env     — legacy alias (installer; preserves prior behavior).
+ *   ③ `~/.config/skit/config.json` `registryUrl` — installer config file.
+ *   ④ built-in `REGISTRY_PROXY_URL` — last-resort fallback (backward-compatible).
+ *
+ * Each layer is FAIL-SOFT: an empty/blank value is skipped, and a non-http(s)
+ * value is skipped with a single warning (never throws, never a broken install)
+ * — resolution falls through to the next layer. With no env and no config file,
+ * this returns `REGISTRY_PROXY_URL` verbatim, so the zero-config microwiseai flow
+ * is 100% unchanged. @internal Exported for testing
  */
 export declare function getRegistryUrl(): string;
+/** Built-in GitLab host fallback — last resort of getGitlabHost's chain (P2 #4). */
+export declare const DEFAULT_GITLAB_HOST = "gitlab.com";
+/**
+ * Resolve the GitLab host via the P2 chain (installer axis), highest first:
+ *   ① `IST_GITLAB_HOST` env  — shared cross-tool override.
+ *   ② `~/.config/skit/config.json` `gitlabHost`.
+ *   ③ built-in `DEFAULT_GITLAB_HOST` ('gitlab.com').
+ *
+ * FAIL-SOFT (P1 pattern): blank values are skipped; a value carrying a scheme is
+ * accepted but normalized to the bare host WITH a warning (glpkg wants a bare
+ * host); a value that normalizes to empty is skipped with a warning. With no env
+ * and no config, returns 'gitlab.com' — backward-compatible.
+ *
+ * ⚠ P2 T1 STATUS: this resolver is CORRECT and tested, but its result is NOT yet
+ * consumed end-to-end for the kit download — glpkg's `resolveGenericTarget`
+ * derives the host from its own ConfigManager scope-mapping and exposes no host
+ * override, and `@glpkg/cli` exports no ConfigManager for skit to synthesize one.
+ * So on the gitlab-direct path the host is INERT until T2 (glpkg). @internal
+ */
+export declare function getGitlabHost(): string;
+/**
+ * Resolve the effective GitLab group NAME via the P2 chain, highest first:
+ *   ① manifest `registry[scope].group` — AUTHOR axis, per-scope (when available).
+ *   ② `IST_GITLAB_GROUP` env — installer default.
+ *   ③ `~/.config/skit/config.json` `gitlabGroup` — installer config default.
+ *   ④ `undefined` — caller/glpkg falls back to its bundled-scope-map.
+ *
+ * Returns a NAME only (never a numeric id — id resolution is glpkg's job, T2).
+ * `registry`/`scope` are optional because at kit-DOWNLOAD time the manifest is
+ * not yet parsed (chicken-and-egg, cf. P1 §0), so the author layer only applies
+ * where a manifest mapping is already in hand.
+ *
+ * ⚠ P2 T1 STATUS: INERT on the kit-download path for the same reason as
+ * getGitlabHost — glpkg's Phase-A resolution does not accept a group override
+ * from skit yet (T2). @internal
+ */
+export declare function getGitlabGroup(registry?: ScopeRegistryMapping, scope?: string): string | undefined;
+/**
+ * The ONE GitLab group setting for kit downloads and CLI installs:
+ * `--group` > IST_GITLAB_GROUP > skit config `gitlabGroup`. No scope→group
+ * table or inference (glpkg removed scope mapping; skit does not re-add it).
+ */
+export declare function resolveGitlabGroupSetting(optsGroup?: string): string | undefined;
+/** Guidance when no group is set (kit download / CLI install). */
+export declare const GITLAB_GROUP_HINT = "Set it once with 'skit config set gitlabGroup <group>', or pass '--group <group>' (or IST_GITLAB_GROUP).";
 /**
  * Get session ID (provided by snapshot)
  * skit does NOT know LICENSE_KEY - only SESSION_ID
  * @internal Exported for testing
  */
 export declare function getSessionId(): string | undefined;
+/**
+ * Registry source selection (glpkg FROZEN contract `--source gitlab|proxy`).
+ * - 'gitlab': install directly from the GitLab group registry (needs a token/PAT)
+ * - 'proxy':  install via the registry-proxy (anonymous/Bearer; server-gated)
+ */
+export type InstallSource = 'gitlab' | 'proxy';
+/**
+ * Parse extra known scopes from the SKIT_REGISTRY_MAPPING env var (CSV).
+ *
+ * Env-override layer of the group-resolution chain (glpkg ADR §4B.6): lets a user
+ * register additional scopes at runtime — routed to the bundled default group —
+ * without a code change. Revived (was a stale test in C1) as the chosen home for
+ * env-level scope overrides; the manifest `glpkg.groups` block (§4C) covers the
+ * committed/per-project case.
+ *
+ * Rule: comma-split → trim each → drop empties.
+ * @internal Exported for testing
+ */
+export declare function getScopesFromEnv(): string[];
 export type { SkitManifest, SkitComponent, SkitCli, SkitComponents, InstallSummary, InstallResult, } from './types/skit.js';
 export type { InstalledKit, InstalledRegistry } from './utils/installed-registry.js';
+export type { DepsMode, DepAction, DepWarning, DepPlanEntry } from './utils/dep-plan.js';
+export { DEPS_MODES, DEFAULT_DEPS_MODE, parseDepsMode, formatDepPlan, decideDep, planDeps, } from './utils/dep-plan.js';
+export { POLICY_NAME_PATTERN, isValidPolicyName, readManifestPolicy };
+/** Public npmjs registry — pins npmjs-native scopes (see NPMJS_NATIVE_SCOPES). */
+export declare const NPMJS_REGISTRY = "https://registry.npmjs.org/";
+/**
+ * BUILT-IN npmjs-native scopes (default). Scopes whose packages live on public
+ * npmjs, NOT the GitLab registry proxy — the proxy serves only GitLab-hosted
+ * packages and blocks npm fallback, so these scopes 401 there. skit routes them
+ * to npmjs regardless of a manifest's declared `source` (e.g. `@glpkg/cli` is
+ * npmjs-native even though the bundled scope map lists `@glpkg` for GitLab group
+ * resolution of other artifacts).
+ *
+ * This is the DEFAULT set; a third party extends it via `SKIT_NPMJS_SCOPES`
+ * (see {@link getNpmjsNativeScopes}). Kept exported (and unchanged: `{@glpkg}`)
+ * for backward compatibility.
+ */
+export declare const NPMJS_NATIVE_SCOPES: Set<string>;
+/**
+ * Parse extra npmjs-native scopes from the `SKIT_NPMJS_SCOPES` env var (CSV).
+ * Lets a third party declare their OWN npmjs-published scopes so they route to
+ * public npmjs instead of 401ing on the proxy — without a code change. Each
+ * entry is trimmed, emptied-dropped, and normalized to a leading `@`.
+ * Rule mirrors {@link getScopesFromEnv}. @internal Exported for testing.
+ */
+export declare function getNpmjsScopesFromEnv(): string[];
+/**
+ * Effective npmjs-native scope set = built-in {@link NPMJS_NATIVE_SCOPES} ∪
+ * `SKIT_NPMJS_SCOPES` env. Read fresh each call (env-driven, like
+ * {@link getScopesFromEnv}). With no env set, equals the default — 100%
+ * backward-compatible. @internal Exported for testing.
+ */
+export declare function getNpmjsNativeScopes(): Set<string>;
+/**
+ * Whether a scope's packages resolve from public npmjs rather than the proxy.
+ * Honors both the built-in defaults and the `SKIT_NPMJS_SCOPES` env extension.
+ */
+export declare function isNpmjsNativeScope(scope: string | undefined): boolean;
+/**
+ * Resolve a scope to its GitLab group. ([B] de-risk, 2026-08-07) The owner
+ * group-id/name hardcode has been REMOVED — group identity now comes ONLY from
+ * the manifest `registry` chain (`registry[scope].group`), keeping this a
+ * gitlab-direct / index-publish concern and out of the anonymous install path.
+ *
+ * `groupId` is best-effort 0 (the manifest carries the group NAME, not the
+ * numeric id); index/publish callers already treat a 0 id as "unknown".
+ * Version enumeration does not use this (it goes through the proxy F1 endpoint,
+ * which routes scope→group server-side). Returns undefined when the scope has no
+ * declared group. @internal Exported for testing
+ */
+export declare function resolveScopeGroup(scope: string, registry?: ScopeRegistryMapping | Record<string, {
+    group?: string;
+}>): {
+    name: string;
+    id: number;
+} | undefined;
+/**
+ * Find the declared GitLab group for a package from a group-keyed mapping
+ * (skit.json `glpkg.groups`, §4C). Returns the group name or undefined.
+ * @internal Exported for testing
+ */
+export declare function findDeclaredGroup(groups: Record<string, string[]> | undefined, packageName: string): string | undefined;
+/**
+ * Build the glpkg command for a generic (kit tarball) download.
+ *
+ * ★ No hardcoded `--group`: by default group resolution is delegated to glpkg's
+ * discovery chain (manifest > persisted > server > bundled map). `--group` is
+ * added ONLY as an explicit override; `--source` selects gitlab|proxy when given.
+ * @internal Exported for testing
+ */
+export declare function buildGenericDownloadCommand(opts: {
+    pkgSpec: string;
+    stagingDir: string;
+    group?: string;
+    source?: InstallSource;
+}): string;
+/**
+ * Build the glpkg command to install a CLI tool globally (`-g` = `--global`).
+ *
+ * glpkg ≥0.16: every package names its source — `--group <g>` (GitLab group;
+ * `--source proxy|gitlab` only applies with it) or `--external` (the npm
+ * registry). A global install neither reads nor writes `glpkg.lock.json`, so
+ * the source must be on the command line every time. `group` undefined ⇒
+ * `--external`. See {@link resolveCliInstallGroup}.
+ * @internal Exported for testing
+ */
+export declare function buildGlobalInstallCommand(pkgSpec: string, source?: InstallSource, group?: string): string;
+/**
+ * GitLab group a CLI package installs from (glpkg ≥0.16 needs it explicitly):
+ *  - unscoped, or an npmjs-native scope (`@glpkg`, SKIT_NPMJS_SCOPES) → undefined
+ *    (= `--external`, the npm registry);
+ *  - else the kit's own `registry[scope].group` (kit data), else the group
+ *    setting ({@link resolveGitlabGroupSetting}: --group > IST_GITLAB_GROUP >
+ *    skit config);
+ *  - none → throws with {@link GITLAB_GROUP_HINT}.
+ * @internal Exported for testing
+ */
+export declare function resolveCliInstallGroup(pkgName: string, registry?: ScopeRegistryMapping, optsGroup?: string): string | undefined;
+/**
+ * Version metadata returned by the proxy anonymous version-enumeration endpoint
+ * (F1 contract, registry-proxy/docs/group-source-install/F1-version-endpoint-contract.md).
+ */
+export interface VersionMetadata {
+    name: string;
+    /** all versions, semver DESC, deduped */
+    versions: string[];
+    /** highest STABLE version (npm dist-tag semantics) */
+    latest: string;
+    /** echoed when ?range= was supplied */
+    range?: string;
+    /** false => resolve client-side from `versions` */
+    rangeSupported?: boolean;
+    /** highest version satisfying range, or null */
+    resolved?: string | null;
+}
+/**
+ * Fetch version metadata from the proxy version-enumeration endpoint (anonymous).
+ *
+ * Tries the candidate URLs in order (see `versionEndpointCandidates` for why two
+ * exist) and returns the first valid 200 `VersionMetadata` body. A 400/404 on one
+ * candidate is treated as "wrong shape / not here" and falls through to the next;
+ * a network/reach error is surfaced as an error (NOT "no versions").
+ *
+ * Replaces the former direct GitLab Packages API call (which needed a glpkg
+ * token) — version listing is non-sensitive and the proxy serves it anonymously,
+ * enabling token-less `latest`/range resolution.
+ * @internal Exported for testing
+ */
+export declare function fetchVersionMetadata(packageName: string, range?: string): Promise<VersionMetadata>;
+/**
+ * Resolve the latest (highest stable) version of a package via the F1 endpoint.
+ * @internal Exported for testing
+ */
+export declare function resolveLatestVersion(packageName: string): Promise<string>;
+/** A failed distkit selection (the `ok: false` arm of `selectVersion`). */
+type KitSelectionFailure = {
+    code: string;
+    message: string;
+    prereleases: readonly string[];
+};
+/**
+ * skit-worded message for a failed version selection (distkit `selectVersion`
+ * on the proxy route, glpkg's — same distkit — on the gitlab route). The hints
+ * name `skit` commands, never `glpkg`.
+ * @internal Exported for testing
+ */
+export declare function formatKitSelectionFailure(packageName: string, spec: string | undefined, f: KitSelectionFailure): string;
+/**
+ * Pick ONE kit version from a registry's list — distkit `selectVersion`
+ * (strategy `stable-default`), called DIRECTLY (ADR 0001; never via a glpkg
+ * re-export):
+ *  - unspecified / `latest` → highest stable; no stable at all → error that lists
+ *    the prereleases;
+ *  - range → highest STABLE in range (a range never selects a prerelease, even
+ *    one that names a prerelease, e.g. `>=0.11.0-dev.0` → NO_MATCH);
+ *  - exact (prerelease allowed) → only if published.
+ * Throws a skit-worded error ({@link formatKitSelectionFailure}).
+ * @internal Exported for testing
+ */
+export declare function selectKitVersion(available: readonly string[], packageName: string, spec?: string): string;
+/**
+ * Resolve a requested version string (latest | exact | range) to a concrete
+ * version via the F1 endpoint. latest/range are always decided CLIENT-side from
+ * the full `versions` list with distkit's policy ({@link selectKitVersion}) —
+ * the server's `resolved`/`latest` are not trusted. An exact version is passed
+ * through (the download itself 404s when it is not published).
+ * @internal Exported for testing
+ */
+export declare function resolveRequestedVersion(packageName: string, requested: string): Promise<string>;
 /**
  * Install options for programmatic use
  */
 export interface InstallSkitOptions {
     /** Working directory (defaults to cwd) */
     cwd?: string;
-    /** Don't actually install, just return what would be installed */
+    /**
+     * Don't actually install, just return what would be installed. A remote /
+     * .tgz kit IS fetched into staging (then removed) so its manifest and
+     * dependency plan (`result.depPlan`) can be computed.
+     */
     dryRun?: boolean;
-    /** Skip dependency installation */
+    /**
+     * Global dependency mode for `dependencies.npm` AND `components.clis`:
+     * - 'satisfied' (default): keep an installed version that satisfies the
+     *   declared range (D2: a prerelease satisfies only a range naming it); never
+     *   downgrade one above the range; install missing/below-range.
+     * - 'missing': keep ANY installed version; install only absent deps.
+     * - 'all': reinstall every dep unconditionally (behavior of <=0.1.43).
+     * - 'none': install no global deps.
+     */
+    deps?: DepsMode;
+    /** Dependency names to exclude regardless of mode (npm name or CLI name). */
+    skipDeps?: string[];
+    /**
+     * Skip dependency installation.
+     * @deprecated alias for `deps: 'none'` (an explicit `deps` wins).
+     */
     skipDependencies?: boolean;
+    /**
+     * Asked once per risky `change` (downgrade / prerelease→stable). Return false
+     * to keep the installed version (the entry becomes `skip`). When omitted the
+     * change proceeds (warn only) — the CLI wires a TTY y/N prompt here.
+     */
+    confirmChange?: (entry: DepPlanEntry) => boolean | Promise<boolean>;
+    /**
+     * Receives the dependency plan (before anything is installed). When omitted
+     * the formatted plan lines go to `onProgress`.
+     */
+    onDepPlan?: (plan: DepPlanEntry[], mode: DepsMode) => void;
+    /**
+     * Annotate `keep` entries with a newer in-range registry version (network).
+     * Only honored with `dryRun`. Default false.
+     */
+    checkNewerInRange?: boolean;
+    /** @internal Installed-version lookup override (tests); defaults to `npm root -g` + fs. */
+    installedVersionLookup?: (name: string) => string | undefined;
+    /**
+     * Explicit GitLab group override (group-resolution chain step 1). Normally
+     * omitted so glpkg's discovery chain resolves + persists the group.
+     */
+    group?: string;
+    /**
+     * Registry source: 'gitlab' (direct) or 'proxy' (registry-proxy). When unset,
+     * the kit download keeps its session-based routing and dep/CLI installs default
+     * to 'proxy' (D2 gap closure).
+     */
+    source?: InstallSource;
     /** Progress callback for status updates */
     onProgress?: (message: string) => void;
 }
@@ -50,6 +344,10 @@ export interface InstallSkitResult {
     version: string;
     summary?: InstallSummary;
     manifest?: SkitManifest;
+    /** Global dependency plan actually applied (or that would be, under dryRun). */
+    depPlan?: DepPlanEntry[];
+    /** Effective `--deps` mode. */
+    depsMode?: DepsMode;
     error?: string;
 }
 /**
@@ -61,6 +359,319 @@ export interface DownloadSkitResult {
     outputPath: string;
     error?: string;
 }
+/**
+ * Parse package spec into name and version
+ * @example parsePackageSpec('@ist/devtools-kit@1.0.0') => { name: '@ist/devtools-kit', version: '1.0.0' }
+ * @example parsePackageSpec('@ist/devtools-kit') => { name: '@ist/devtools-kit', version: 'latest' }
+ */
+export declare function parsePackageSpec(packageSpec: string): {
+    name: string;
+    version: string;
+};
+/**
+ * Classify a version string as 'latest', 'exact', or 'range'.
+ * @example classifyVersion('latest') => 'latest'
+ * @example classifyVersion('1.0.0') => 'exact'
+ * @example classifyVersion('^1.0.0') => 'range'
+ */
+export declare function classifyVersion(version: string): 'latest' | 'exact' | 'range';
+/**
+ * Resolve a version string against a list of available versions (sorted descending).
+ * - 'latest' → highest STABLE version (prerelease only if no stable exists);
+ *   input order is not trusted (sorted with semver.rcompare)
+ * - exact → returns if available, else null
+ * - range → uses semver.maxSatisfying
+ */
+export declare function resolveVersion(versions: string[], range: string): string | null;
+/**
+ * Determine what version string to record in skit.json dependencies.
+ * - If requestedRange is a range (^, ~, x, >=), preserve it as-is
+ * - Otherwise (exact or no range), use caret prefix (npm default behavior)
+ */
+export declare function toDependencyRecord(resolvedVersion: string, requestedRange?: string): string;
+/**
+ * Convert package name to registry-proxy format
+ * @example toRegistryFormat('@ist/devtools-kit') => 'ist__devtools-kit'
+ */
+export declare function toRegistryFormat(packageName: string): string;
+/**
+ * Generate tarball filename from package name and version
+ * @example getTarballFilename('@ist/devtools-kit', '1.0.0') => 'ist__devtools-kit-1.0.0.tar.gz'
+ */
+export declare function getTarballFilename(packageName: string, version: string): string;
+/**
+ * Outcome of a registry-proxy tarball fetch (TIER 1 of the download chain).
+ * - 'ok':     tarball fetched and extracted successfully.
+ * - 'denied': proxy returned 401/403 — the package is private and the caller
+ *             is not authorized anonymously (fall back to the owner glpkg path).
+ * Any other failure (network error, unexpected non-2xx) throws instead.
+ */
+export type ProxyDownloadOutcome = 'ok' | 'denied' | ProxyDenied;
+/** A 401/403 from the proxy, with the real status + (credential-free) URL. */
+export interface ProxyDenied {
+    outcome: 'denied';
+    status: number;
+    url: string;
+}
+/** Opt-in flag: also send `Authorization: Bearer $IST_SESSION_TOKEN` on proxy tarball GETs. */
+export declare const SKIT_TARBALL_BEARER_ENV = "SKIT_TARBALL_BEARER";
+/**
+ * Headers for a registry-proxy tarball GET.
+ *   - `X-Session-Id` when a sessionId is present (unchanged legacy behavior).
+ *   - `Authorization: Bearer <IST_SESSION_TOKEN>` ONLY when
+ *     `SKIT_TARBALL_BEARER=1` AND `IST_SESSION_TOKEN` is non-empty. Default OFF:
+ *     with the flag unset the headers are byte-identical to before.
+ * The token value is never logged.
+ * @internal Exported for testing
+ */
+export declare function buildProxyTarballHeaders(sessionId?: string, env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * TIER 1 — fetch a kit tarball from the registry-proxy.
+ *
+ * The proxy is the PUBLIC access layer for these packages, so a single call
+ * covers both anonymous (public) and session-authenticated access:
+ *   - If `sessionId` is provided, send `X-Session-Id`.
+ *   - If absent, send NO auth header (anonymous) — returns 200 for public kits.
+ *
+ * Denial semantics: ONLY 401/403 counts as 'denied' (private package / caller
+ * not entitled). A network error is NOT a denial and is surfaced as-is, so we
+ * never misreport connectivity issues as "private".
+ * @internal Exported for testing
+ */
+export declare function downloadTarballViaProxy(name: string, version: string, stagingDir: string, sessionId?: string): Promise<ProxyDownloadOutcome>;
+/**
+ * Injectable seams for {@link downloadKitViaExecutor} — the glpkg executor lib
+ * calls (Phase-A resolve, Phase-B fetch) + the proxy fetch. Defaults are the real
+ * implementations; tests override them for hermetic (no-network) coverage.
+ */
+export interface KitDownloadDeps {
+    resolveTarget?: typeof resolveGenericTarget;
+    execFetch?: typeof execFetchGeneric;
+    downloadViaProxy?: typeof downloadTarballViaProxy;
+    /** Proxy version resolution (latest/range → exact); default resolveRequestedVersion. */
+    resolveVersion?: typeof resolveRequestedVersion;
+}
+/**
+ * GitLab packages-list query rules for skit's OWN list reads (`skit browse`).
+ * Kit version listing is glpkg's (0.16 `resolveGenericTarget` uses the same
+ * rules: created_at desc, per_page 100, x-next-page, package_version).
+ *  - `order_by=created_at&sort=desc&per_page=100` — GitLab's default order is
+ *    created_at ASC (oldest first), and `order_by=version` is a STRING sort
+ *    (0.9.0 > 0.10.0), so it must never be used.
+ *  - read the next page ONLY when the response carries a non-empty `x-next-page`.
+ * @internal Exported for testing
+ */
+export declare const GITLAB_PACKAGES_LIST_QUERY = "order_by=created_at&sort=desc&per_page=100";
+/** True when a GitLab list response says another page follows (non-empty `x-next-page`). */
+export declare function hasGitlabNextPage(res: Response): boolean;
+/**
+ * Download + unpack a kit tarball into `stagingDir`.
+ *
+ * SOURCE SELECTION (0.1.45, owner decision — back to the 7b605de gitlab-first
+ * direction; the 4021a72 proxy-first default is withdrawn):
+ *   - source UNSET (default) or `--source gitlab`: gitlab-direct (distkit
+ *     `gitlab-registry` generic directive → glpkg Phase-A → `execFetchGeneric`).
+ *     Needs the GitLab group setting; a private kit uses the ambient token, a
+ *     public one downloads without a token.
+ *   - `--source proxy`: the registry proxy ONLY when asked for; a 401/403 fails
+ *     loud (no route switch — ADR 0002/0003).
+ *
+ * FAIL-LOUD (report 34 §4): every path ends in a `skit.json` presence check
+ * ({@link assertKitManifestPresent}), so a 401/empty download never masquerades
+ * downstream as "skit.json not found".
+ */
+export declare function downloadKitViaExecutor(packageSpec: string, stagingDir: string, opts?: {
+    group?: string;
+    source?: InstallSource;
+    token?: string | null;
+    onProgress?: (message: string) => void;
+}, deps?: KitDownloadDeps): Promise<'gitlab' | 'proxy'>;
+/**
+ * Normalize a `dependencies.npm` value to its object form. A bare version string
+ * (and an object without an explicit `source`) defaults to `source: 'gitlab'`
+ * — gitlab-direct, anonymous-tolerant (public token-free; private uses the
+ * ambient PAT). A scope without a declared `registry[scope].url` degrades to the
+ * proxy anonymous path at install time (see {@link installNpmDeps}), so this
+ * default never regresses a token-less public install. @internal Exported for testing
+ */
+export declare function normalizeNpmDependency(value: string | NpmDependencySpec): {
+    version: string;
+    source: NpmDependencySource;
+};
+/**
+ * Build a global `npm install` command for one or more `name@version` specs.
+ * `latest` (or a missing version) is passed as the bare package name so npm
+ * resolves the dist-tag. @internal Exported for testing
+ */
+export declare function buildNpmInstallCommand(specs: string[]): string;
+/**
+ * Extract the scope (e.g. `@ist`) from a scoped package name, or undefined for
+ * an unscoped name. @internal Exported for testing
+ */
+export declare function scopeOf(packageName: string): string | undefined;
+/**
+ * Compute the scope set to pre-register in the anonymous proxy `.npmrc` (the
+ * public tokenless install flow). ([B] de-risk, 2026-08-07) The set is now
+ * PARAMETERIZED / DERIVED rather than read off a hardcoded owner-group map — a
+ * union of, in order of intent:
+ *   1. `registryScopes` — scopes DECLARED in the installing manifest's `registry`
+ *      block (the migration target: authors declare their own scopes here);
+ *   2. env `SKIT_REGISTRY_MAPPING` (`getScopesFromEnv`) — runtime routing override;
+ *   3. `LEGACY_ROUTING_SCOPES` — legacy safety net so an un-migrated kit's
+ *      transitive private-scope deps still resolve via the proxy (no 404 on npmjs);
+ *   4. the declared proxy deps' OWN scopes (from `proxySpecs`).
+ *
+ * ROUTING ONLY — carries NO group identity. Keeping the legacy keys here (vs an
+ * empty set) is what preserves the public tokenless flow until kits migrate.
+ *
+ * ★ P5 (distkit adoption, layer-split): this function KEEPS its name + signature
+ * (the `.npmrc` PROJECTION layer) but no longer owns the union algorithm — it now
+ * ADAPTS core `deriveRoutingScopes(registryModel, extraScopes?, origins?)` (the
+ * model-level SSOT). skit maps its 4 scope sources onto core's inputs:
+ *   - manifest `registryScopes` -> a minimal RegistryModel (keys are all core
+ *     reads for scope derivation; `group` is stubbed and never consulted);
+ *   - env `SKIT_REGISTRY_MAPPING` (getScopesFromEnv) + `LEGACY_ROUTING_SCOPES`
+ *     + the declared proxy deps' own scopes -> `extraScopes` overlay.
+ * ★ LEGACY_ROUTING_SCOPES MUST stay in the overlay (safety net) — dropping it
+ * empties the routing set for an un-migrated kit and its transitive private-scope
+ * deps 404 on npmjs. The output is now SORTED (core stable UTF-16 order) rather
+ * than insertion-order; the `.npmrc` consumer treats scopes as a set, so the
+ * ordering change is purely cosmetic (see golden fixture).
+ * @internal Exported for testing
+ */
+export declare function deriveProxyRoutingScopes(opts: {
+    registryScopes?: string[];
+    proxySpecs?: string[];
+}): string[];
+/** TEMP(D5): route an npm dep batch went through (for messages + tests). */
+export type NpmDepRoute = 'gitlab' | 'proxy' | 'npmjs';
+/**
+ * TEMP(D5): how `installNpmDeps` routes deps — the install's source
+ * (`--source`, default gitlab since 0.1.45).
+ */
+export interface NpmDepRouteOptions {
+    /** the install's source; unset = gitlab (the 0.1.45 default). */
+    source?: InstallSource;
+    /** `--group` override — applies to dep gitlab-direct URLs too. */
+    group?: string;
+    onProgress?: (message: string) => void;
+}
+/** @internal TEMP(D5) test-only: reset the group id cache. */
+export declare function resetGitlabGroupIdCache(): void;
+/**
+ * TEMP(D5): GitLab group npm registry URL for a numeric group id.
+ * @internal Exported for testing
+ */
+export declare function buildGitlabGroupNpmUrl(host: string, groupId: number): string;
+/**
+ * TEMP(D5): resolve a GitLab group NAME (or full path) to its numeric id via
+ * `GET /api/v4/groups/<url-encoded name>` with the ambient token (anonymous when
+ * null — a public group still resolves). A numeric input is returned as-is.
+ * Cached per run. Fails loud naming the URL tried.
+ * @internal Exported for testing
+ */
+export declare function resolveGitlabGroupId(host: string, group: string, token: string | null): Promise<number>;
+/**
+ * TEMP(D5): the GitLab-direct npm registry URL for `scope`, or undefined when no
+ * group is known. Precedence: `--group` override > `registry[scope].url` >
+ * group name (`registry[scope].group` > IST_GITLAB_GROUP > skit config) resolved
+ * to its numeric id. @internal Exported for testing
+ */
+export declare function resolveGitlabDepRegistryUrl(scope: string, registry: ScopeRegistryMapping, opts: {
+    group?: string;
+    token: string | null;
+    host?: string;
+}): Promise<string | undefined>;
+/**
+ * Install npm dependencies using plain `npm` — the glpkg BINARY is NOT required
+ * (free-pivot). Batches:
+ * - 'npmjs': source 'npm' / npmjs-native scopes -> public npmjs registry.
+ * - 'proxy': registry-proxy via a temporary scoped .npmrc (inherited proxy auth
+ *            as env REFERENCES only — utils/npm-auth.ts; anonymous otherwise).
+ *            Routing scope set: `deriveProxyRoutingScopes`.
+ * - 'gitlab': GitLab group npm registry via a temporary scoped .npmrc with the
+ *            ambient GitLab PAT (anonymous-tolerant).
+ *
+ * TEMP(D5) ROUTE RULES (hotfix; replaced by D5):
+ * - gitlab (default since 0.1.45, or `--source gitlab`): every non-npmjs dep goes
+ *   gitlab-direct; the URL comes from `--group` / `registry[scope].url` /
+ *   `registry[scope].group` / IST_GITLAB_GROUP / skit config (name → id). None →
+ *   fail loud with the group hint.
+ * - `--source proxy`: every non-npmjs dep goes via the proxy; a failure is NOT
+ *   retried on another route (ADR 0002/0003).
+ * Every failure names the route + registry URL tried.
+ * @internal Exported for testing
+ */
+export declare function installNpmDeps(dependencies: Record<string, string | NpmDependencySpec>, registryScopes?: string[], registry?: ScopeRegistryMapping, route?: NpmDepRouteOptions): Promise<NpmDepRoute[]>;
+/**
+ * Compare two registry URLs for equality, ignoring trailing slashes (glpkg's
+ * `proxy:status` echoes a canonicalized URL with a trailing `/`, ours has none).
+ * @internal Exported for testing
+ */
+export declare function sameRegistryUrl(a: string, b: string): boolean;
+/**
+ * Parse the human-readable output of `glpkg config proxy:status`, e.g.:
+ *
+ *   Proxy Configuration:
+ *     URL:     https://registry-proxy.example.dev/
+ *     Enabled: no
+ *
+ * Returns the configured proxy URL (empty string if unset) and whether the proxy
+ * is enabled. Tolerant of "(not set)" / "none" placeholders. @internal Exported for testing
+ */
+export declare function parseGlpkgProxyStatus(output: string): {
+    url: string;
+    enabled: boolean;
+};
+/**
+ * Compute the idempotent bootstrap plan for making `glpkg install --source proxy`
+ * usable on a clean box (free-install track A):
+ *
+ *   1. `npm install -g @glpkg/cli` — only if the glpkg binary is absent. Public
+ *      npmjs, tokenless; also breaks the glpkg self-install circular dependency.
+ *   2. `glpkg config proxy:set <registryUrl>` — only if the configured proxy URL
+ *      differs from ours (trailing-slash-insensitive).
+ *   3. `glpkg config proxy:enable` — only if the proxy is not already enabled.
+ *
+ * Returns the list of shell commands to run in order. Already-satisfied steps are
+ * omitted, so a fully-bootstrapped box yields an empty plan (idempotent).
+ * @internal Exported for testing
+ */
+export declare function planGlpkgBootstrap(registryUrl: string, state: {
+    binaryPresent: boolean;
+    proxyUrl: string;
+    proxyEnabled: boolean;
+}): string[];
+/**
+ * Injectable IO for {@link ensureGlpkgBootstrap} — probes real glpkg state and
+ * runs shell commands. Swapped out in unit tests. @internal
+ */
+export interface GlpkgBootstrapIO {
+    probeBinary: () => boolean;
+    probeProxy: () => {
+        url: string;
+        enabled: boolean;
+    };
+    run: (command: string) => void;
+}
+/**
+ * @internal Reset the once-per-process bootstrap memo (test-only helper).
+ */
+export declare function resetGlpkgBootstrapMemo(): void;
+/**
+ * Ensure the glpkg binary exists and its registry-proxy config points at our
+ * proxy and is enabled, so `glpkg install --source proxy` works on a clean box
+ * (free-install track A). Reuses REGISTRY_PROXY_URL via {@link getRegistryUrl}
+ * (SSOT) — no new hardcoded URL. Idempotent: each step is skipped when already
+ * satisfied, and the whole routine is a no-op after the first successful call in
+ * a process (recursive skit-dep installs bootstrap only once). Preserves the
+ * tokenless invariant: it never writes auth — glpkg's own anonymous logic (no
+ * token → no .npmrc auth line) is untouched.
+ *
+ * @returns the list of commands that were executed (empty when nothing to do).
+ * @internal Exported for testing
+ */
+export declare function ensureGlpkgBootstrap(registryUrl?: string, io?: GlpkgBootstrapIO): Promise<string[]>;
 /**
  * Install a skit package programmatically
  * Uses GitLab token from ~/.config/gitlab-config for authentication
@@ -82,6 +693,12 @@ export interface DownloadSkitResult {
  * ```
  */
 export declare function installSkit(packageSpec: string, options?: InstallSkitOptions): Promise<InstallSkitResult>;
+/**
+ * Global deps declared by a manifest, in plan order: `dependencies.npm` then
+ * `components.clis` (each CLI also matches `--skip-dep <cli.name>`).
+ * @internal Exported for testing
+ */
+export declare function collectDeclaredDeps(manifest: SkitManifest): DeclaredDep[];
 /**
  * Download a skit package without installing
  *
@@ -141,4 +758,39 @@ export declare function uninstallSkit(packageName: string, options?: {
     removedFiles: string[];
     error?: string;
 }>;
+/**
+ * Result of orphan scan
+ */
+export interface OrphanResult {
+    prompts: string[];
+    profiles: string[];
+}
+/**
+ * Find prompts and profiles not managed by any installed skit
+ *
+ * @example
+ * ```ts
+ * import { findOrphans } from '@ist/skit/lib';
+ *
+ * const orphans = await findOrphans();
+ * console.log('Unmanaged prompts:', orphans.prompts);
+ * console.log('Unmanaged profiles:', orphans.profiles);
+ * ```
+ */
+export declare function findOrphans(): Promise<OrphanResult>;
+/**
+ * Remove orphaned files by their relative paths from ~/.ist/
+ *
+ * @param files - Relative paths from ~/.ist/ (e.g. 'prompts/foo.md')
+ * @returns Array of successfully removed relative paths
+ *
+ * @example
+ * ```ts
+ * import { removeOrphans } from '@ist/skit/lib';
+ *
+ * const removed = await removeOrphans(['prompts/old.md', 'profiles/stale.md']);
+ * console.log(`Removed ${removed.length} files`);
+ * ```
+ */
+export declare function removeOrphans(files: string[]): Promise<string[]>;
 //# sourceMappingURL=lib.d.ts.map