@opensip-cli/simulation 0.1.0

package/dist/recipes/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Sim recipe types — mirrors the fitness recipe shape so
+ * users get the same mental model across both tools.
+ *
+ * A recipe is a named bundle that selects scenarios and configures their
+ * execution. The user runs `opensip sim --recipe <name>` to invoke
+ * one. Without a flag, the built-in `default` recipe applies.
+ */
+import type { ScenarioKind } from '../types/kind-types.js';
+/** Selector that specifies scenarios by explicit ID list. */
+export interface ExplicitScenarioSelector {
+    readonly type: 'explicit';
+    readonly scenarioIds: readonly string[];
+}
+/** Selector that includes all scenarios with optional exclusions. */
+export interface AllScenarioSelector {
+    readonly type: 'all';
+    readonly exclude?: readonly string[];
+}
+/** Selector that includes scenarios with specified tags. */
+export interface TagsScenarioSelector {
+    readonly type: 'tags';
+    readonly include: readonly string[];
+    readonly exclude?: readonly string[];
+}
+/** Selector that filters by scenario kind (load / chaos). */
+export interface KindScenarioSelector {
+    readonly type: 'kind';
+    readonly kinds: readonly ScenarioKind[];
+    readonly exclude?: readonly string[];
+}
+/**
+ * Union of every scenario-selector shape used by recipes.
+ *
+ * The `explicit` / `all` / `tags` arms mirror `@opensip-cli/core`'s
+ * `RecipeSelector` shape (keeping sim's historical `scenarioIds` field on
+ * `explicit`); `kind` is a sim-only arm. Resolution delegates to core's
+ * `resolveSelector` via per-arm predicates (see `service.ts`) — sim's
+ * id/name-keyed exclude semantics differ from core's tag/glob built-ins, so
+ * every arm is supplied as a predicate and core never names `ScenarioKind`.
+ */
+export type ScenarioSelector = ExplicitScenarioSelector | AllScenarioSelector | TagsScenarioSelector | KindScenarioSelector;
+/** Execution configuration for a sim recipe. */
+export interface SimulationExecutionOptions {
+    readonly mode: 'parallel' | 'sequential';
+    readonly timeout?: number;
+    readonly maxParallel?: number;
+    readonly stopOnFirstFailure?: boolean;
+}
+/** Complete sim-recipe definition: scenarios + execution. */
+export interface SimulationRecipe {
+    readonly id: string;
+    readonly name: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly scenarios: ScenarioSelector;
+    readonly execution: SimulationExecutionOptions;
+    readonly tags?: readonly string[];
+}
+/** Author-facing config — `kind` is implicit, `id`/`name` are required. */
+export type SimulationRecipeConfig = SimulationRecipe;
+//# sourceMappingURL=types.d.ts.map

package/dist/recipes/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/recipes/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAM3D,6DAA6D;AAC7D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GACxB,wBAAwB,GACxB,mBAAmB,GACnB,oBAAoB,GACpB,oBAAoB,CAAC;AAMzB,gDAAgD;AAChD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC;AAMD,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,0BAA0B,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,2EAA2E;AAC3E,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,CAAC"}

package/dist/recipes/types.js

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Sim recipe types — mirrors the fitness recipe shape so
+ * users get the same mental model across both tools.
+ *
+ * A recipe is a named bundle that selects scenarios and configures their
+ * execution. The user runs `opensip sim --recipe <name>` to invoke
+ * one. Without a flag, the built-in `default` recipe applies.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/recipes/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/recipes/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/scaffold/examples.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview simulation's `init` example contribution (ADR-0038).
+ *
+ * simulation OWNS the example scenario/recipe bytes that `init` scaffolds —
+ * relocated here from the CLI's `config-templates.ts`. sim's examples are
+ * language-independent, so the `ScaffoldContext` is ignored. Byte content is
+ * verbatim; a Phase-0 golden + a Phase-1 parity test pin byte-identity.
+ */
+import type { ScaffoldContext, ScaffoldFile } from '@opensip-cli/core';
+/** Example simulation scenario source (verbatim). */
+export declare function exampleScenarioSource(): string;
+/** Example simulation recipe source (verbatim). */
+export declare function exampleSimRecipeSource(): string;
+/**
+ * simulation's scaffold contribution — language-independent (`ctx` ignored):
+ * `scenarios/example-scenario.mjs` + `recipes/example-recipe.mjs`, matching
+ * `scaffold-writer.ts`'s sim logic.
+ */
+export declare function simScaffoldExamples(_ctx: ScaffoldContext): ScaffoldFile[];
+/** simulation's COMPLETE stable example-id set (language-independent). */
+export declare function simStableExampleIds(): string[];
+//# sourceMappingURL=examples.d.ts.map

