@cleocode/core 2026.9.26 → 2026.10.2

package/dist/resources/run-class.d.ts

@@ -0,0 +1,111 @@
+/**
+ * What a command is, for `cleo run` and the provider hook (T12983): the
+ * governor class it needs, whether it is heavy at all, and whether it may be
+ * paused. Pure and dependency-free (type-only imports, plus `node:fs` for the
+ * workspace-root check), so a hook that runs on every Bash call can import it
+ * cheaply.
+ *
+ * Only the COMMAND WORD counts: the tool (`argv[0]` after `env`/`nice`/
+ * `time` and `NAME=value` prefixes), or for a package manager its script
+ * (`pnpm build`, `npm run test:unit`) or exec'd tool (`npx vitest`,
+ * `pnpm exec tsc`, `pnpm dlx`). A tool name inside an argument never counts
+ * (`git commit -m "fix vitest"`, `grep -rn tsc .`, `cd packages/next`).
+ * `--version`/`--help` and watch/dev/serve modes are never heavy: a watcher
+ * would hold a slot forever.
+ *
+ * @module resources/run-class
+ * @task T12979
+ * @epic T12978
+ */
+import type { ResourceClass } from '@cleocode/contracts';
+import type { CanonicalTool } from '../tasks/tool-resolver.js';
+/** Short class names accepted by `cleo run --class`. */
+export declare const RUN_CLASS_ALIASES: Readonly<Record<string, ResourceClass>>;
+/** What an argv runs: its tool, or a package manager's script / exec target. */
+export interface CommandTarget {
+    /** The program that runs the work (`vitest`, `tsc`, `cargo`, or the pm). */
+    readonly tool: string;
+    /** The package-manager verb or script (`build`, `test:unit`, `install`), else null. */
+    readonly script: string | null;
+    /** The package manager, when the command went through one. */
+    readonly pm: string | null;
+    /** Arguments after the tool or script. */
+    readonly rest: readonly string[];
+    /** A workspace-scoping flag was given (`--filter`, `-C`, …). */
+    readonly scoped: boolean;
+    /** A run-everywhere flag was given (`-r`, `--workspaces`, `yarn workspaces foreach`). */
+    readonly recursive: boolean;
+}
+/**
+ * Resolve the command word of `argv`.
+ *
+ * @example
+ * ```ts
+ * commandTarget(['pnpm', '--filter', 'x', 'run', 'test:unit']).script; // 'test:unit'
+ * commandTarget(['npx', '-y', 'vitest', 'run']).tool;                  // 'vitest'
+ * commandTarget(['env', 'CI=1', 'tsc', '-b']).tool;                    // 'tsc'
+ * ```
+ */
+export declare function commandTarget(argv: readonly string[]): CommandTarget;
+/**
+ * Whether a script or task name serves or watches: `dev`, `start` or
+ * `preview` as its first segment (`dev`, `dev:web`), or `watch`/`serve` in
+ * any segment (`test:watch`, `docs:serve`). `build:dev`, `build:preview` and
+ * `test:dev` are one-shot runs.
+ */
+export declare function isWatchName(name: string): boolean;
+/**
+ * Whether `argv` is a heavy command: a test runner, compiler, bundler or
+ * linter as the command word, or a package-manager test/build/typecheck/lint/
+ * install script, or `cargo`/`go` build or test. Never `--version`/`--help`,
+ * never a watch/dev/serve mode.
+ *
+ * @example
+ * ```ts
+ * looksHeavy(['npx', 'vitest', 'run']);              // true
+ * looksHeavy(['git', 'commit', '-m', 'fix vitest']);  // false
+ * looksHeavy(['pnpm', 'dev']);                       // false
+ * looksHeavy(['tsc', '--version']);                  // false
+ * ```
+ */
+export declare function looksHeavy(argv: readonly string[]): boolean;
+/**
+ * Whether `argv` is a watcher or server (`pnpm dev`, `turbo run dev`,
+ * `vitest --ui`, `vite preview`): it never exits, so `cleo run` refuses it
+ * rather than let it hold a slot forever (an explicit `--class` overrides).
+ * Never `--version`/`--help`, a flag value (`pytest -k dev`, `vitest -t serve`)
+ * or a `-w` that means something else (`jest -w 2`, `prettier -w .`).
+ */
+export declare function isWatchCommand(argv: readonly string[]): boolean;
+/**
+ * The governor class for a command.
+ *
+ * An explicit `--class` wins (aliases above). Otherwise: a test runner, a
+ * `test` script, `npm t`, `bun test`, `cargo|go test`, or turbo/nx running
+ * only test tasks is `test-run`; a build that spans the workspace (`-r`,
+ * `--workspaces`, `yarn workspaces foreach`, an unscoped build at a workspace
+ * root, or any non-test turbo / `nx run-many|affected` run, `build test`
+ * included) is `full-build`; anything else is `scoped-build`.
+ *
+ * @param explicit - the `--class` value, if given.
+ * @param argv - the command.
+ * @param cwd - where it runs (for the workspace-root check).
+ * @throws {Error} when `explicit` is not a known class or alias.
+ */
+export declare function resolveRunClass(explicit: string | undefined, argv: readonly string[], cwd: string): ResourceClass;
+/** The `heavyToolEnv` canonical tool a run class sizes its env from. */
+export declare function canonicalForClass(cls: ResourceClass): CanonicalTool;
+/**
+ * Whether a job may be SIGSTOPped under pressure. Installs, db-heavy work and
+ * cargo (which holds the registry cache and target-dir locks) hold shared
+ * locks the oldest job may need, so pausing them can stall the one job that
+ * is meant to keep the machine moving.
+ *
+ * CLEO's own commands are never paused either (#1777 R7-1): `cleo verify
+ * --evidence tool:test` holds the tool-semaphore and tool-cache locks and
+ * spawns its heavy tool DETACHED, out of the paused group. A pause would
+ * freeze only the lock holder while the test keeps running; its locks stop
+ * refreshing, go stale and are taken, and it crashes on resume.
+ */
+export declare function isPausable(cls: ResourceClass, argv: readonly string[]): boolean;
+//# sourceMappingURL=run-class.d.ts.map

package/dist/resources/run-class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-class.d.ts","sourceRoot":"","sources":["../../src/resources/run-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAWpE,CAAC;AA8LH,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,yFAAyF;IACzF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CA4GpE;AA2CD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGjD;AAkHD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAY3D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE/D;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,GACV,aAAa,CA+Bf;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,CAEnE;AA4BD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAO/E"}