@danypops/vehicle-core 0.18.2 → 0.18.4

package/dist/cli-safety/assert-no-leading-flag-char.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Guards against the argv-injection class behind a well-known family of CLI-wrapper CVEs
+ * (simple-git's own history includes several): a caller-influenced string that starts with `-`
+ * can be parsed by the target CLI as a *flag* (`--upload-pack`, `--exec`, `--template`, `-c`
+ * config override) instead of the literal ref/path/pattern value the caller intended. Any Vehicle
+ * operation that hands a caller-supplied string to a shelled-out CLI's argv should run it through
+ * this check first, at the exact position it reaches that argv.
+ *
+ * This is a hard rejection with no exceptions -- it has no opinion about *why* a value starting
+ * with `-` might be needed and does not attempt to allow-list specific flags. A caller whose CLI
+ * genuinely accepts caller-influenced flag-shaped arguments needs a purpose-built allow-list of
+ * its own; this primitive only ever covers the common case of a value that should always be a
+ * literal.
+ */
+export declare class UnsafeCliArgument extends Error {
+    readonly value: string;
+    readonly fieldName?: string | undefined;
+    constructor(value: string, fieldName?: string | undefined);
+}
+/** Throws UnsafeCliArgument if `value` starts with `-`. `fieldName`, when given, names the field in the thrown error's own message for a caller with several distinct argv positions to check. */
+export declare function assertNoLeadingFlagChar(value: string, fieldName?: string): void;

package/dist/cli-safety/assert-no-leading-flag-char.js

@@ -0,0 +1,31 @@
+/**
+ * Guards against the argv-injection class behind a well-known family of CLI-wrapper CVEs
+ * (simple-git's own history includes several): a caller-influenced string that starts with `-`
+ * can be parsed by the target CLI as a *flag* (`--upload-pack`, `--exec`, `--template`, `-c`
+ * config override) instead of the literal ref/path/pattern value the caller intended. Any Vehicle
+ * operation that hands a caller-supplied string to a shelled-out CLI's argv should run it through
+ * this check first, at the exact position it reaches that argv.
+ *
+ * This is a hard rejection with no exceptions -- it has no opinion about *why* a value starting
+ * with `-` might be needed and does not attempt to allow-list specific flags. A caller whose CLI
+ * genuinely accepts caller-influenced flag-shaped arguments needs a purpose-built allow-list of
+ * its own; this primitive only ever covers the common case of a value that should always be a
+ * literal.
+ */
+export class UnsafeCliArgument extends Error {
+    value;
+    fieldName;
+    constructor(value, fieldName) {
+        super(fieldName
+            ? `"${value}" cannot be used as ${fieldName} -- it would be interpreted as a CLI flag, not a literal value`
+            : `"${value}" cannot be used as a CLI argument -- it would be interpreted as a flag, not a literal value`);
+        this.value = value;
+        this.fieldName = fieldName;
+        this.name = "UnsafeCliArgument";
+    }
+}
+/** Throws UnsafeCliArgument if `value` starts with `-`. `fieldName`, when given, names the field in the thrown error's own message for a caller with several distinct argv positions to check. */
+export function assertNoLeadingFlagChar(value, fieldName) {
+    if (value.startsWith("-"))
+        throw new UnsafeCliArgument(value, fieldName);
+}

package/dist/cli-safety/index.d.ts

@@ -0,0 +1 @@
+export * from "./assert-no-leading-flag-char.js";

package/dist/cli-safety/index.js

@@ -0,0 +1 @@
+export * from "./assert-no-leading-flag-char.js";

package/dist/index.d.ts

@@ -6,13 +6,16 @@
  * classification, invocation context), events, manifest, client (the port a
  * caller programs against), approvals (the Approval Gate's wire shapes), jobs
  * (Vehicle Jobs' pure pieces), schedules, watches, persistence (atomic
- * JSON), and concurrency (timer-based scheduling primitives) -- the latter
- * two are technical utilities, not Vehicle protocol capabilities, kept
- * distinct for that reason. Every symbol below is re-exported unchanged
+ * JSON), concurrency (timer-based scheduling primitives), cli-safety
+ * (argv-injection guards for any operation shelling out to a CLI), and
+ * resource-pool (bounded admission/eviction/leasing for a pooled expensive
+ * stateful resource) -- the latter four are technical utilities, not
+ * Vehicle protocol capabilities, kept distinct for that reason. Every symbol below is re-exported unchanged
  * from its historical flat-file home, so root-level `import { X } from
  * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
  */
 export * from "./approvals/index.js";
+export * from "./cli-safety/index.js";
 export * from "./client/index.js";
 export * from "./concurrency/index.js";
 export * from "./content/index.js";
@@ -23,6 +26,7 @@ export * from "./jobs/index.js";
 export * from "./manifest/index.js";
 export * from "./operations/index.js";
 export * from "./persistence/index.js";
+export * from "./resource-pool/index.js";
 export * from "./schedules/index.js";
 export * from "./schemas/index.js";
 export * from "./watches/index.js";

package/dist/index.js

@@ -6,13 +6,16 @@
  * classification, invocation context), events, manifest, client (the port a
  * caller programs against), approvals (the Approval Gate's wire shapes), jobs
  * (Vehicle Jobs' pure pieces), schedules, watches, persistence (atomic
- * JSON), and concurrency (timer-based scheduling primitives) -- the latter
- * two are technical utilities, not Vehicle protocol capabilities, kept
- * distinct for that reason. Every symbol below is re-exported unchanged
+ * JSON), concurrency (timer-based scheduling primitives), cli-safety
+ * (argv-injection guards for any operation shelling out to a CLI), and
+ * resource-pool (bounded admission/eviction/leasing for a pooled expensive
+ * stateful resource) -- the latter four are technical utilities, not
+ * Vehicle protocol capabilities, kept distinct for that reason. Every symbol below is re-exported unchanged
  * from its historical flat-file home, so root-level `import { X } from
  * "@danypops/vehicle-core"` usage is completely unaffected by this layout.
  */
 export * from "./approvals/index.js";
+export * from "./cli-safety/index.js";
 export * from "./client/index.js";
 export * from "./concurrency/index.js";
 export * from "./content/index.js";
@@ -23,6 +26,7 @@ export * from "./jobs/index.js";
 export * from "./manifest/index.js";
 export * from "./operations/index.js";
 export * from "./persistence/index.js";
+export * from "./resource-pool/index.js";
 export * from "./schedules/index.js";
 export * from "./schemas/index.js";
 export * from "./watches/index.js";

package/dist/resource-pool/bounded-resource-pool.d.ts

@@ -0,0 +1,139 @@
+import { ResourceAdmissionQueueFull, ResourceAdmissionQueueTimedOut, ResourceCapacityExceeded, ResourceInUse } from "./errors.js";
+import type { ResourcePoolActiveCeilingSource, ResourcePoolResourcePolicy } from "./resource-policy.js";
+export { ResourceAdmissionQueueFull, ResourceAdmissionQueueTimedOut, ResourceCapacityExceeded, ResourceInUse };
+/** A resource the pool can shut down when it goes cold. costHandle, when present, is an opaque token a cost-sampling hook may key off (e.g. a subprocess pid) -- undefined for a resource with nothing external to sample. */
+export interface PooledResource {
+    close(): Promise<void>;
+    isAlive?(): boolean;
+    readonly costHandle?: unknown;
+}
+/**
+ * Distinguishes an interactive human/agent-facing request from a self-scheduled background one.
+ * Foreground admission is never queued or reduced below reservedForegroundSlots' effective
+ * ceiling -- background is the only work kind that ever waits. Defaults to "foreground": a caller
+ * that never opts in gets today's exact unreserved behavior.
+ */
+export type ResourceWorkKind = "foreground" | "background";
+export type ResourcePoolEvent = {
+    readonly kind: "admission-evicted" | "dead-replaced" | "resource-pressure-evicted";
+    readonly partitionKey: string;
+} | {
+    readonly kind: "close-failed";
+    readonly reason: "admission" | "dead-replacement" | "idle-reap" | "resource-pressure";
+    readonly partitionKey: string;
+    readonly errorName: string;
+};
+export interface ResourcePoolStatus<Status = unknown> {
+    readonly active: number;
+    readonly leased: number;
+    readonly maxActive: number;
+    /** The count ceiling actually in effect for the most recent admission -- may exceed maxActive when a resource policy's own soft ceiling raised it, never exceeds absoluteMaxActive. */
+    readonly effectiveMaxActive: number;
+    readonly activeCeilingSource: ResourcePoolActiveCeilingSource;
+    readonly absoluteMaxActive: number;
+    readonly byPartition: Readonly<Record<string, number>>;
+    readonly resources?: Status;
+    /** How many background admissions are currently waiting for a slot reserved for foreground work -- count-only, zero whenever reservedForegroundSlots is unset or nothing is contending. */
+    readonly waitingBackgroundAdmissions: number;
+}
+export interface PoolLease<Value> extends AsyncDisposable {
+    readonly value: Value;
+}
+export interface ResourcePoolOptions<Status = unknown> {
+    readonly maxActive?: number;
+    readonly partitionLimits?: Readonly<Record<string, number>>;
+    readonly resourcePolicy?: ResourcePoolResourcePolicy<Status>;
+    /** The hard structural ceiling a resource policy's own soft ceiling can never raise maxActive past. Defaults to 32. Must be >= maxActive. */
+    readonly absoluteMaxActive?: number;
+    readonly observe?: (event: ResourcePoolEvent) => void;
+    /** Slots background admission alone can never grow into. Default 0 (no reservation). */
+    readonly reservedForegroundSlots?: number;
+    /** How long a queued background admission waits for a slot before giving up with ResourceAdmissionQueueTimedOut. Default 10s. */
+    readonly backgroundAdmissionQueueTimeoutMs?: number;
+    /** How many background admissions may be simultaneously waiting before a new one fails fast with ResourceAdmissionQueueFull instead of growing the wait queue further. Default 8. */
+    readonly maxQueuedBackgroundAdmissions?: number;
+    /** Fed one (partitionKey, costHandle) pair per active entry with a costHandle on calibrateCosts(). */
+    readonly costRecorder?: {
+        recordSample(partitionKey: string, costHandle: unknown): void;
+    };
+    readonly now?: () => number;
+}
+/**
+ * Owns the bounded lifecycle of pooled, expensive, stateful resources partitioned by an
+ * (ownerKey, partitionKey) pair -- e.g. one warm language-server process per (workspace,
+ * language), one warm browser context per (tenant, profile). Never knows how to build a resource:
+ * `acquire()` takes a lazy factory invoked only on an actual cache miss, so every caller-specific
+ * concept (what a resource even is, how to construct one) lives entirely in the caller's own
+ * closure at each call site.
+ */
+export declare class BoundedResourcePool<OwnerKey extends string, Resource extends PooledResource, Status = unknown> {
+    private readonly options;
+    private readonly entries;
+    private readonly now;
+    private readonly maxActive;
+    private readonly absoluteMaxActive;
+    private lastActiveCeilingSource;
+    private lastEffectiveMaxActive;
+    private readonly partitionLimits;
+    private admissionTail;
+    private nextSequence;
+    private readonly reservedForegroundSlots;
+    private readonly backgroundAdmissionQueueTimeoutMs;
+    private readonly maxQueuedBackgroundAdmissions;
+    private readonly admissionWaiters;
+    private queuedBackgroundAdmissions;
+    private readonly waitingCounts;
+    constructor(options?: ResourcePoolOptions<Status>);
+    private key;
+    private partitionLimit;
+    private countPartition;
+    private activePartitions;
+    private leastRecentlyUsedIdle;
+    private evict;
+    /** Wakes every queued background admission to re-check the real state -- called whenever an entry is removed OR a lease completes (an idle candidate an admit() retry might now be able to evict). A false wake just re-checks and re-waits; never a correctness issue, only a wasted retry. */
+    private notifyAdmissionWaiters;
+    /** True while at least one background admission for this owner is currently waiting for a reserved-slot conflict to clear. */
+    waitingForAdmission(ownerKey: OwnerKey): boolean;
+    /**
+     * Runs entirely outside the serialized admission lock -- admissionTail is the single global
+     * admission mutex, and this wait can legitimately take up to backgroundAdmissionQueueTimeoutMs.
+     * Holding that lock for the whole wait would block every other admission request, foreground
+     * included, which is the exact starvation this exists to prevent.
+     */
+    private waitForAdmissionRoom;
+    private admit;
+    private serialized;
+    /** Acquires a lease for (ownerKey, partitionKey), reusing an already-admitted resource if one is warm, or admitting a fresh one via `create()` -- called only on an actual cache miss, never speculatively. workKind defaults to "foreground". */
+    acquire(ownerKey: OwnerKey, partitionKey: string, create: () => Resource, workKind?: ResourceWorkKind): Promise<PoolLease<Resource>>;
+    private lease;
+    has(ownerKey: OwnerKey, partitionKey: string): boolean;
+    hasAny(ownerKey: OwnerKey): boolean;
+    /** Every currently active resource belonging to `ownerKey` -- lets a caller's own fan-out (file-watch notifications, etc) stay pool-backed instead of duplicating the entry map. */
+    activeResourcesForOwner(ownerKey: OwnerKey): readonly Resource[];
+    /**
+     * Derives the count ceiling actually in effect right now, independent of any particular
+     * admission attempt -- the resource policy's own soft ceiling raises maxActive when it reports
+     * more room, clamped to absoluteMaxActive, and falls back to maxActive alone (source
+     * "configured") on any metric loss -- fails closed, never treated as "unlimited room."
+     */
+    private baseActiveCeiling;
+    status(): ResourcePoolStatus<Status>;
+    /** Samples every currently active entry with a real costHandle and folds it into the configured recorder, if any -- a no-op without one. Read-only over the entry map, so it deliberately does not run inside serialized(). */
+    calibrateCosts(): void;
+    /** Unconditional force-close of every one of `ownerKey`'s resources, regardless of any active lease -- for the case of a remote resource swapped out from under an already-warm one, where correctness requires closing regardless of who still holds it. */
+    closeOwner(ownerKey: OwnerKey): Promise<void>;
+    /** Unconditional force-close of one (ownerKey, partitionKey) resource, if any -- the single-partition sibling of closeOwner, for a caller that has already identified exactly which partition needs invalidating. */
+    closePartition(ownerKey: OwnerKey, partitionKey: string): Promise<void>;
+    /**
+     * The safe sibling of closeOwner: refuses (does not evict anything) while any of this owner's
+     * resources has an active lease. Serialized against concurrent admission so a lease can't be
+     * granted between the check and the close.
+     */
+    releaseOwnerIfIdle(ownerKey: OwnerKey): Promise<{
+        readonly closed: number;
+    }>;
+    closeAll(): Promise<void>;
+    private reconcileResourcesUnsafe;
+    reconcileResources(): Promise<number>;
+    reapIdle(maxIdleMs: number): Promise<number>;
+}