package/dist/scaffold/examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"examples.d.ts","sourceRoot":"","sources":["../../src/scaffold/examples.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEvE,qDAAqD;AACrD,wBAAgB,qBAAqB,IAAI,MAAM,CAiC9C;AAED,mDAAmD;AACnD,wBAAgB,sBAAsB,IAAI,MAAM,CAoB/C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,YAAY,EAAE,CAezE;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C"}

package/dist/scaffold/examples.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview simulation's `init` example contribution (ADR-0038).
+ *
+ * simulation OWNS the example scenario/recipe bytes that `init` scaffolds —
+ * relocated here from the CLI's `config-templates.ts`. sim's examples are
+ * language-independent, so the `ScaffoldContext` is ignored. Byte content is
+ * verbatim; a Phase-0 golden + a Phase-1 parity test pin byte-identity.
+ */
+/** Example simulation scenario source (verbatim). */
+export function exampleScenarioSource() {
+    return `// Example simulation scenario — a real load window against an in-process target.
+//
+// 'sim' is a standalone driver: you bring the target. This demo drives a
+// trivial in-process target so it runs out-of-box and shows the harness
+// mechanics (a real request loop, measured latency, asserted SLOs). To test
+// YOUR service, replace 'target' with httpTarget({ url: process.env.TARGET_URL })
+// — and point it only at a target you own. For fault injection, see the chaos
+// docs (defineChaosScenario + fault.*).
+//
+// Edit this file or add new .mjs files to opensip-cli/sim/scenarios/.
+// Files in this directory are auto-loaded on the next \`opensip sim\` run.
+//
+// Docs: https://github.com/opensip-ai/opensip-cli#simulation
+import { defineLoadScenario, ASSERTIONS /*, httpTarget */ } from '@opensip-cli/simulation';
+
+export const scenarios = [
+  defineLoadScenario({
+    id: 'example-scenario',
+    name: 'example-scenario',
+    description: 'Demo load scenario — drives a trivial in-process target',
+    tags: ['example'],
+    // BYO target: any async function that resolves on success / throws on failure.
+    // Swap for your service:  target: httpTarget({ url: process.env.TARGET_URL }),
+    target: async () => {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    },
+    workload: { rps: 20, rampUp: 1 },
+    duration: 3,
+    assertions: [ASSERTIONS.lowErrorRate(), ASSERTIONS.lowLatency('p95', 500)],
+  }),
+];
+`;
+}
+/** Example simulation recipe source (verbatim). */
+export function exampleSimRecipeSource() {
+    return `// Example simulation recipe — runs only the example scenario.
+//
+// Edit this file or add new .mjs files to opensip-cli/sim/recipes/.
+// Files in this directory are auto-loaded on the next run.
+//
+// Run this recipe explicitly:  opensip sim --recipe example
+import { defineSimulationRecipe } from '@opensip-cli/simulation';
+
+export const recipes = [
+  defineSimulationRecipe({
+    id: 'URCP_sim_example',
+    name: 'example',
+    displayName: 'Example',
+    description: 'Demo recipe — runs only the example scenario',
+    scenarios: { type: 'explicit', scenarioIds: ['example-scenario'] },
+    execution: { mode: 'parallel', timeout: 30_000 },
+  }),
+];
+`;
+}
+/**
+ * simulation's scaffold contribution — language-independent (`ctx` ignored):
+ * `scenarios/example-scenario.mjs` + `recipes/example-recipe.mjs`, matching
+ * `scaffold-writer.ts`'s sim logic.
+ */
+export function simScaffoldExamples(_ctx) {
+    return [
+        {
+            kind: 'scenarios',
+            filename: 'example-scenario.mjs',
+            content: exampleScenarioSource(),
+            stableId: 'example-scenario',
+        },
+        {
+            kind: 'recipes',
+            filename: 'example-recipe.mjs',
+            content: exampleSimRecipeSource(),
+            stableId: 'URCP_sim_example',
+        },
+    ];
+}
+/** simulation's COMPLETE stable example-id set (language-independent). */
+export function simStableExampleIds() {
+    return ['example-scenario', 'URCP_sim_example'];
+}
+//# sourceMappingURL=examples.js.map

