carrick 0.3.84 → 0.3.85

package/README.md

@@ -17,6 +17,21 @@ accepts that credential or a `CARRICK_TOKEN` environment override, and signs in
 through the browser itself when a terminal has neither. GitHub CLI credentials
 do not grant Carrick access.
 
+An installed `carrick` does not move on its own, and a scan on an old build can
+fail on a defect that is already fixed. So every command reads a cached answer
+to "is there a newer one", refreshes it in the background, and prints a line
+naming the exact update command for the way this copy was installed. It never
+blocks on the network, and `CARRICK_NO_UPDATE_CHECK=1` turns it off for a
+reproducible run. The one thing it installs is an older **global** `carrick`
+when you run through `npx`: that install answers your agent's hooks and every
+new shell, so it is brought level with the version you just ran, using the
+package manager that owns it and nothing that overrides your own npm
+configuration. A machine with no global is never installed onto without a yes —
+`carrick init` asks, and `carrick init --install-global` is the answer for a
+script. In CI it warns
+and continues, so a workflow decides its own version — and
+`carrick-tools/carrick@v1` in a workflow already moves to each release.
+
 `init` prints one line per thing it did — `◇` done, `▲` a warning with what to
 do about it, `■` something it could not do and why — and ends on the sentence
 to paste to your agent. Everything else, including the editor extension, how

package/bin/carrick.mjs

