@north-light/crouter 0.3.281 → 0.3.282

package/dist/core/manifest-recovery.js

@@ -0,0 +1,72 @@
+// Dispatch with recovery from an out-of-date command description.
+//
+// Extracted from the cli entry so the whole behaviour — rethrow, refetch,
+// re-parse, exactly-once — can be driven by a test through `runCli` and a real
+// error off the wire, rather than only by launching the binary.
+import { resolveRoot } from '../build-root.js';
+import { runCli } from './command.js';
+import { forceRevalidateBundlePlugin } from './command-plugins/revalidate.js';
+import { handle } from './io.js';
+import { staleManifestPlugin } from './manifest-stale.js';
+/**
+ * Run `argv` against `root`, and if the backend answers `manifest_stale`,
+ * refetch that plugin's package and run the ORIGINAL argv again against a
+ * freshly resolved tree — exactly once.
+ *
+ * Re-parsing the original argv, rather than re-running the leaf that failed, is
+ * what makes a RENAMED verb recoverable: the old leaf no longer exists in the
+ * refreshed tree, and only the dispatcher can answer that against the fresh
+ * tree's own siblings.
+ *
+ * Never throws: every outcome is rendered through the dispatcher's own
+ * `handle`, so a caller can mark the end of dispatch unconditionally.
+ */
+export async function dispatchWithStaleRecovery(root, argv) {
+    try {
+        // The dispatcher renders every other failure itself; a `manifest_stale`
+        // error is the one it rethrows, because recovery needs this frame.
+        await runCli(root, argv);
+        return;
+    }
+    catch (error) {
+        if (!(await refetchStalePlugin(error))) {
+            // Nothing newer to run against: report the backend's own complaint
+            // exactly as the dispatcher would have.
+            handle(error);
+            return;
+        }
+        try {
+            // The refreshed tree, re-resolved: the package this invocation dispatches
+            // against is not the one it was built from. Replaying the argv is only
+            // safe because a server that sets the flag has promised it — the two
+            // preconditions are recorded on `ManifestStaleEnvelope` in
+            // `src/api/plugin-manifest-schema.ts`, and crtr cannot check either one.
+            await runCli(await resolveRoot(argv[2]), argv);
+        }
+        catch (retryError) {
+            // Exactly once. A second `manifest_stale` against a package just
+            // refetched is the server's answer, not another refresh cycle.
+            handle(retryError);
+        }
+    }
+}
+/**
+ * A backend that answers `manifest_stale` is saying this client invoked from an
+ * out-of-date description of its commands. Refetch that plugin's package and
+ * report whether it actually changed. An unchanged package means the operation
+ * is genuinely gone, so the server's own error, which already names what it
+ * does serve, is the honest answer and stands.
+ */
+async function refetchStalePlugin(error) {
+    const plugin = staleManifestPlugin(error);
+    if (plugin === undefined)
+        return false;
+    try {
+        return await forceRevalidateBundlePlugin(plugin);
+    }
+    catch {
+        // The refetch is the recovery. If it fails there is nothing newer to retry
+        // against, and the server's original complaint is what the caller needs.
+        return false;
+    }
+}

package/dist/core/manifest-stale.d.ts

@@ -0,0 +1,18 @@
+import type { ManifestStaleEnvelope } from '../api/plugin-manifest-schema.js';
+/** What crtr attaches to the `CrtrError` it raises for a stale answer. */
+type StaleErrorDetails = Required<ManifestStaleEnvelope> & {
+    plugin: string;
+};
+/** Did the backend's own error envelope claim staleness? Reads the parsed JSON
+ *  body, before it becomes a `CrtrError`. */
+export declare function envelopeClaimsStale(envelope: Record<string, unknown>): boolean;
+/** The details a transport adds when it converts a stale envelope into the
+ *  error the dispatcher rethrows. */
+export declare function staleErrorDetails(plugin: string): StaleErrorDetails;
+/** Is this the one error class the dispatcher rethrows instead of rendering? */
+export declare function isManifestStaleError(error: unknown): boolean;
+/** The plugin to refetch, or `undefined` when this error is not a recoverable
+ *  stale answer. A stale flag with no plugin name is not actionable: nothing
+ *  identifies the package whose description went out of date. */
+export declare function staleManifestPlugin(error: unknown): string | undefined;
+export {};

package/dist/core/manifest-stale.js