package/dist/scaffold/examples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"examples.js","sourceRoot":"","sources":["../../src/scaffold/examples.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,qDAAqD;AACrD,MAAM,UAAU,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BR,CAAC;AACF,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,sBAAsB;IACpC,OAAO;;;;;;;;;;;;;;;;;;CAkBR,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAqB;IACvD,OAAO;QACL;YACE,IAAI,EAAE,WAAW;YACjB,QAAQ,EAAE,sBAAsB;YAChC,OAAO,EAAE,qBAAqB,EAAE;YAChC,QAAQ,EAAE,kBAAkB;SAC7B;QACD;YACE,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,oBAAoB;YAC9B,OAAO,EAAE,sBAAsB,EAAE;YACjC,QAAQ,EAAE,kBAAkB;SAC7B;KACF,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB;IACjC,OAAO,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;AAClD,CAAC"}

package/dist/scope-augmentation.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview RunScope augmentation for simulation.
+ *
+ * D7 (tool subscopes via module augmentation, per the RunScope/
+ * Registry architecture): tool-specific concerns nest under the
+ * tool's name on `RunScope` and
+ * are added via TypeScript module augmentation from the tool's own
+ * package. Core never imports simulation-shaped types — the layer rule
+ * stays intact (`core ← contracts ← {simulation, ...}`).
+ *
+ * Two singletons used to hang off this package as module-level state:
+ *
+ *   - `scenarioRegistry`                — per-process scenario registry.
+ *   - `defaultSimulationRecipeRegistry` — per-process recipe registry.
+ *
+ * Both are now per-RunScope. The simulation tool's `contributeScope` hook
+ * (in `tool.ts`) instantiates fresh registries and attaches them to
+ * `scope.simulation` once per CLI invocation. Tools and library code
+ * read via `currentScope()?.simulation?.{scenarios,recipes}`.
+ *
+ * The `simulation` slot is intentionally optional and mutable (no
+ * `readonly`) on the augmented interface: the kernel doesn't construct
+ * it, and only the simulation tool's `contributeScope` writes to it during
+ * scope construction. A run that doesn't load the simulation tool
+ * carries no `scope.simulation`, and reads return `undefined`.
+ */
+import type { RunnableScenario } from './framework/runnable-scenario.js';
+import type { SimulationRecipeRegistry } from './recipes/registry.js';
+import type { Registry } from '@opensip-cli/core';
+/**
+ * Per-RunScope `ensureScenariosLoaded` lifecycle state — moved off the `sim.ts`
+ * module singletons (`scenariosLoadedFor` / `pluginLoadErrors`) so two concurrent
+ * sim runs carry independent load state (audit F1). Mutable: written once per run
+ * by `ensureScenariosLoaded`; read by `getPluginLoadErrors`.
+ */
+export interface SimulationLoadState {
+    /** Project directory `ensureScenariosLoaded` has completed for in THIS scope.
+     *  `null` before the first load; `''` is the "loaded" sentinel for no-project. */
+    loadedFor: string | null;
+    /** Plugin load failures from the most recent `ensureScenariosLoaded` call. */
+    pluginLoadErrors: readonly string[];
+}
+/**
+ * Per-RunScope simulation state. Constructed by the simulation tool's
+ * `contributeScope()` hook and attached to `scope.simulation`.
+ */
+export interface SimulationSubscope {
+    /** Scenario registry — populated through the generic capability loader
+     *  (`sim-pack` domain) + `loadAllSimPlugins` during `ensureScenariosLoaded`. */
+    readonly scenarios: Registry<RunnableScenario>;
+    /** Recipe registry — seeded with built-in recipes at construction;
+     *  plugin loader + the sim-recipe domain register user recipes. */
+    readonly recipes: SimulationRecipeRegistry;
+    /** `ensureScenariosLoaded` lifecycle state for this run (audit F1). */
+    readonly load: SimulationLoadState;
+}
+declare module '@opensip-cli/core' {
+    interface ScopeContribution {
+        /**
+         * Simulation tool's per-run state. Returned by the simulation tool's
+         * `contributeScope` hook and installed by the kernel; absent in runs
+         * where the simulation tool is not registered. Consumers MUST
+         * null-check before reading. Augments `ScopeContribution`, which
+         * `ToolScope`/`RunScope` extend — so `cli.scope.simulation` /
+         * `currentScope()?.simulation` stay readable (audit 2026-05-29, M4).
+         */
+        simulation?: SimulationSubscope;
+    }
+}
+//# sourceMappingURL=scope-augmentation.d.ts.map

package/dist/scope-augmentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-augmentation.d.ts","sourceRoot":"","sources":["../src/scope-augmentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC;sFACkF;IAClF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8EAA8E;IAC9E,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;oFACgF;IAChF,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC/C;uEACmE;IACnE,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC3C,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC;AAED,OAAO,QAAQ,mBAAmB,CAAC;IACjC,UAAU,iBAAiB;QACzB;;;;;;;WAOG;QACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;KACjC;CACF"}

package/dist/scope-augmentation.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview RunScope augmentation for simulation.
+ *
+ * D7 (tool subscopes via module augmentation, per the RunScope/
+ * Registry architecture): tool-specific concerns nest under the
+ * tool's name on `RunScope` and
+ * are added via TypeScript module augmentation from the tool's own
+ * package. Core never imports simulation-shaped types — the layer rule
+ * stays intact (`core ← contracts ← {simulation, ...}`).
+ *
+ * Two singletons used to hang off this package as module-level state:
+ *
+ *   - `scenarioRegistry`                — per-process scenario registry.
+ *   - `defaultSimulationRecipeRegistry` — per-process recipe registry.
+ *
+ * Both are now per-RunScope. The simulation tool's `contributeScope` hook
+ * (in `tool.ts`) instantiates fresh registries and attaches them to
+ * `scope.simulation` once per CLI invocation. Tools and library code
+ * read via `currentScope()?.simulation?.{scenarios,recipes}`.
+ *
+ * The `simulation` slot is intentionally optional and mutable (no
+ * `readonly`) on the augmented interface: the kernel doesn't construct
+ * it, and only the simulation tool's `contributeScope` writes to it during
+ * scope construction. A run that doesn't load the simulation tool
+ * carries no `scope.simulation`, and reads return `undefined`.
+ */
+export {};
+//# sourceMappingURL=scope-augmentation.js.map

package/dist/scope-augmentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-augmentation.js","sourceRoot":"","sources":["../src/scope-augmentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/dist/tool.d.ts

@@ -0,0 +1,21 @@
+/**
+ * simulationTool — simulation as a Tool plugin.
+ *
+ * Owns the `sim` subcommand. The Commander wiring is no longer hand-rolled:
+ * the tool exports a
+ * declarative {@link CommandSpec} (`simCommand`) and the host's
+ * `mountCommandSpec` mounts it (name/description/aliases, the ADR-0021 common
+ * flags, the `--recipe` option) and owns the parse→handler→error→exit pipeline.
+ * This file owns only the sim runner — the `runSim` handler below — which keeps
+ * the JSON/Ink dispatch, cloud egress, and report auto-open exactly as the
+ * old `register()` action body did (byte-identical behaviour).
+ */
+import './scope-augmentation.js';
+import type { Tool } from '@opensip-cli/core';
+/**
+ * Per-tool contract version (ADR-0047).
+ */
+export declare const SIMULATION_CONTRACT_VERSION = "1.0.0";
+export declare const SIMULATION_STABLE_ID = "715d32c2-692c-4ed4-985b-a35deaf186aa";
+export declare const simulationTool: Tool;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwBH,OAAO,yBAAyB,CAAC;AAIjC,OAAO,KAAK,EAIV,IAAI,EAIL,MAAM,mBAAmB,CAAC;AAoU3B;;GAEG;AACH,eAAO,MAAM,2BAA2B,UAAU,CAAC;AAEnD,eAAO,MAAM,oBAAoB,yCAAyC,CAAC;AAE3E,eAAO,MAAM,cAAc,EAAE,IAuC5B,CAAC"}