@sous-io/plugin-api 1.0.15 → 1.0.16

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import type { Environment, ProjectInfo } from "./context.js";
+import type { IntentDefinition } from "./intents.js";
 import type { EntityReader } from "./entities.js";
 import type { JsonObject, JsonValue, Patch, PatchSet, PathInput } from "./json.js";
 import type { DocumentNode } from "./node.js";
@@ -111,6 +112,11 @@ export interface ConfigBuilder extends Reporter {
     readonly contributor: ContributorInfo;
     readonly project: ProjectInfo | undefined;
     readonly env: Environment;
+    /**
+     * What the front end is about to run, when it said (`BuildOptions.plan`); `undefined` when
+     * nothing is known, as for a library caller or a command only a plugin loaded later adds.
+     */
+    readonly plan: RunPlan | undefined;
 }
 /**
  * A contributor: anything that adds to the config.
@@ -167,4 +173,22 @@ export interface BuildOptions {
      * where the warning is noise above the answer. The build is still timed (`--timings`).
      */
     reportBudgets?: boolean;
+    /**
+     * What the front end is about to run, when it read its command line before the config was built.
+     * The engine keeps it for every later build in the same run, and contributors read it as
+     * `config.plan`.
+     */
+    plan?: RunPlan;
+}
+/**
+ * What a front end is about to run, read from its command line before the config was built.
+ *
+ * ```ts
+ * { intent: buildDefinition }   // `sous build`
+ * { intent: undefined }         // `sous --help`, `sous --version`: no intent runs
+ * ```
+ */
+export interface RunPlan {
+    /** The intent it will submit, or `undefined` when it runs none (help, the version). */
+    readonly intent: IntentDefinition | undefined;
 }

package/dist/intents.d.ts

@@ -102,6 +102,13 @@ export interface IntentDefinition<N extends string = string, S extends SousSchem
      * config is built, when the project loads no plugin beyond the built-in ones.
      */
     runsWithoutConfig?: boolean;
+    /**
+     * `boolean = false`. It reads the files of the recipes the project subscribes to (their config
+     * layers, plugins, variables or content), so sous downloads every pinned recipe this machine lacks
+     * before it runs, and fails when one cannot be downloaded. Any other intent runs with the recipe
+     * files already on this machine, so it works offline and without credentials.
+     */
+    needsRecipeFiles?: boolean;
     /**
      * It works on a project, so it fails, before it runs, when sous was started outside one: the
      * error says no sous config was found and how to set a project up.

package/dist/plugin.d.ts

@@ -1,4 +1,4 @@
-import type { ContributorDefinition } from "./config.js";
+import type { ContributorDefinition, RunPlan } from "./config.js";
 import type { Environment, EngineHandle, ProjectInfo } from "./context.js";
 import type { EntityKindOptions, EntityReader } from "./entities.js";
 import type { EventFor, EventForPattern, EventPattern, EventPayload, Listener, ListenerOptions } from "./events.js";
@@ -60,6 +60,12 @@ export interface FrontEndDefinition {
      * building the config when the project loads no further plugin.
      */
     needsConfig?(engine: EngineHandle, argv: readonly string[]): boolean;
+    /**
+     * What `argv` will run, read before the config is built (asked on the config of the built-in
+     * plugins' registrations alone), or `undefined` when it cannot tell. The application passes it to
+     * the config build as `plan`.
+     */
+    plan?(engine: EngineHandle, argv: readonly string[]): RunPlan | undefined;
 }
 /** `sous.intents`. */
 export interface IntentRegistry {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/plugin-api",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "The plugin interface of sous: definePlugin, the shared type interfaces, Reporter, Prompter and the error classes",
   "type": "module",
   "license": "Apache-2.0",