@@ -0,0 +1,39 @@
+// The one place in crtr that names the `manifest_stale` wire field.
+//
+// The field itself is declared in the published format subpath
+// (`src/api/plugin-manifest-schema.ts`), which is what a plugin backend compiles
+// against. This module binds crtr's readers and writer to that declaration, so
+// renaming the field there fails the build here rather than silently splitting
+// the two sides: a backend that keeps setting a field nobody reads, and a client
+// that never recovers.
+import { CrtrError } from './errors.js';
+/** Bound to the published declaration: `keyof` is the field's literal type, so
+ *  a rename over there makes this assignment a type error. */
+const STALE_FIELD = 'manifest_stale';
+/** The plugin whose package produced the out-of-date description, carried
+ *  alongside the flag so the recovery frame knows what to refetch. The backend
+ *  does not send this — the transport that made the call names it. */
+const PLUGIN_FIELD = 'plugin';
+/** Did the backend's own error envelope claim staleness? Reads the parsed JSON
+ *  body, before it becomes a `CrtrError`. */
+export function envelopeClaimsStale(envelope) {
+    return envelope[STALE_FIELD] === true;
+}
+/** The details a transport adds when it converts a stale envelope into the
+ *  error the dispatcher rethrows. */
+export function staleErrorDetails(plugin) {
+    return { [STALE_FIELD]: true, [PLUGIN_FIELD]: plugin };
+}
+/** Is this the one error class the dispatcher rethrows instead of rendering? */
+export function isManifestStaleError(error) {
+    return error instanceof CrtrError && error.details?.[STALE_FIELD] === true;
+}
+/** The plugin to refetch, or `undefined` when this error is not a recoverable
+ *  stale answer. A stale flag with no plugin name is not actionable: nothing
+ *  identifies the package whose description went out of date. */
+export function staleManifestPlugin(error) {
+    if (!isManifestStaleError(error))
+        return undefined;
+    const plugin = error.details?.[PLUGIN_FIELD];
+    return typeof plugin === 'string' ? plugin : undefined;
+}

package/dist/core/plugin-swap-lock.d.ts

@@ -0,0 +1,9 @@
+/** Under the scope root's `tmp/`, alongside the staging and `.prev` dirs the
+ *  swap itself uses, so one directory holds the whole transition. */
+export declare function bundleSwapLockPath(scopeRootPath: string, name: string): string;
+/** Whether ANOTHER live process currently holds this plugin's swap lock. Our
+ *  own lock does not count: the swapper reads the plugin list from inside its
+ *  own critical section. */
+export declare function bundleSwapInFlightElsewhere(scopeRootPath: string, name: string): boolean;
+/** Wait out another process's swap of this plugin, bounded. */
+export declare function awaitBundleSwap(scopeRootPath: string, name: string): void;

package/dist/core/plugin-swap-lock.js

@@ -0,0 +1,31 @@
+// The one name for the lock a bundle-plugin package swap is held under, and the
+// two questions a reader asks about it.
+//
+// Two modules need it and neither may own it: the swapper lives in
+// `commands/pkg/plugin-manage.ts` (the whole command graph), the reader in
+// `core/installed-plugins.ts` (deliberately leaf-safe: types, fs-utils,
+// manifest). This module keeps both dependency-light — `node:path` plus the
+// generic lock primitive, which itself imports only `node:fs` and
+// `node:crypto`.
+import { join } from 'node:path';
+import { awaitExclusiveLockRelease, exclusiveLockOwnerPid } from './exclusive-lock.js';
+/** How long a reader waits for another process's swap to finish before it
+ *  reports what it can see. A swap is one rename of an already-staged, already-
+ *  validated tree, so a wait this long means the holder is wedged, not slow. */
+const READER_WAIT_MS = 2_000;
+/** Under the scope root's `tmp/`, alongside the staging and `.prev` dirs the
+ *  swap itself uses, so one directory holds the whole transition. */
+export function bundleSwapLockPath(scopeRootPath, name) {
+    return join(scopeRootPath, 'tmp', `${name}.swap.lock`);
+}
+/** Whether ANOTHER live process currently holds this plugin's swap lock. Our
+ *  own lock does not count: the swapper reads the plugin list from inside its
+ *  own critical section. */
+export function bundleSwapInFlightElsewhere(scopeRootPath, name) {
+    const pid = exclusiveLockOwnerPid(bundleSwapLockPath(scopeRootPath, name));
+    return pid !== null && pid !== process.pid;
+}
+/** Wait out another process's swap of this plugin, bounded. */
+export function awaitBundleSwap(scopeRootPath, name) {
+    awaitExclusiveLockRelease(bundleSwapLockPath(scopeRootPath, name), READER_WAIT_MS);
+}

package/dist/types.d.ts

@@ -386,8 +386,15 @@ export interface ScopeState {
     marketplaces: Record<string, {
         last_updated?: string;
     }>;
+    /** Per-plugin cache bookkeeping for the bundle revalidation pass.
+     *  `etag` is the validator the server returned with the archive currently
+     *  unpacked on disk, replaced only on a 200. `checked_at` is written on every
+     *  revalidation attempt, success or failure, so an unreachable server costs
+     *  one timed-out probe per TTL rather than one per command. */
     plugins: Record<string, {
         last_updated?: string;
+        etag?: string;
+        checked_at?: string;
     }>;
     last_self_check?: string;
     /** The name of the remote canvas target `crtr canvas use` last selected

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.281",
+  "version": "0.3.282",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -76,6 +76,7 @@
     "typecheck:pi-packages": "npx tsc -p src/builtin-pi-packages/pi-crtr-extensions/tsconfig.json",
     "test:build-output": "node scripts/build-concurrency-test.mjs",
     "check:cli-no-canvas": "node scripts/check-cli-no-canvas.mjs",
+    "check:cli-cold-start": "node scripts/check-cli-cold-start.mjs",
     "check:daemon-no-barrel": "node scripts/check-daemon-no-barrel.mjs",
     "check:quote-style": "node scripts/check-quote-style.mjs",
     "postinstall": "node scripts/postinstall.mjs",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.281",
+  "version": "0.3.282",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.281",
+      "version": "0.3.282",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {