@canonical/pragma-cli 0.34.0 → 0.36.0

package/dist/src/capabilities/shared/packageManager.js

@@ -0,0 +1,349 @@
+/**
+ * Storeless install-source detector, shared by `info`, `upgrade`, and
+ * `doctor`'s `pragma version` check.
+ *
+ * Detection is driven by the FILESYSTEM — the resolved entry path, the invoked
+ * bin path, and the symlinks between them — not by environment variables. The
+ * previous heuristic read `npm_config_user_agent`, which npm/pnpm/yarn/bun set
+ * only when THEY run a script; a user typing the bin name in a shell never has
+ * it, so on the path that mattered the detector always fell through to the
+ * honest runtime and reported `node` for every install. The agent survives
+ * only as a last-resort corroboration for a workspace install whose tree
+ * carries no other marker.
+ *
+ * The two paths that matter, and why both are needed:
+ *
+ * - `import.meta.url` is REALPATH-RESOLVED by the module loader. For a normal
+ *   install it sits inside `node_modules/<pkg>`; for a linked development
+ *   install (`npm link` / `bun link`) it has already escaped to the source
+ *   checkout and contains no `node_modules` at all — which is precisely why an
+ *   entry-only detector cannot see a link.
+ * - `process.argv[1]` preserves the path the user actually invoked, symlinks
+ *   intact. Walking its link chain finds the `node_modules/<pkg>` entry the
+ *   bin points through, and whether THAT directory is itself a symlink
+ *   pointing outside the install root — the linked-install signal. The chain
+ *   is only trusted when the package directory it names really contains the
+ *   running module (`realPath` identity check), so a foreign bin on argv[1]
+ *   (vitest, a wrapper script) never misattributes the install.
+ *
+ * The manager is identified by path SHAPE (`.bun/`, `.pnpm`/`pnpm`, `.volta`,
+ * `.asdf`, yarn's global dir), ephemeral runners by their cache shapes
+ * (`_npx`, `bunx-*`, pnpm's `dlx`), and a workspace's manager by the lockfile
+ * beside the install root. When no signal is conclusive the detector answers
+ * `unknown` — a state with NO update command, because a confidently wrong
+ * `npm i -g` is worse than none (against a linked checkout it would overwrite
+ * the link to the tree being developed). `pmUpdateCommand` accepts only the
+ * {@link GlobalInstall} arm, so offering a command to any other state is a
+ * type error, not a convention.
+ *
+ * Read-only and storeless: a handful of `lstat`/`readlink`/`realpath`/`exists`
+ * probes, bounded by the link-chain cap — nothing is ever written. The module
+ * sits on the fast-path static graph (via the shared barrel), so all probing
+ * happens at call time; module load stays inert.
+ *
+ * Windows note: segment matching splits on both separators, so the SHAPE
+ * checks (`managerFromPath`, `ephemeralRunner`) are exercised against
+ * win32-style fixtures — but scope containment goes through the host's
+ * `node:path` and, like `platformPaths.ts`, the win32 arm is a conventional
+ * best guess that has NOT been validated on a real Windows machine.
+ */
+import { existsSync, readlinkSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { INSTALL_UPDATE_GUIDANCE, installSourceLabel, } from "../../kernel/render/vocabulary.js";
+/** Split on both separators, so shape checks read win32 paths too. */
+const splitPath = (path) => path.split(/[\\/]/);
+/** The separator the input path itself uses (win32 fixtures keep theirs). */
+const sepOf = (path) => (path.includes("\\") ? "\\" : "/");
+/**
+ * The directory a package was installed INTO — the parent of the `node_modules`
+ * holding it, so `/proj/node_modules/@scope/x/dist/bin.js` yields `/proj`.
+ *
+ * The LAST occurrence, because nested `node_modules` mean the innermost one is
+ * the tree the entry actually lives in.
+ *
+ * @param entry - Absolute path to the running module.
+ * @returns The install root, or `undefined` when the entry is not installed at
+ *   all (a source checkout, where no `node_modules` segment appears).
+ * @remarks Exported for its unit test; not part of the package's public surface.
+ */
+export function findInstallRoot(entry) {
+    const segments = splitPath(entry);
+    const index = segments.lastIndexOf("node_modules");
+    return index === -1 ? undefined : segments.slice(0, index).join(sepOf(entry));
+}
+/**
+ * Whether `directory` contains `candidate`, or is it.
+ *
+ * Compared through `relative()` rather than a string prefix: a prefix test needs
+ * a hard-coded separator (wrong on Windows) and would call `/proj-two` a child
+ * of `/proj`.
+ *
+ * @param directory - The containing directory.
+ * @param candidate - The path to test.
+ * @returns True when `candidate` is `directory` or sits beneath it.
+ * @remarks Exported for its unit test; not part of the package's public surface.
+ */
+export function containsPath(directory, candidate) {
+    const offset = relative(directory, candidate);
+    return offset === "" || (!offset.startsWith("..") && !isAbsolute(offset));
+}
+/**
+ * Locate the `node_modules` package a path sits inside — root and package
+ * directory, scope-aware. `node_modules/.bin/...` is NOT a package (the shim
+ * there is a symlink the chain walk should follow instead).
+ */
+function locatePackage(path) {
+    const segments = splitPath(path);
+    const index = segments.lastIndexOf("node_modules");
+    if (index === -1)
+        return undefined;
+    const first = segments[index + 1];
+    if (first === undefined || first === ".bin")
+        return undefined;
+    const span = first.startsWith("@") ? 2 : 1;
+    if (span === 2 && segments[index + 2] === undefined)
+        return undefined;
+    const sep = sepOf(path);
+    return {
+        root: segments.slice(0, index).join(sep),
+        pkgDir: segments.slice(0, index + 1 + span).join(sep),
+    };
+}
+/** The manager a path's shape names, or `undefined` when it names none. */
+export function managerFromPath(path) {
+    const segments = splitPath(path).map((s) => s.toLowerCase());
+    const has = (name) => segments.includes(name);
+    if (has(".bun"))
+        return "bun";
+    if (has(".pnpm") || has("pnpm"))
+        return "pnpm";
+    if (has(".volta") ||
+        segments.some((s, i) => s === "volta" && segments[i + 1] === "tools")) {
+        return "volta";
+    }
+    // asdf/nvm host an ordinary npm global tree inside a versioned node install.
+    if (has(".asdf") || has(".nvm"))
+        return "npm";
+    const yarn = segments.findIndex((s) => s === "yarn" || s === ".yarn");
+    if (yarn !== -1 && segments.indexOf("global", yarn) !== -1)
+        return "yarn";
+    return undefined;
+}
+/**
+ * The ephemeral runner a path's cache shape names, if any.
+ *
+ * Each pattern is anchored to the runner's ACTUAL cache layout, not to a bare
+ * directory name appearing anywhere in the path. A loose match reclassifies an
+ * ordinary project — `/work/dlx/app`, or anything under a directory someone
+ * named `_npx` — as ephemeral, and because that verdict is reached BEFORE the
+ * workspace containment check it wins even when a lockfile sits beside the
+ * root. The failure is quiet rather than loud: an ephemeral install correctly
+ * offers no upgrade command, so the user simply never learns how to update.
+ */
+export function ephemeralRunner(path) {
+    const segments = splitPath(path);
+    // npx caches at `<npm cache>/_npx/<hash>/…` — `~/.npm` on unix,
+    // `%LOCALAPPDATA%\npm-cache` on Windows.
+    const npx = segments.indexOf("_npx");
+    const npxParent = npx > 0 ? segments[npx - 1] : undefined;
+    if (npxParent === ".npm" || npxParent === "npm-cache")
+        return "npx";
+    // bunx materialises `$TMPDIR/bunx-<uid>-<pkg>@<ver>/…`; requiring the uid
+    // keeps a hand-made `bunx-tools` directory from matching.
+    if (segments.some((s) => /^bunx-\d+-/.test(s)))
+        return "bunx";
+    // pnpm caches at `<pnpm cache>/dlx/<hash>/…`.
+    const dlx = segments.indexOf("dlx");
+    if (dlx > 0 && segments[dlx - 1] === "pnpm")
+        return "pnpm dlx";
+    return undefined;
+}
+/** The lockfile beside an install root, mapped to its manager. */
+function lockfileManager(root, exists, sep) {
+    const beside = (name) => exists(`${root}${sep}${name}`);
+    if (beside("bun.lock") || beside("bun.lockb"))
+        return "bun";
+    if (beside("pnpm-lock.yaml"))
+        return "pnpm";
+    if (beside("yarn.lock"))
+        return "yarn";
+    if (beside("package-lock.json"))
+        return "npm";
+    return undefined;
+}
+/** The manager `npm_config_user_agent` names, when present and recognized. */
+function agentManager(agent) {
+    const name = agent?.split("/")[0];
+    return name === "npm" || name === "pnpm" || name === "yarn" || name === "bun"
+        ? name
+        : undefined;
+}
+/** The link-chain hop cap — a symlink cycle must not spin the detector. */
+const MAX_LINK_HOPS = 10;
+/**
+ * Walk `argv[1]`'s symlink chain to the `node_modules` entry it points
+ * through, and trust it only when that package directory really contains the
+ * running module. Returns the FIRST chain path inside a package — before the
+ * package-level symlink is resolved away, which is where the linked-install
+ * signal lives.
+ */
+function resolveInvokedEntry(probe) {
+    if (probe.invoked === undefined)
+        return undefined;
+    let path = resolve(probe.cwd, probe.invoked);
+    for (let hop = 0; hop < MAX_LINK_HOPS; hop++) {
+        const located = locatePackage(path);
+        if (located !== undefined) {
+            // Identity check: only OUR package's bin may classify this process.
+            const real = probe.realPath(located.pkgDir);
+            return real !== undefined && containsPath(real, probe.entry)
+                ? path
+                : undefined;
+        }
+        const target = probe.readLink(path);
+        if (target === undefined)
+            return undefined;
+        path = resolve(dirname(path), target);
+    }
+    return undefined;
+}
+const unknownInstall = (runtime) => ({
+    kind: "unknown",
+    runtime,
+    label: installSourceLabel("unknown", runtime),
+});
+/**
+ * Classify an install from a captured probe — the PURE core of
+ * {@link detectInstallSource}, exercised by the fixture matrix in its test.
+ *
+ * @param probe - The captured paths, environment, and filesystem readers.
+ * @returns The classified install source.
+ */
+export function classifyInstall(probe) {
+    const invokedEntry = resolveInvokedEntry(probe);
+    const installed = invokedEntry ??
+        (locatePackage(probe.entry) !== undefined ? probe.entry : undefined);
+    if (installed === undefined)
+        return unknownInstall(probe.runtime);
+    const located = locatePackage(installed);
+    /* v8 ignore next -- `installed` is only set when locatePackage succeeded */
+    if (located === undefined)
+        return unknownInstall(probe.runtime);
+    const { root, pkgDir } = located;
+    // A package dir that is a symlink pointing OUTSIDE its install root is a
+    // linked development install (`npm link`/`bun link`). Inside the root it is
+    // a store or workspace layout (pnpm's `.pnpm`, a monorepo package) — normal.
+    const rawTarget = probe.readLink(pkgDir);
+    if (rawTarget !== undefined) {
+        const target = resolve(dirname(pkgDir), rawTarget);
+        if (!containsPath(root, target)) {
+            const pm = managerFromPath(installed);
+            return {
+                kind: "linked",
+                ...(pm !== undefined ? { pm } : {}),
+                target,
+                label: installSourceLabel("linked", pm),
+            };
+        }
+    }
+    const runner = ephemeralRunner(installed);
+    if (runner !== undefined) {
+        return {
+            kind: "ephemeral",
+            runner,
+            label: installSourceLabel("ephemeral", runner),
+        };
+    }
+    const shaped = managerFromPath(installed);
+    if (containsPath(root, resolve(probe.cwd))) {
+        // A workspace tree can belong to any manager; the lockfile beside its
+        // root is the marker, the user-agent (when a script runner set it) the
+        // corroboration of last resort.
+        const pm = shaped ??
+            lockfileManager(root, probe.exists, sepOf(installed)) ??
+            agentManager(probe.userAgent);
+        return {
+            kind: "workspace",
+            ...(pm !== undefined ? { pm } : {}),
+            root,
+            label: installSourceLabel("workspace", pm),
+        };
+    }
+    // A global tree with none of the distinctive shapes is npm's: bun, pnpm,
+    // volta and yarn all mark their global roots, npm (and nvm/asdf node
+    // installs, which npm serves) do not. The user-agent is NOT consulted here —
+    // it names whoever ran the script (`bun run …`), not who installed the bin.
+    const pm = shaped ?? "npm";
+    return { kind: "global", pm, label: installSourceLabel("global", pm) };
+}
+/** Capture the live process into a probe (the only impure code here). */
+function liveProbe() {
+    return {
+        entry: fileURLToPath(import.meta.url),
+        invoked: process.argv[1],
+        cwd: process.cwd(),
+        userAgent: process.env.npm_config_user_agent,
+        runtime: process.versions.bun ? "bun" : "node",
+        readLink: (path) => {
+            try {
+                return readlinkSync(path);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        realPath: (path) => {
+            try {
+                return realpathSync(path);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        exists: (path) => existsSync(path),
+    };
+}
+/**
+ * Detect how the binary was installed.
+ *
+ * @param probe - Injected probe (tests); defaults to the live process.
+ * @returns The classified install source.
+ * @note Impure by default — reads `import.meta.url`, `process`, and a bounded
+ *   handful of symlink/realpath/exists probes. Never writes.
+ */
+export function detectInstallSource(probe = liveProbe()) {
+    return classifyInstall(probe);
+}
+/** The global-update command per package manager (install-style). */
+const PM_UPDATE_COMMAND = {
+    bun: (pkg) => `bun add -g ${pkg}`,
+    npm: (pkg) => `npm i -g ${pkg}`,
+    pnpm: (pkg) => `pnpm add -g ${pkg}`,
+    yarn: (pkg) => `yarn global add ${pkg}`,
+    volta: (pkg) => `volta install ${pkg}`,
+};
+/**
+ * The command that updates a GLOBAL install of `pkg`. Accepting only the
+ * {@link GlobalInstall} arm is the point: a linked, ephemeral, workspace, or
+ * unknown install has no sanctioned command, and asking for one is a type
+ * error — {@link updateGuidance} is what those states say instead.
+ *
+ * @param install - The detected global install.
+ * @param pkg - The package to update.
+ * @returns The shell command.
+ */
+export function pmUpdateCommand(install, pkg) {
+    return PM_UPDATE_COMMAND[install.pm](pkg);
+}
+/**
+ * The honest sentence a command-less install state shows when a newer release
+ * exists — see {@link INSTALL_UPDATE_GUIDANCE} for the words.
+ *
+ * @param install - Any non-global install.
+ * @returns The guidance sentence for its state.
+ */
+export function updateGuidance(install) {
+    return INSTALL_UPDATE_GUIDANCE[install.kind];
+}
+//# sourceMappingURL=packageManager.js.map

package/dist/src/capabilities/shared/packageManager.js.map

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

package/dist/src/capabilities/shared/registry.js

@@ -0,0 +1,55 @@
+/**
+ * npm registry version check — the shared network read `info` (enrichment) and
+ * `upgrade` (mutation) both consume.
+ *
+ * Ported verbatim from the old shell's `info/operations/checkRegistryVersion` +
+ * its `DIST_TAG_MAP`/`REGISTRY_TIMEOUT_MS` constants. A single GET against the
+ * registry's package document, a 3s timeout, and `undefined` on any failure
+ * (offline, non-2xx, timeout, missing dist-tag) — so a caller degrades silently
+ * rather than erroring. The whole request is preview-safe: it is a plain read
+ * with no side effects.
+ */
+/**
+ * The published package `info`/`upgrade` check for updates: the stable name
+ * users installed, so the check answers "is a newer release of the tool
+ * available".
+ */
+export const PRAGMA_PACKAGE = "@canonical/pragma-cli";
+/** Maps each release channel to its corresponding npm dist-tag (internal). */
+const DIST_TAG_MAP = {
+    normal: "latest",
+    experimental: "experimental",
+    prerelease: "next",
+};
+/** Timeout in milliseconds for npm registry HTTP requests. */
+export const REGISTRY_TIMEOUT_MS = 3_000;
+/**
+ * Check the npm registry for the latest published version of a package.
+ *
+ * @param packageName - The npm package name (e.g. `@canonical/pragma-cli`).
+ * @param channel - The release channel, selecting which dist-tag to read.
+ * @returns The latest version for the channel's dist-tag, or `undefined` when
+ *   offline / non-2xx / timed out / the dist-tag is absent.
+ * @note Impure — a single network GET (3s timeout, silent-fail).
+ */
+export async function checkRegistryVersion(packageName, channel) {
+    const distTag = DIST_TAG_MAP[channel];
+    const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}`;
+    try {
+        const response = await fetch(url, {
+            signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+            headers: { Accept: "application/json" },
+        });
+        if (!response.ok)
+            return undefined;
+        const data = (await response.json());
+        const version = data["dist-tags"]?.[distTag];
+        if (!version)
+            return undefined;
+        return { latest: version };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/capabilities/shared/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../src/capabilities/shared/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,YAAY,GAA4B;IAC5C,MAAM,EAAE,QAAQ;IAChB,YAAY,EAAE,cAAc;IAC5B,UAAU,EAAE,MAAM;CACnB,CAAC;AAEF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAOzC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,WAAmB,EACnB,OAAgB;IAEhB,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,8BAA8B,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC;IAE5E,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,mBAAmB,CAAC;YAChD,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;SACxC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,SAAS,CAAC;QAEnC,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAElC,CAAC;QACF,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QAE/B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}