@@ -82,6 +82,82 @@ async function refreshNoticeLine() {
 
 await refreshNoticeLine();
 
+/**
+ * "The carrick you are running is not the carrick that is published."
+ *
+ * At the start of the command, which is the only moment it is useful: told
+ * halfway through a scan, a person has already paid for the scan. An installed
+ * `carrick` never moves on its own, so without this the only upgrade path is a
+ * human remembering — which is exactly the path that failed a pilot customer,
+ * who ran a scan on a build three releases old and hit a defect already fixed.
+ *
+ * On a laptop this reads one small cache file and starts a detached child to
+ * refresh it, so it adds no measurable time; in CI it is one bounded fetch, and
+ * only in front of a scan. Either way it prints and continues: nothing here
+ * installs anything or changes which binary runs. `src/update.ts` has the
+ * reasoning, `docs/reference/update-check.md` the design.
+ *
+ * Silent for `lsp` and `hook post-edit`: those run on a protocol stream and on
+ * every keystroke-ish edit. `hook session-start` prints its own version of this
+ * on stdout, where the agent reading the session actually sees it.
+ */
+async function noticeUpdate() {
+  try {
+    const update = await import("../dist/update.js");
+    if (command === "lsp" || command === "hook") {
+      // Still worth refreshing the cache: hooks are the most frequent
+      // invocation on a developer machine, so they are what keeps the answer
+      // the other commands print from going stale.
+      if (!update.inCi(process.env)) update.scheduleUpdateCheck(process.env);
+      return;
+    }
+    const line = update.inCi(process.env)
+      ? await update.ciUpdateNotice(argv, process.env)
+      : update.updateNoticeFromCache(process.env);
+    // stderr, always: a `--json` answer and `lsp --stdio` own stdout.
+    if (line) process.stderr.write(`${line}\n`);
+  } catch {
+    // A version check is never a reason for a command not to run.
+  }
+}
+
+await noticeUpdate();
+
+/**
+ * Leave no older `carrick` on PATH behind this run (carrick#1372).
+ *
+ * A run through `npx carrick@latest` is current by construction and changes
+ * nothing on the machine, so a global install from an earlier release keeps
+ * answering every hook, every script and every new shell afterwards. Where one
+ * exists, this brings it level, through the package manager that owns it, and
+ * then resolves `carrick` again to check that it took. It installs nothing on a
+ * machine that has no global: that offer is `carrick init`'s, where there is
+ * somebody to ask.
+ *
+ * `src/global-install.ts` has the reasoning. Silent unless it does something,
+ * and never a reason a command does not run.
+ */
+async function keepGlobalCurrent() {
+  try {
+    const sync = await import("../dist/global-install.js");
+    if (!sync.syncsOnThisRun(command, process.env)) return;
+    // stderr throughout, so a `--json` answer on stdout stays parseable.
+    const outcome = sync.syncGlobalInstall({
+      say: (line) => process.stderr.write(`carrick: ${line}\n`),
+    });
+    // A run that is ending on an older carrick than it is says so at the END of
+    // it. In front of `carrick index` this is the first line of a log that then
+    // runs for minutes, and what it names is the state the machine is left in.
+    if (outcome.warning) {
+      process.once("exit", () => process.stderr.write(`carrick: ${outcome.warning}\n`));
+    }
+  } catch {
+    // An upgrade that could not even be attempted is not a failed command.
+  }
+}
+
+await keepGlobalCurrent();
+
 /**
  * Run a build of the index and render it (carrick#1315).
  *
@@ -127,6 +203,7 @@ async function renderNative(args) {
 /** Run the scanner binary, streaming its output and answering with its code. */
 async function runNative(args) {
   const { resolveNativeBinary, nativeEnv, overrideLine } = await import("../dist/native.js");
+  const { relaySignals } = await import("../dist/scan.js");
   const lookup = resolveNativeBinary();
   if (!lookup.binary) {
     process.stderr.write(`carrick: ${lookup.problem}\n`);
@@ -139,11 +216,17 @@ async function runNative(args) {
     stdio: "inherit",
     env: nativeEnv(),
   });
+  // The streams are inherited here, so a scan this process walks out on keeps
+  // writing to the terminal — but it is still a scan nobody told to stop, and
+  // a `kill` on this pid reaches this process alone (carrick#1391).
+  const stopRelaying = relaySignals(child);
   child.on("error", (error) => {
+    stopRelaying();
     process.stderr.write(`carrick: could not run ${lookup.binary}: ${error.message}\n`);
     process.exit(1);
   });
   child.on("exit", (code, signal) => {
+    stopRelaying();
     // A signalled child is reported the way a shell reports it, so a Ctrl-C
     // through this shim looks like a Ctrl-C of the scanner.
     if (signal) {
@@ -212,6 +295,12 @@ function extraHelp() {
     "                                 carrick.json",
     "    --version                    the version of this package",
     "",
+    "ENVIRONMENT:",
+    "    CARRICK_NO_UPDATE_CHECK      set it to stop carrick checking whether a",
+    "                                 newer version is published. The check reads",
+    "                                 one cached file and refreshes it in the",
+    "                                 background; it never installs anything.",
+    "",
     "`carrick init [--project SLUG]` sets this folder up; `carrick init --help`",
     "prints its own arguments. `carrick doctor` re-checks that setup and exits",
     "non-zero on anything it finds. `carrick remove` undoes what init wrote on",

package/dist/auth/credentials.d.ts

@@ -32,6 +32,15 @@ export type Credential = {
      */
     scope?: string;
 };
+/**
+ * The per-user directory Carrick keeps its own state in.
+ *
+ * Exported because more than the credential lives here: the update check's
+ * cache (`src/update.ts`) is written beside it, and two spellings of one
+ * directory would put a test's temporary state somewhere a later read cannot
+ * find it.
+ */
+export declare function configDir(env?: NodeJS.ProcessEnv): string;
 export declare function credentialPath(env?: NodeJS.ProcessEnv): string;
 export declare function readCredential(env?: NodeJS.ProcessEnv): Credential | null;
 export declare function saveCredential(token: string, workspace: string | null, env?: NodeJS.ProcessEnv, scope?: string): void;

package/dist/auth/credentials.js

@@ -17,13 +17,24 @@ export const APP_BASE = "https://app.carrick.tools";
  * `docs/internal/reference/laptop-scan-seam.md` §1.1, §8.1, §9).
  */
 export const SCOPE = "cli";
-export function credentialPath(env = process.env) {
+/**
+ * The per-user directory Carrick keeps its own state in.
+ *
+ * Exported because more than the credential lives here: the update check's
+ * cache (`src/update.ts`) is written beside it, and two spellings of one
+ * directory would put a test's temporary state somewhere a later read cannot
+ * find it.
+ */
+export function configDir(env = process.env) {
     const base = env["XDG_CONFIG_HOME"] ||
         (process.platform === "win32" ? env["APPDATA"] : undefined) ||
         path.join(env["HOME"] || os.homedir(), ".config");
     if (!path.isAbsolute(base))
         throw new Error("Carrick's configuration directory must be an absolute path.");
-    return path.join(base, "carrick", "credentials.json");
+    return path.join(base, "carrick");
+}
+export function credentialPath(env = process.env) {
+    return path.join(configDir(env), "credentials.json");
 }
 export function readCredential(env = process.env) {
     if (env["CARRICK_TOKEN"] !== undefined) {

package/dist/auth/credentials.js.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/auth/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,QAAQ,GAAG,2BAA2B,CAAC;AACpD,MAAM,CAAC,MAAM,QAAQ,GAAG,2BAA2B,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,CAAC;AAqB3B,MAAM,UAAU,cAAc,CAAC,MAAyB,OAAO,CAAC,GAAG;IACjE,MAAM,IAAI,GAAG,GAAG,CAAC,iBAAiB,CAAC;QACjC,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACpD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IAC3G,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAyB,OAAO,CAAC,GAAG;IACjE,IAAI,GAAG,CAAC,eAAe,CAAC,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,mGAAmG,CAAC,CAAC;QACrJ,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAC9E,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,EAAU,CAAC;IACf,IAAI,CAAC;QAAC,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,GAAG,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAAC,CAAC;IAChF,OAAO,KAAK,EAAE,CAAC;QACb,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,EAAE,CAAC;QACrG,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,EAAE,CAAC;QACnE,MAAM,UAAU,GAAG,KAAmB,CAAC;QACvC,IAAI,UAAU,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ;YACxE,CAAC,UAAU,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;YAChD,CAAC,CAAC,UAAU,CAAC,cAAc,KAAK,IAAI,IAAI,OAAO,UAAU,CAAC,cAAc,KAAK,QAAQ,CAAC;YACtF,CAAC,CAAC,UAAU,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ,CAAC;YACzE,OAAO,UAAU,CAAC,WAAW,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,EAAE,CAAC;QAClE,OAAO,UAAU,CAAC;IACpB,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IAAC,CAAC;YAC1F,CAAC;QAAC,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,SAAwB,EAAE,MAAyB,OAAO,CAAC,GAAG,EAAE,QAAgB,KAAK;IACjI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACvG,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IAC3H,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACjE,MAAM,SAAS,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;IAClE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;QACzD,MAAM,UAAU,GAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,CAAC;QACtI,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACnG,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;YAAS,CAAC;QAAC,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAAC,CAAC;AACvE,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACnE,IAAI,CAAC;QAAC,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;IACxD,OAAO,KAAK,EAAE,CAAC;QACb,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;AACH,CAAC"}
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/auth/credentials.ts"],"names":[],"mappings":"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"}

package/dist/auth/read.d.ts

@@ -6,13 +6,13 @@ declare const response: z.ZodObject<{
         billing_tier: z.ZodEnum<["free", "cross_repo", "paid"]>;
         installed: z.ZodBoolean;
     }, "strip", z.ZodTypeAny, {
+        installed: boolean;
         slug: string;
         billing_tier: "free" | "cross_repo" | "paid";
-        installed: boolean;
     }, {
+        installed: boolean;
         slug: string;
         billing_tier: "free" | "cross_repo" | "paid";
-        installed: boolean;
     }>;
     allowance_sentence: z.ZodNullable<z.ZodString>;
     repos: z.ZodArray<z.ZodDiscriminatedUnion<"connected", [z.ZodObject<{
@@ -81,9 +81,9 @@ declare const response: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     schema: "carrick.resolve-repos/0";
     workspace: {
+        installed: boolean;
         slug: string;
         billing_tier: "free" | "cross_repo" | "paid";
-        installed: boolean;
     };
     repos: ({
         connected: false;
@@ -108,9 +108,9 @@ declare const response: z.ZodObject<{
 }, {
     schema: "carrick.resolve-repos/0";
     workspace: {
+        installed: boolean;
         slug: string;
         billing_tier: "free" | "cross_repo" | "paid";
-        installed: boolean;
     };
     repos: ({
         connected: false;

package/dist/global-install.d.ts

@@ -0,0 +1,183 @@
+import type { InstallShape } from "./update.ts";
+/** The names a `carrick` on PATH goes by, most specific first. */
+export declare function carrickNames(platform?: string): string[];
+/** A `carrick` that is installed on this machine and is not the one running. */
+export type GlobalCarrick = {
+    /** What the PATH lookup answers with. */
+    binary: string;
+    /** Where that leads after symlinks: an npm global bin entry is a link. */
+    real: string;
+    /** Its version, or null when neither its manifest nor the binary said. */
+    version: string | null;
+};
+export type FindOptions = {
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+    exists?: (target: string) => boolean;
+    real?: (target: string) => string;
+};
+/**
+ * The `carrick` a PATH lookup finds, skipping what only exists during a run.
+ *
+ * `which carrick` cannot answer this question. npm puts the exec tree's own
+ * `node_modules/.bin` at the front of PATH for the child it runs, so inside
+ * `npx carrick init` a `which` says `carrick` is on PATH on a machine where it
+ * is not — and `carrick init` then wrote a bare `carrick hook post-edit` into a
+ * settings file, naming a command that stopped existing when npx exited.
+ *
+ * File reads only: no `which`, no subprocess, so it costs nothing on a command
+ * that runs on every edit.
+ */
+export declare function findCarrick(options?: FindOptions): GlobalCarrick | null;
+export type VersionOptions = {
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+    read?: (target: string) => string;
+    run?: (binary: string) => string | null;
+};
+/**
+ * The version of the install a binary belongs to.
+ *
+ * Read off the manifest above it wherever the path says — an npm global bin
+ * entry links straight into `lib/node_modules/carrick/bin`, so the answer is a
+ * file read. A shim that is a real file (volta, a `.cmd` on Windows) leads
+ * nowhere, and only then is the binary asked, with the version check turned off
+ * in the child so an older build does not fork a registry fetch from our probe.
+ */
+export declare function installedVersion(found: GlobalCarrick, options?: VersionOptions): string | null;
+/**
+ * The command that replaces a global install, for the manager that owns it.
+ *
+ * Null for the two shapes that are not a global: an npx cache directory, which
+ * is thrown away and re-resolved, and a project dependency, which belongs to
+ * whichever repository pins it and is not this run's to change. Both are
+ * reported rather than acted on.
+ *
+ * The version is pinned rather than `@latest` on purpose. The run knows which
+ * version it is, `@latest` is a second question for the registry, and a pinned
+ * spec is what makes the verification below a comparison rather than a guess.
+ */
+export declare function globalCommand(kind: InstallShape["kind"], version: string): string[] | null;
+/**
+ * The command for a machine that has no global carrick at all.
+ *
+ * The running copy's own shape names the manager: somebody running through
+ * `npx` has npm, and a project dependency says nothing about what its owner
+ * would want globally, so both answer npm.
+ */
+export declare function firstGlobalCommand(kind: InstallShape["kind"], version: string): string[];
+export type InstallResult = {
+    ok: boolean;
+    reason: string | null;
+};
+/** What this file needs from the machine, so every case above can be a test. */
+export type GlobalMachine = {
+    /** The global carrick on PATH with its version, or null where there is none. */
+    find: () => GlobalCarrick | null;
+    /** The shape an installed path is in, for the command that replaces it. */
+    shape: (found: GlobalCarrick) => InstallShape;
+    /** Run an install. `ok` is the manager's own verdict, nothing more. */
+    install: (argv: string[]) => InstallResult;
+};
+/** How long an install is given before it is a refusal with a reason. */
+export declare const INSTALL_TIMEOUT_MS = 180000;
+/** The last thing a failed install said, for a reader who has to act on it. */
+export declare function failureReason(result: {
+    status: number | null;
+    stderr: string | null;
+    stdout: string | null;
+    error?: Error;
+}): string;
+export declare function realMachine(env?: NodeJS.ProcessEnv): GlobalMachine;
+/**
+ * What a run did about the global install, for the tests and for the log.
+ *
+ * `warning` is the sentence for a run that is ENDING on an older carrick than
+ * it is, and it is returned rather than said because that is where it belongs:
+ * a line printed in front of `carrick index` is the first line of a
+ * multi-minute log, and what it names is the state the machine is left in. The
+ * caller prints it last. Everything else — what is being upgraded, and that it
+ * took — is progress, and is said as it happens.
+ */
+export type SyncOutcome = {
+    kind: "skipped";
+    why: string;
+    warning: null;
+} | {
+    kind: "current";
+    version: string;
+    warning: null;
+} | {
+    kind: "upgraded";
+    from: string;
+    to: string;
+    warning: null;
+} | {
+    kind: "refused";
+    from: string;
+    to: string;
+    reason: string;
+    command: string;
+    warning: string;
+} | {
+    kind: "stale";
+    path: string | null;
+    version: string | null;
+    command: string | null;
+    warning: string;
+};
+export type SyncOptions = {
+    /** The version this run is. */
+    running?: string | null;
+    /** Progress, as it happens: what is being upgraded, and that it took. */
+    say: (line: string) => void;
+    machine?: GlobalMachine;
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * Bring an older global carrick level with this run, and say so.
+ *
+ * The ruling this implements: somebody who installed carrick globally has
+ * already chosen to have it on this machine, so bringing that choice up to date
+ * is inside what they agreed to and is not asked about. What is NOT inside it
+ * is creating an install they never asked for, forcing one past their machine's
+ * policy, or leaving them on an older binary without knowing.
+ */
+export declare function syncGlobalInstall(options: SyncOptions): SyncOutcome;
+/**
+ * Whether this invocation keeps the global install level.
+ *
+ * Only a run through npx. Every other shape IS the install a person would be
+ * upgrading: a global run of `carrick index` is already the version on PATH,
+ * and a project dependency belongs to the repository that pins it. npx is the
+ * one that leaves a second, older carrick behind it, and it is also the one the
+ * quickstart and the agents use.
+ *
+ * Never in CI: a build machine is thrown away, nothing on it is on PATH for a
+ * next run, and what runs there is the workflow's decision.
+ */
+export declare function syncsOnThisRun(command: string | undefined, env?: NodeJS.ProcessEnv, root?: string): boolean;
+export type OfferOutcome = "present" | "installed" | "declined" | "failed";
+export type OfferOptions = {
+    running?: string | null;
+    /** `--yes`, which consents to the scaffold and not to an install. */
+    assumeYes: boolean;
+    /** `--install-global`, which is the consent. */
+    install: boolean;
+    confirm: (question: string) => Promise<boolean>;
+    say: (line: string) => void;
+    machine?: GlobalMachine;
+    env?: NodeJS.ProcessEnv;
+    root?: string;
+};
+/**
+ * Offer a global install to a machine that has none, and never take one.
+ *
+ * The ruling: `--yes` answers for the workspace, so it prints the command and
+ * installs nothing; a terminal is asked; `--install-global` is the consent a
+ * script gives. What turns on the answer is the hook commands written
+ * immediately after this — with a global, they are the bare `carrick`, which
+ * survives the end of this npx run; without one, they name this install, which
+ * does not.
+ */
+export declare function offerGlobalInstall(options: OfferOptions): Promise<OfferOutcome>;