@skrr-ai/cli 0.1.119 → 0.1.120

package/dist/lib/cli-installation-diagnostics.js

@@ -0,0 +1,254 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectCliInstallations = inspectCliInstallations;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const update_check_1 = require("./update-check");
+const CLI_PACKAGE_NAME = '@skrr-ai/cli';
+/**
+ * Inspect executable paths without ever starting another CLI.
+ *
+ * `doctor` is often invoked because PATH is already suspect. Running each
+ * discovered `skrr --version` would make the report execute an arbitrary
+ * shadowing binary. This reader follows symlinks and reads package metadata
+ * only; a candidate that cannot prove it belongs to this CLI is reported as
+ * unrecognised rather than trusted.
+ */
+function inspectCliInstallations(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const activeRoot = options.activeRoot ? canonicalPath(options.activeRoot) : null;
+    const activeEntry = options.activeEntry ?? process.argv[1] ?? null;
+    const locations = executableLocations({
+        activeEntry,
+        pathValue: env.PATH ?? '',
+        platform,
+        wellKnownPaths: options.wellKnownPaths ?? defaultWellKnownPaths(env, platform),
+    });
+    const candidates = new Map();
+    const unrecognisedExecutables = [];
+    // A source checkout may be invoked through node, Jest, or a development
+    // wrapper rather than an executable named `skrr`. Its configured root is the
+    // reliable active fact, so inspect it independently from PATH discovery.
+    if (activeRoot) {
+        const activePackage = readCliPackage(activeRoot, true);
+        if (activePackage) {
+            addCandidate(candidates, activePackage, {
+                path: activeEntry ?? path.join(activeRoot, 'bin', 'run.js'),
+                realPath: activeEntry ? realPath(activeEntry) : null,
+                source: 'active',
+                pathPrecedence: null,
+            }, env);
+        }
+    }
+    for (const location of locations) {
+        const packageInfo = readCliPackage(location.path);
+        if (!packageInfo) {
+            if (location.source !== 'active' && isExecutable(location.path, platform)) {
+                unrecognisedExecutables.push({
+                    path: location.path,
+                    realPath: realPath(location.path),
+                    source: location.source,
+                    pathPrecedence: location.pathPrecedence,
+                });
+            }
+            continue;
+        }
+        addCandidate(candidates, packageInfo, location, env);
+    }
+    const rows = [...candidates.values()]
+        .map((candidate) => ({
+        paths: [...candidate.paths],
+        realPath: candidate.realPath,
+        packageRoot: candidate.packageRoot,
+        version: candidate.version,
+        owner: candidate.owner,
+        updateCommand: candidate.updateCommand,
+        sources: sourceOrder([...candidate.sources]),
+        pathPrecedence: candidate.pathPrecedence,
+        active: candidate.active,
+    }))
+        .sort(compareCandidates);
+    const active = rows.find((candidate) => candidate.active) ?? null;
+    const pathVersions = [...new Set(rows
+            .filter((candidate) => candidate.pathPrecedence !== null)
+            .sort((a, b) => (a.pathPrecedence ?? Number.MAX_SAFE_INTEGER) - (b.pathPrecedence ?? Number.MAX_SAFE_INTEGER))
+            .map((candidate) => candidate.version))];
+    const hasVersionDrift = pathVersions.length > 1;
+    return {
+        active,
+        candidates: rows,
+        unrecognisedExecutables,
+        pathVersions,
+        hasVersionDrift,
+        remedy: hasVersionDrift ? versionDriftRemedy(rows, active) : null,
+    };
+}
+function addCandidate(candidates, packageInfo, location, env) {
+    const key = packageInfo.packageRoot;
+    const existing = candidates.get(key);
+    const install = existing
+        ? null
+        : (0, update_check_1.classifyCliInstall)(env, [process.execPath, location.path], null, false);
+    const candidate = existing ?? {
+        paths: new Set(),
+        realPath: location.realPath,
+        packageRoot: packageInfo.packageRoot,
+        version: packageInfo.version,
+        // Read-only classification: doctor never creates a write-probe just to
+        // identify an installation.
+        owner: install.kind,
+        updateCommand: (0, update_check_1.cliUpdateCommand)(install.kind, install.npmPrefix),
+        sources: new Set(),
+        pathPrecedence: location.pathPrecedence,
+        active: false,
+    };
+    if (!existing)
+        candidates.set(key, candidate);
+    candidate.paths.add(location.path);
+    if (!candidate.realPath && location.realPath)
+        candidate.realPath = location.realPath;
+    candidate.sources.add(location.source);
+    candidate.active ||= location.source === 'active';
+    if (location.pathPrecedence !== null &&
+        (candidate.pathPrecedence === null || location.pathPrecedence < candidate.pathPrecedence)) {
+        candidate.pathPrecedence = location.pathPrecedence;
+    }
+}
+function executableLocations(options) {
+    const names = options.platform === 'win32' ? ['skrr.exe', 'skrr.cmd'] : ['skrr'];
+    const locations = [];
+    if (options.activeEntry) {
+        locations.push({ path: options.activeEntry, realPath: realPath(options.activeEntry), source: 'active', pathPrecedence: null });
+    }
+    const seenPath = new Set();
+    for (const [index, directory] of options.pathValue.split(path.delimiter).entries()) {
+        if (!directory)
+            continue;
+        for (const name of names) {
+            const candidate = path.resolve(directory, name);
+            if (!isExecutable(candidate, options.platform) || seenPath.has(candidate))
+                continue;
+            seenPath.add(candidate);
+            locations.push({ path: candidate, realPath: realPath(candidate), source: 'path', pathPrecedence: index });
+        }
+    }
+    for (const candidate of options.wellKnownPaths) {
+        const resolved = path.resolve(candidate);
+        if (!isExecutable(resolved, options.platform) || seenPath.has(resolved))
+            continue;
+        seenPath.add(resolved);
+        locations.push({ path: resolved, realPath: realPath(resolved), source: 'well_known', pathPrecedence: null });
+    }
+    return locations;
+}
+function defaultWellKnownPaths(env, platform) {
+    if (platform === 'win32')
+        return [];
+    const home = env.HOME?.trim();
+    return [
+        ...(home ? [path.join(home, '.local', 'bin', 'skrr')] : []),
+        '/opt/homebrew/bin/skrr',
+        '/usr/local/bin/skrr',
+    ];
+}
+function readCliPackage(entry, allowPackageRoot = false) {
+    let current = canonicalPath(entry);
+    try {
+        if (!allowPackageRoot || !fs.statSync(current).isDirectory())
+            current = path.dirname(current);
+    }
+    catch {
+        current = path.dirname(current);
+    }
+    while (true) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(current, 'package.json'), 'utf8'));
+            if (pkg.name === CLI_PACKAGE_NAME && typeof pkg.version === 'string' && pkg.version.trim()) {
+                return { packageRoot: canonicalPath(current), version: pkg.version };
+            }
+        }
+        catch {
+            // A wrapper that does not prove its package must not be treated as skrr.
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function realPath(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        return null;
+    }
+}
+function canonicalPath(value) {
+    return realPath(value) ?? path.resolve(value);
+}
+function isExecutable(candidate, platform) {
+    try {
+        fs.accessSync(candidate, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sourceOrder(sources) {
+    const order = ['active', 'path', 'well_known'];
+    return order.filter((source) => sources.includes(source));
+}
+function compareCandidates(a, b) {
+    if (a.active !== b.active)
+        return a.active ? -1 : 1;
+    const aPrecedence = a.pathPrecedence ?? Number.MAX_SAFE_INTEGER;
+    const bPrecedence = b.pathPrecedence ?? Number.MAX_SAFE_INTEGER;
+    return aPrecedence - bPrecedence || a.packageRoot.localeCompare(b.packageRoot);
+}
+function versionDriftRemedy(candidates, active) {
+    const pathCandidates = candidates
+        .filter((candidate) => candidate.pathPrecedence !== null)
+        .sort((a, b) => (a.pathPrecedence ?? Number.MAX_SAFE_INTEGER) - (b.pathPrecedence ?? Number.MAX_SAFE_INTEGER));
+    const selected = pathCandidates[0] ?? active;
+    if (!selected)
+        return 'Inspect the skrr entries on PATH, update the intended installation, then re-run `skrr doctor`.';
+    return (`PATH selects ${selected.paths[0]} (v${selected.version}). Update the installation you intend to keep with ` +
+        `\`${selected.updateCommand}\`, then remove or reorder the other skrr entries using their owning package manager. ` +
+        'No PATH changes were made. Verify with `skrr update --component cli --check` and `skrr doctor`.');
+}

package/dist/lib/command-hygiene.d.ts

@@ -28,8 +28,52 @@ export type CommandHygieneReport = {
     };
     /** The verb rules the findings below are measured against (P8). */
     namingGrammar: readonly string[];
+    /** A reviewable, report-only inventory for high-side-effect CLI flows. */
+    execution: ExecutionContractReport;
     issues: CommandHygieneIssue[];
 };
+type ExecutionRequirement = 'operationIdentifier' | 'receipt' | 'recovery' | 'machineState' | 'idempotency';
+type ExecutionRequirementStatus = 'provided' | 'missing' | 'not_applicable';
+type ExecutionRequirementAssessment = {
+    status: ExecutionRequirementStatus;
+    /** A source-level fact, or the bounded change needed to close a gap. */
+    note: string;
+};
+type HighSideEffectCommand = {
+    command: string;
+    effect: 'remote_execution' | 'machine_lifecycle' | 'durable_execution' | 'automation_control' | 'release_publication';
+    owner: string;
+    priority: 'P0' | 'P1' | 'P2';
+    requirements: Readonly<Record<ExecutionRequirement, ExecutionRequirementAssessment>>;
+};
+type HumanOnlyExemption = {
+    command: string;
+    effect: 'credential_issuance';
+    /** Why a receipt would be unsafe or misleading for this command. */
+    reason: string;
+    /** The policy/document a reviewer must re-check before changing the exemption. */
+    reviewedEvidence: string;
+};
+export type ExecutionContractReport = {
+    /** Commands in the current source/manifest that matched the guarded vocabulary. */
+    candidates: number;
+    classified: number;
+    humanOnlyExemptions: number;
+    missingOperationIdentifiers: number;
+    missingReceipts: number;
+    missingRecoveryGuidance: number;
+    missingMachineStateOutputs: number;
+    missingIdempotencyBehavior: number;
+    contracts: Array<{
+        command: string;
+        effect: HighSideEffectCommand['effect'];
+        owner: string;
+        priority: HighSideEffectCommand['priority'];
+        requirements: HighSideEffectCommand['requirements'];
+    }>;
+    exemptions: HumanOnlyExemption[];
+    unclassified: string[];
+};
 export declare function auditCommands({ rootDir, manifest, }: {
     rootDir: string;
     /**
@@ -50,3 +94,4 @@ export declare const ENFORCED_HYGIENE_DOMAINS: readonly ["tasks", "spaces", "pro
  * report sees the rule and not only the findings it produced.
  */
 export declare const NAMING_GRAMMAR: readonly ["Verbs: list, show, create, update, delete, archive, unarchive, move. A reversible state flip is its own verb, never a flag on its inverse.", "Scope: a list verb takes its parent scope as an optional filter flag; a verb that cannot work without a scope says so in its description.", "Output: every command in tasks, spaces and projects takes --json and has a description (audit errors)."];
+export {};