@xfey/tutti 0.1.60 → 0.1.62

package/dist/server-shell/package-installation/command.js

@@ -0,0 +1,162 @@
+import { execFile, spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, statSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 16 * 1024;
+const MAX_NPM_CANDIDATES = 12;
+function bounded(value, maxBytes) {
+    const text = typeof value === "string" ? value : (value?.toString("utf8") ?? "");
+    return Buffer.byteLength(text, "utf8") <= maxBytes
+        ? text
+        : Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");
+}
+function classifyCommandError(code) {
+    if (code === "ETIMEDOUT") {
+        return "timeout";
+    }
+    if (code === "ENOBUFS") {
+        return "output_limit";
+    }
+    return "spawn_failed";
+}
+export const runPackageCommandSync = (plan) => {
+    const result = spawnSync(plan.executable, [...plan.args], {
+        encoding: "utf8",
+        env: plan.env,
+        maxBuffer: plan.maxOutputBytes,
+        shell: plan.shell,
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: plan.timeoutMs,
+        windowsHide: true,
+    });
+    return {
+        status: result.status,
+        stdout: bounded(result.stdout, plan.maxOutputBytes),
+        stderr: bounded(result.stderr, plan.maxOutputBytes),
+        ...(result.error === undefined
+            ? {}
+            : {
+                errorCode: classifyCommandError(result.error.code),
+            }),
+    };
+};
+export const runPackageCommand = async (plan) => await new Promise((resolveResult) => {
+    execFile(plan.executable, [...plan.args], {
+        encoding: "utf8",
+        env: plan.env,
+        maxBuffer: plan.maxOutputBytes,
+        shell: plan.shell,
+        timeout: plan.timeoutMs,
+        windowsHide: true,
+    }, (error, stdout, stderr) => {
+        const errorWithCode = error;
+        resolveResult({
+            status: errorWithCode === null
+                ? 0
+                : typeof errorWithCode.code === "number"
+                    ? errorWithCode.code
+                    : null,
+            stdout: bounded(stdout, plan.maxOutputBytes),
+            stderr: bounded(stderr, plan.maxOutputBytes),
+            ...(errorWithCode === null
+                ? {}
+                : {
+                    errorCode: errorWithCode.killed === true
+                        ? "timeout"
+                        : classifyCommandError(errorWithCode.code),
+                }),
+        });
+    });
+});
+function executableCandidate(path) {
+    if (!isAbsolute(path) || !existsSync(path)) {
+        return false;
+    }
+    try {
+        if (!statSync(path).isFile()) {
+            return false;
+        }
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function packagePrefixNpmCandidate(packageRoot, packageName) {
+    const segments = packageName.split("/").reverse();
+    let globalRoot = packageRoot;
+    for (const segment of segments) {
+        if (globalRoot.split(/[\\/]/u).at(-1) !== segment) {
+            return null;
+        }
+        globalRoot = dirname(globalRoot);
+    }
+    if (globalRoot.split(/[\\/]/u).at(-1) !== "node_modules") {
+        return null;
+    }
+    const libDirectory = dirname(globalRoot);
+    if (libDirectory.split(/[\\/]/u).at(-1) !== "lib") {
+        return null;
+    }
+    return join(dirname(libDirectory), "bin", "npm");
+}
+export function collectNpmExecutableCandidates(options) {
+    const collected = [];
+    const add = (candidate) => {
+        if (candidate !== null &&
+            collected.length < MAX_NPM_CANDIDATES &&
+            !collected.includes(candidate) &&
+            executableCandidate(candidate)) {
+            collected.push(candidate);
+        }
+    };
+    add(join(dirname(options.nodeExecutable), "npm"));
+    add(packagePrefixNpmCandidate(options.packageRoot, options.packageName));
+    for (const directory of (options.env.PATH ?? "").split(delimiter)) {
+        if (directory.trim() !== "" && isAbsolute(directory)) {
+            add(join(directory, "npm"));
+        }
+    }
+    return collected;
+}
+const SAFE_ENVIRONMENT_KEYS = [
+    "HOME",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "LOGNAME",
+    "NO_PROXY",
+    "TMPDIR",
+    "USER",
+];
+export function createNpmCommandEnvironment(options) {
+    const result = {};
+    for (const key of SAFE_ENVIRONMENT_KEYS) {
+        const value = options.env[key];
+        if (value !== undefined && value !== "") {
+            result[key] = value;
+        }
+    }
+    const directories = [
+        dirname(options.nodeExecutable),
+        ...(options.env.PATH ?? "").split(delimiter).filter((entry) => isAbsolute(entry)),
+    ];
+    result.PATH = [...new Set(directories)].join(delimiter);
+    result.NPM_CONFIG_UPDATE_NOTIFIER = "false";
+    return result;
+}
+export function createPackageCommandPlan(options) {
+    if (!isAbsolute(options.executable)) {
+        throw new Error("Package commands require an absolute executable path.");
+    }
+    return {
+        executable: options.executable,
+        args: [...options.args],
+        env: { ...options.env },
+        timeoutMs: options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,
+        maxOutputBytes: options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
+        shell: false,
+    };
+}
+//# sourceMappingURL=command.js.map

package/dist/server-shell/package-installation/discovery.d.ts

@@ -0,0 +1,51 @@
+import { type PackageCommandPlan, type PackageCommandRunner } from "./command.js";
+import { PUBLISHED_TUTTI_PACKAGE_NAME, type GlobalPackageInstallation, type GlobalPackageInstallationResolution, type PackageInstallationUnavailableReason } from "./installation.js";
+import { type ExactSemver } from "./semver.js";
+export type PublishedPackageTarget = {
+    packageName: typeof PUBLISHED_TUTTI_PACKAGE_NAME;
+    version: ExactSemver;
+};
+export type PackageUpdateDiscovery = {
+    status: "up_to_date";
+    currentVersion: string;
+    latestVersion: string;
+} | {
+    status: "update_available";
+    currentVersion: string;
+    latestVersion: string;
+    target: PublishedPackageTarget;
+} | {
+    status: "unavailable";
+    currentVersion: string;
+    reasonCode: PackageInstallationUnavailableReason | "registry_unavailable";
+};
+export type GlobalInstallPlan = PackageCommandPlan & {
+    args: readonly [
+        "install",
+        "--global",
+        `${typeof PUBLISHED_TUTTI_PACKAGE_NAME}@${string}`,
+        "--no-audit",
+        "--no-fund"
+    ];
+};
+export declare function discoverPublishedPackageUpdate(options: {
+    installation: GlobalPackageInstallation;
+    runner?: PackageCommandRunner;
+}): Promise<PackageUpdateDiscovery>;
+export declare function buildGlobalInstallPlan(options: {
+    installation: GlobalPackageInstallation;
+    target: PublishedPackageTarget;
+}): GlobalInstallPlan;
+export declare class PackageUpdateDiscoveryService {
+    #private;
+    constructor(options?: {
+        runner?: PackageCommandRunner;
+        now?: () => number;
+        cacheTtlMs?: number;
+    });
+    discover(resolution: GlobalPackageInstallationResolution, options?: {
+        refresh?: boolean;
+    }): Promise<PackageUpdateDiscovery>;
+    clear(): void;
+}
+//# sourceMappingURL=discovery.d.ts.map

package/dist/server-shell/package-installation/discovery.js

@@ -0,0 +1,137 @@
+import { createPackageCommandPlan, runPackageCommand, } from "./command.js";
+import { PUBLISHED_TUTTI_PACKAGE_NAME, } from "./installation.js";
+import { compareExactSemver, parseExactSemver } from "./semver.js";
+const DEFAULT_DISCOVERY_CACHE_TTL_MS = 5 * 60 * 1_000;
+const GLOBAL_INSTALL_TIMEOUT_MS = 5 * 60 * 1_000;
+export async function discoverPublishedPackageUpdate(options) {
+    const result = await (options.runner ?? runPackageCommand)(createPackageCommandPlan({
+        executable: options.installation.npmExecutable,
+        args: ["view", PUBLISHED_TUTTI_PACKAGE_NAME, "dist-tags.latest", "--json"],
+        env: options.installation.npmEnvironment,
+    }));
+    if (result.status !== 0) {
+        return {
+            status: "unavailable",
+            currentVersion: options.installation.currentVersion,
+            reasonCode: "registry_unavailable",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        parsed = null;
+    }
+    const latestVersion = parseExactSemver(parsed);
+    if (latestVersion === null) {
+        return {
+            status: "unavailable",
+            currentVersion: options.installation.currentVersion,
+            reasonCode: "registry_unavailable",
+        };
+    }
+    const comparison = compareExactSemver(latestVersion, options.installation.currentVersion);
+    if (comparison < 0) {
+        return {
+            status: "unavailable",
+            currentVersion: options.installation.currentVersion,
+            reasonCode: "registry_unavailable",
+        };
+    }
+    if (comparison === 0) {
+        return {
+            status: "up_to_date",
+            currentVersion: options.installation.currentVersion,
+            latestVersion,
+        };
+    }
+    return {
+        status: "update_available",
+        currentVersion: options.installation.currentVersion,
+        latestVersion,
+        target: { packageName: PUBLISHED_TUTTI_PACKAGE_NAME, version: latestVersion },
+    };
+}
+export function buildGlobalInstallPlan(options) {
+    if (options.target.packageName !== PUBLISHED_TUTTI_PACKAGE_NAME) {
+        throw new Error("The package update target is invalid.");
+    }
+    const version = parseExactSemver(options.target.version);
+    if (version === null || compareExactSemver(version, options.installation.currentVersion) <= 0) {
+        throw new Error("The package update target must be a newer exact version.");
+    }
+    const plan = createPackageCommandPlan({
+        executable: options.installation.npmExecutable,
+        args: [
+            "install",
+            "--global",
+            `${PUBLISHED_TUTTI_PACKAGE_NAME}@${version}`,
+            "--no-audit",
+            "--no-fund",
+        ],
+        env: options.installation.npmEnvironment,
+        timeoutMs: GLOBAL_INSTALL_TIMEOUT_MS,
+    });
+    return {
+        ...plan,
+        args: [
+            "install",
+            "--global",
+            `${PUBLISHED_TUTTI_PACKAGE_NAME}@${version}`,
+            "--no-audit",
+            "--no-fund",
+        ],
+    };
+}
+export class PackageUpdateDiscoveryService {
+    #runner;
+    #now;
+    #cacheTtlMs;
+    #cache;
+    #pending;
+    constructor(options = {}) {
+        this.#runner = options.runner ?? runPackageCommand;
+        this.#now = options.now ?? Date.now;
+        this.#cacheTtlMs = options.cacheTtlMs ?? DEFAULT_DISCOVERY_CACHE_TTL_MS;
+    }
+    async discover(resolution, options = {}) {
+        if (resolution.status === "unavailable") {
+            return {
+                status: "unavailable",
+                currentVersion: "0.0.0",
+                reasonCode: resolution.reasonCode,
+            };
+        }
+        const installation = resolution.installation;
+        const key = [
+            installation.npmExecutable,
+            installation.globalRoot,
+            installation.currentVersion,
+        ].join("\n");
+        if (options.refresh !== true &&
+            this.#cache?.key === key &&
+            this.#cache.expiresAt > this.#now()) {
+            return this.#cache.result;
+        }
+        if (options.refresh !== true && this.#pending?.key === key) {
+            return await this.#pending.result;
+        }
+        const result = discoverPublishedPackageUpdate({ installation, runner: this.#runner });
+        this.#pending = { key, result };
+        try {
+            const discovered = await result;
+            this.#cache = { key, expiresAt: this.#now() + this.#cacheTtlMs, result: discovered };
+            return discovered;
+        }
+        finally {
+            if (this.#pending?.result === result) {
+                this.#pending = undefined;
+            }
+        }
+    }
+    clear() {
+        this.#cache = undefined;
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/server-shell/package-installation/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./command.js";
+export * from "./discovery.js";
+export * from "./installation.js";
+export * from "./semver.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/server-shell/package-installation/index.js

@@ -0,0 +1,5 @@
+export * from "./command.js";
+export * from "./discovery.js";
+export * from "./installation.js";
+export * from "./semver.js";
+//# sourceMappingURL=index.js.map

package/dist/server-shell/package-installation/installation.d.ts

@@ -0,0 +1,34 @@
+import type { CliPackageIdentity } from "../cli/version.js";
+import { type SyncPackageCommandRunner } from "./command.js";
+import { type ExactSemver } from "./semver.js";
+export declare const PUBLISHED_TUTTI_PACKAGE_NAME = "@xfey/tutti";
+export declare const DEFAULT_NODE_ENGINE = ">=24 <26";
+export declare const DEFAULT_NPM_ENGINE = ">=11 <12";
+export type PackageInstallationUnavailableReason = "installation_not_global" | "custom_home" | "npm_unavailable" | "npm_global_root_mismatch" | "npm_version_unsupported" | "global_prefix_read_only";
+export type GlobalPackageInstallation = {
+    packageName: typeof PUBLISHED_TUTTI_PACKAGE_NAME;
+    currentVersion: ExactSemver;
+    packageRoot: string;
+    globalRoot: string;
+    npmExecutable: string;
+    nodeExecutable: string;
+    npmEnvironment: NodeJS.ProcessEnv;
+};
+export type GlobalPackageInstallationResolution = {
+    status: "eligible";
+    installation: GlobalPackageInstallation;
+} | {
+    status: "unavailable";
+    reasonCode: PackageInstallationUnavailableReason;
+};
+export declare function resolveGlobalPackageInstallation(options: {
+    packageIdentity: CliPackageIdentity;
+    tuttiHome: string;
+    env: NodeJS.ProcessEnv;
+    nodeExecutable?: string;
+    nodeVersion?: string;
+    defaultTuttiHome?: string;
+    runner?: SyncPackageCommandRunner;
+    pathWritable?: (path: string) => boolean;
+}): GlobalPackageInstallationResolution;
+//# sourceMappingURL=installation.d.ts.map

package/dist/server-shell/package-installation/installation.js

@@ -0,0 +1,123 @@
+import { accessSync, constants, existsSync, lstatSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { collectNpmExecutableCandidates, createNpmCommandEnvironment, createPackageCommandPlan, runPackageCommandSync, } from "./command.js";
+import { parseExactSemver, semverMajor } from "./semver.js";
+export const PUBLISHED_TUTTI_PACKAGE_NAME = "@xfey/tutti";
+export const DEFAULT_NODE_ENGINE = ">=24 <26";
+export const DEFAULT_NPM_ENGINE = ">=11 <12";
+function defaultTuttiHome() {
+    return join(homedir(), ".tutti");
+}
+function isWritable(path) {
+    try {
+        accessSync(path, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasSupportedEngine(version, minimumMajor, maximumMajor) {
+    const exact = parseExactSemver(version.startsWith("v") ? version.slice(1) : version);
+    if (exact === null) {
+        return false;
+    }
+    const major = semverMajor(exact);
+    return major !== null && major >= minimumMajor && major < maximumMajor;
+}
+function strictAbsoluteLine(value) {
+    const trimmed = value.trim();
+    return trimmed !== "" && !trimmed.includes("\n") && !trimmed.includes("\r") && isAbsolute(trimmed)
+        ? trimmed
+        : null;
+}
+export function resolveGlobalPackageInstallation(options) {
+    const packageRoot = resolve(options.packageIdentity.root);
+    const currentVersion = parseExactSemver(options.packageIdentity.version);
+    if (options.packageIdentity.name !== PUBLISHED_TUTTI_PACKAGE_NAME ||
+        currentVersion === null ||
+        !isAbsolute(packageRoot)) {
+        return { status: "unavailable", reasonCode: "installation_not_global" };
+    }
+    if (resolve(options.tuttiHome) !== resolve(options.defaultTuttiHome ?? defaultTuttiHome())) {
+        return { status: "unavailable", reasonCode: "custom_home" };
+    }
+    const nodeExecutable = resolve(options.nodeExecutable ?? process.execPath);
+    if (!hasSupportedEngine(options.nodeVersion ?? process.version, 24, 26)) {
+        return { status: "unavailable", reasonCode: "npm_version_unsupported" };
+    }
+    const npmEnvironment = createNpmCommandEnvironment({ env: options.env, nodeExecutable });
+    const candidates = collectNpmExecutableCandidates({
+        env: options.env,
+        nodeExecutable,
+        packageRoot,
+        packageName: PUBLISHED_TUTTI_PACKAGE_NAME,
+    });
+    if (candidates.length === 0) {
+        return { status: "unavailable", reasonCode: "npm_unavailable" };
+    }
+    const runner = options.runner ?? runPackageCommandSync;
+    let observedGlobalRoot = false;
+    for (const npmExecutable of candidates) {
+        const rootResult = runner(createPackageCommandPlan({
+            executable: npmExecutable,
+            args: ["root", "--global"],
+            env: npmEnvironment,
+        }));
+        const globalRoot = rootResult.status === 0 ? strictAbsoluteLine(rootResult.stdout) : null;
+        if (globalRoot === null) {
+            continue;
+        }
+        observedGlobalRoot = true;
+        const expectedPackageRoot = join(globalRoot, ...PUBLISHED_TUTTI_PACKAGE_NAME.split("/"));
+        if (!existsSync(expectedPackageRoot)) {
+            continue;
+        }
+        try {
+            const expectedRealpath = realpathSync(expectedPackageRoot);
+            const packageRealpath = realpathSync(packageRoot);
+            if (lstatSync(expectedPackageRoot).isSymbolicLink()) {
+                if (expectedRealpath === packageRealpath) {
+                    return { status: "unavailable", reasonCode: "installation_not_global" };
+                }
+                continue;
+            }
+            if (expectedRealpath !== packageRealpath) {
+                continue;
+            }
+        }
+        catch {
+            continue;
+        }
+        const versionResult = runner(createPackageCommandPlan({
+            executable: npmExecutable,
+            args: ["--version"],
+            env: npmEnvironment,
+        }));
+        if (versionResult.status !== 0 || !hasSupportedEngine(versionResult.stdout.trim(), 11, 12)) {
+            return { status: "unavailable", reasonCode: "npm_version_unsupported" };
+        }
+        const pathWritable = options.pathWritable ?? isWritable;
+        if (!pathWritable(globalRoot) || !pathWritable(dirname(expectedPackageRoot))) {
+            return { status: "unavailable", reasonCode: "global_prefix_read_only" };
+        }
+        return {
+            status: "eligible",
+            installation: {
+                packageName: PUBLISHED_TUTTI_PACKAGE_NAME,
+                currentVersion,
+                packageRoot,
+                globalRoot,
+                npmExecutable,
+                nodeExecutable,
+                npmEnvironment,
+            },
+        };
+    }
+    return {
+        status: "unavailable",
+        reasonCode: observedGlobalRoot ? "npm_global_root_mismatch" : "npm_unavailable",
+    };
+}
+//# sourceMappingURL=installation.js.map

package/dist/server-shell/package-installation/semver.d.ts

@@ -0,0 +1,9 @@
+declare const exactSemverBrand: unique symbol;
+export type ExactSemver = string & {
+    readonly [exactSemverBrand]: true;
+};
+export declare function parseExactSemver(value: unknown): ExactSemver | null;
+export declare function compareExactSemver(left: ExactSemver, right: ExactSemver): number;
+export declare function semverMajor(version: ExactSemver): number | null;
+export {};
+//# sourceMappingURL=semver.d.ts.map

package/dist/server-shell/package-installation/semver.js

@@ -0,0 +1,84 @@
+const NUMERIC_IDENTIFIER = "(?:0|[1-9]\\d*)";
+const NON_NUMERIC_IDENTIFIER = "(?:\\d*[A-Za-z-][0-9A-Za-z-]*)";
+const PRERELEASE_IDENTIFIER = `(?:${NUMERIC_IDENTIFIER}|${NON_NUMERIC_IDENTIFIER})`;
+const EXACT_SEMVER_PATTERN = new RegExp(`^(${NUMERIC_IDENTIFIER})\\.(${NUMERIC_IDENTIFIER})\\.(${NUMERIC_IDENTIFIER})` +
+    `(?:-(${PRERELEASE_IDENTIFIER}(?:\\.${PRERELEASE_IDENTIFIER})*))?` +
+    "(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$", "u");
+function parse(value) {
+    const match = EXACT_SEMVER_PATTERN.exec(value);
+    if (match === null) {
+        return null;
+    }
+    const major = match[1];
+    const minor = match[2];
+    const patch = match[3];
+    if (major === undefined || minor === undefined || patch === undefined) {
+        return null;
+    }
+    return {
+        raw: value,
+        core: [major, minor, patch],
+        prerelease: match[4] === undefined ? [] : match[4].split("."),
+    };
+}
+export function parseExactSemver(value) {
+    if (typeof value !== "string" || value.trim() !== value) {
+        return null;
+    }
+    return parse(value)?.raw ?? null;
+}
+function compareNumeric(left, right) {
+    if (left.length !== right.length) {
+        return left.length < right.length ? -1 : 1;
+    }
+    return left === right ? 0 : left < right ? -1 : 1;
+}
+export function compareExactSemver(left, right) {
+    const parsedLeft = parse(left);
+    const parsedRight = parse(right);
+    if (parsedLeft === null || parsedRight === null) {
+        throw new Error("Cannot compare invalid SemVer values.");
+    }
+    for (let index = 0; index < parsedLeft.core.length; index += 1) {
+        const comparison = compareNumeric(parsedLeft.core[index] ?? "", parsedRight.core[index] ?? "");
+        if (comparison !== 0) {
+            return comparison;
+        }
+    }
+    if (parsedLeft.prerelease.length === 0 || parsedRight.prerelease.length === 0) {
+        if (parsedLeft.prerelease.length === parsedRight.prerelease.length) {
+            return 0;
+        }
+        return parsedLeft.prerelease.length === 0 ? 1 : -1;
+    }
+    const length = Math.max(parsedLeft.prerelease.length, parsedRight.prerelease.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftIdentifier = parsedLeft.prerelease[index];
+        const rightIdentifier = parsedRight.prerelease[index];
+        if (leftIdentifier === undefined || rightIdentifier === undefined) {
+            return leftIdentifier === undefined ? -1 : 1;
+        }
+        if (leftIdentifier === rightIdentifier) {
+            continue;
+        }
+        const leftNumeric = /^\d+$/u.test(leftIdentifier);
+        const rightNumeric = /^\d+$/u.test(rightIdentifier);
+        if (leftNumeric && rightNumeric) {
+            return compareNumeric(leftIdentifier, rightIdentifier);
+        }
+        if (leftNumeric !== rightNumeric) {
+            return leftNumeric ? -1 : 1;
+        }
+        return leftIdentifier < rightIdentifier ? -1 : 1;
+    }
+    return 0;
+}
+export function semverMajor(version) {
+    const major = parse(version)?.core[0];
+    if (major === undefined || major.length > 6) {
+        return null;
+    }
+    const parsed = Number.parseInt(major, 10);
+    return Number.isSafeInteger(parsed) ? parsed : null;
+}
+//# sourceMappingURL=semver.js.map