@smthrs/std 0.0.0-stage → 1.0.0-rc.12

package/dist/esm/Bash.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Bash flow declaration and portable handler.
+ *
+ * Two ways in, and the difference is where the payload is parsed. `command` is
+ * a line for the platform shell, exactly as before. `script` is program text
+ * delivered to an interpreter on standard input, as data: nothing quotes it,
+ * escapes it, or terminates it with a heredoc marker, so the class of failure
+ * that produced `docker exec c bash -lc '…python - <<EOF…'` cannot occur. Its
+ * `args` reach the script as arguments rather than as interpolated text.
+ *
+ * `container` names a container the host knows how to reach, and the argv is
+ * built by the injected {@link Container} transport rather than typed by the
+ * caller. A host that binds no transport refuses such a call by saying so; the
+ * requirement is optional here precisely so a host without containers is not
+ * forced to declare one.
+ *
+ * @since 1.0.0
+ */
+import type * as ChildProcessSpawner from "@smthrs/kernel/ChildProcessSpawner";
+import * as Path from "@smthrs/kernel/Path";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as StdError from "./StdError.ts";
+/**
+ * Registry name for the bash flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export declare const name = "bash";
+/**
+ * Model-facing description of the bash flow.
+ *
+ * Capped at 200 characters and read every frame, which is why the
+ * invalid-probe contract is not restated here: the cell contract teaches it
+ * once, and a result that has one explains itself.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export declare const description = "Run a shell command, or an interpreter over a script passed as data instead of quoted into a line. container routes it through the host's container transport. mode:hermetic pre-checks path tokens.";
+/**
+ * Default command timeout in milliseconds.
+ *
+ * Ten minutes lets full builds and test suites finish while ensuring a stalled
+ * process eventually releases the flow.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const DEFAULT_TIMEOUT_MS = 600000;
+/**
+ * Input schema for the bash flow.
+ *
+ * The mode named `hermetic` requires explicit read and write envelopes for a
+ * lexical pre-check; it does not by itself confine the process. Unhermetic mode
+ * deliberately omits those declarations so the distinction stays visible in
+ * the input shape.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Input: Schema.Union<readonly [Schema.Struct<{
+    readonly mode: Schema.Literal<"hermetic">;
+    readonly command: Schema.optional<Schema.String>;
+    readonly script: Schema.optional<Schema.String>;
+    readonly interpreter: Schema.optional<Schema.String>;
+    readonly args: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly stdin: Schema.optional<Schema.String>;
+    readonly container: Schema.optional<Schema.String>;
+    readonly reads: Schema.$Array<Schema.NonEmptyString>;
+    readonly writes: Schema.$Array<Schema.NonEmptyString>;
+    readonly cwd: Schema.optional<Schema.String>;
+    readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly timeoutMs: Schema.optional<Schema.Number>;
+}>, Schema.Struct<{
+    readonly mode: Schema.withDecodingDefaultKey<Schema.optionalKey<Schema.Literal<"unhermetic">>, never>;
+    readonly command: Schema.optional<Schema.String>;
+    readonly script: Schema.optional<Schema.String>;
+    readonly interpreter: Schema.optional<Schema.String>;
+    readonly args: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly stdin: Schema.optional<Schema.String>;
+    readonly container: Schema.optional<Schema.String>;
+    readonly cwd: Schema.optional<Schema.String>;
+    readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly timeoutMs: Schema.optional<Schema.Number>;
+}>]>;
+/**
+ * Decoded input accepted by the bash handler.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type;
+/**
+ * Output schema for the bash flow.
+ *
+ * `invalidProbe` is present when the shell itself refused to start the
+ * command, which its exit code says outright: 127 for a program it could not
+ * find, 126 for one it could not execute. Only that. Reading a runner's own
+ * wording is a judgment rather than a fact, and `Probe.classify` makes it with
+ * Jev for the `test` flow, whose caller is asking about a suite; a shell call
+ * is any command at all and stays free of the gateway. See `Probe`.
+ *
+ * The `<stream>Truncated` flags are a wire convention, not a display detail.
+ * A truncated capture is a fragment of what the process printed, and the
+ * harness reads these flags to refuse a later write of those exact bytes —
+ * `@smthrs/harness/TruncatedOutput` is the consuming half. Renaming a flag, or
+ * dropping it when the capture is cut, disarms that guard silently.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Output: Schema.Struct<{
+    readonly exitCode: Schema.Number;
+    readonly stdout: Schema.String;
+    readonly stderr: Schema.String;
+    readonly stdoutTruncated: Schema.Boolean;
+    readonly stderrTruncated: Schema.Boolean;
+    readonly stdoutDroppedBytes: Schema.Number;
+    readonly stderrDroppedBytes: Schema.Number;
+    readonly invalidProbe: Schema.optional<Schema.Struct<{
+        readonly reason: Schema.Literals<readonly ["unknown-command", "unknown-test", "unknown-path", "unknown-module", "unknown-environment"]>;
+        readonly evidence: Schema.String;
+        readonly message: Schema.String;
+    }>>;
+    readonly mutated: Schema.optional<Schema.Boolean>;
+}>;
+/**
+ * Decoded output returned by the bash handler.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type;
+/**
+ * The text of a stream cut to its start and end: the start, one line naming
+ * the bytes omitted between them, and the end. A host that captures output
+ * itself, such as a terminal behind {@link inTerminal}, cuts with this so every
+ * {@link Output} reads the same.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.5
+ */
+export declare const elideMiddle: (start: string, droppedBytes: number, end: string) => string;
+/**
+ * Static conservative effect envelope for the bash flow.
+ *
+ * The declaration is the registry-time worst case because the mode is not
+ * known until an invocation is decoded.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effects: import("@smthrs/plan/Effects").Declaration;
+/**
+ * Narrows the effect envelope for a decoded invocation.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export declare const effectsFor: (input: Input) => import("@smthrs/plan/Effects").Declaration;
+/**
+ * Capabilities required by the bash flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export declare const capabilities: string[];
+/**
+ * Declaration-only bash flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export declare const flow: {
+    readonly name: "bash";
+    readonly description: "Run a shell command, or an interpreter over a script passed as data instead of quoted into a line. container routes it through the host's container transport. mode:hermetic pre-checks path tokens.";
+    readonly input: Schema.Union<readonly [Schema.Struct<{
+        readonly mode: Schema.Literal<"hermetic">;
+        readonly command: Schema.optional<Schema.String>;
+        readonly script: Schema.optional<Schema.String>;
+        readonly interpreter: Schema.optional<Schema.String>;
+        readonly args: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly stdin: Schema.optional<Schema.String>;
+        readonly container: Schema.optional<Schema.String>;
+        readonly reads: Schema.$Array<Schema.NonEmptyString>;
+        readonly writes: Schema.$Array<Schema.NonEmptyString>;
+        readonly cwd: Schema.optional<Schema.String>;
+        readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+        readonly timeoutMs: Schema.optional<Schema.Number>;
+    }>, Schema.Struct<{
+        readonly mode: Schema.withDecodingDefaultKey<Schema.optionalKey<Schema.Literal<"unhermetic">>, never>;
+        readonly command: Schema.optional<Schema.String>;
+        readonly script: Schema.optional<Schema.String>;
+        readonly interpreter: Schema.optional<Schema.String>;
+        readonly args: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly stdin: Schema.optional<Schema.String>;
+        readonly container: Schema.optional<Schema.String>;
+        readonly cwd: Schema.optional<Schema.String>;
+        readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+        readonly timeoutMs: Schema.optional<Schema.Number>;
+    }>]>;
+    readonly output: Schema.Struct<{
+        readonly exitCode: Schema.Number;
+        readonly stdout: Schema.String;
+        readonly stderr: Schema.String;
+        readonly stdoutTruncated: Schema.Boolean;
+        readonly stderrTruncated: Schema.Boolean;
+        readonly stdoutDroppedBytes: Schema.Number;
+        readonly stderrDroppedBytes: Schema.Number;
+        readonly invalidProbe: Schema.optional<Schema.Struct<{
+            readonly reason: Schema.Literals<readonly ["unknown-command", "unknown-test", "unknown-path", "unknown-module", "unknown-environment"]>;
+            readonly evidence: Schema.String;
+            readonly message: Schema.String;
+        }>>;
+        readonly mutated: Schema.optional<Schema.Boolean>;
+    }>;
+    readonly capabilities: string[];
+    readonly effects: import("@smthrs/plan/Effects").Declaration;
+};
+/**
+ * How one recorded call to this flow reads: the verb for each settlement, the
+ * input field that is its subject, and the measured output fields a one-line
+ * summary may count.
+ *
+ * Display metadata only, governed by `@smthrs/registry`
+ * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export declare const presentation: {
+    readonly verb: {
+        readonly pending: "running";
+        readonly success: "ran";
+        readonly failure: "failed to run";
+    };
+    readonly subject: "command";
+    readonly result: "command";
+};
+/**
+ * Executes a shell command through the permission-aware kernel service.
+ *
+ * Non-zero exit codes remain successful values. Only timeout, host, permission,
+ * and declared-envelope pre-check failures use the typed error channel.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const run: (input: {
+    readonly mode: "hermetic";
+    readonly writes: readonly string[];
+    readonly reads: readonly string[];
+    readonly cwd?: string | undefined;
+    readonly env?: {
+        readonly [x: string]: string;
+    } | undefined;
+    readonly stdin?: string | undefined;
+    readonly command?: string | undefined;
+    readonly args?: readonly string[] | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly script?: string | undefined;
+    readonly interpreter?: string | undefined;
+    readonly container?: string | undefined;
+} | {
+    readonly mode?: "unhermetic";
+    readonly cwd?: string | undefined;
+    readonly env?: {
+        readonly [x: string]: string;
+    } | undefined;
+    readonly stdin?: string | undefined;
+    readonly command?: string | undefined;
+    readonly args?: readonly string[] | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly script?: string | undefined;
+    readonly interpreter?: string | undefined;
+    readonly container?: string | undefined;
+}) => Effect.Effect<{
+    readonly stderr: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stdoutTruncated: boolean;
+    readonly stderrTruncated: boolean;
+    readonly stdoutDroppedBytes: number;
+    readonly stderrDroppedBytes: number;
+    readonly invalidProbe?: {
+        readonly reason: "unknown-command" | "unknown-test" | "unknown-path" | "unknown-module" | "unknown-environment";
+        readonly evidence: string;
+        readonly message: string;
+    } | undefined;
+    readonly mutated?: boolean | undefined;
+}, StdError.StdError, ChildProcessSpawner.ChildProcessSpawner | import("effect/Path").Path>;
+/**
+ * What one call runs, after planning and before any transport: the program,
+ * its arguments (absent for a shell command line), standard input, the
+ * caller's environment, and the logical invocation as a person reads it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Invocation {
+    readonly file: string;
+    readonly args: ReadonlyArray<string> | undefined;
+    readonly stdin: string | undefined;
+    readonly env: Record<string, string> | undefined;
+    readonly quoted: string;
+}
+/**
+ * The invocation `input` names, or the typed refusal explaining why it names
+ * none. The same plan {@link run} spawns; a terminal provider runs it instead.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const invocation: (input: Input) => Invocation | StdError.StdError;
+/**
+ * {@link run}'s contract through a registered terminal (T-TRM-05): the same
+ * plan, hermetic pre-check, bounded output and diagnostics refresh, with
+ * execution supplied by `execute` instead of a spawn on this host. A terminal
+ * has no container transport, so a containerised call is refused before it
+ * reaches `execute`.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export declare const inTerminal: <R>(execute: (input: Input) => Effect.Effect<Output, StdError.StdError, R>) => (input: {
+    readonly mode: "hermetic";
+    readonly writes: readonly string[];
+    readonly reads: readonly string[];
+    readonly cwd?: string | undefined;
+    readonly env?: {
+        readonly [x: string]: string;
+    } | undefined;
+    readonly stdin?: string | undefined;
+    readonly command?: string | undefined;
+    readonly args?: readonly string[] | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly script?: string | undefined;
+    readonly interpreter?: string | undefined;
+    readonly container?: string | undefined;
+} | {
+    readonly mode?: "unhermetic";
+    readonly cwd?: string | undefined;
+    readonly env?: {
+        readonly [x: string]: string;
+    } | undefined;
+    readonly stdin?: string | undefined;
+    readonly command?: string | undefined;
+    readonly args?: readonly string[] | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly script?: string | undefined;
+    readonly interpreter?: string | undefined;
+    readonly container?: string | undefined;
+}) => Effect.Effect<{
+    readonly stderr: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stdoutTruncated: boolean;
+    readonly stderrTruncated: boolean;
+    readonly stdoutDroppedBytes: number;
+    readonly stderrDroppedBytes: number;
+    readonly invalidProbe?: {
+        readonly reason: "unknown-command" | "unknown-test" | "unknown-path" | "unknown-module" | "unknown-environment";
+        readonly evidence: string;
+        readonly message: string;
+    } | undefined;
+    readonly mutated?: boolean | undefined;
+}, StdError.StdError, import("effect/Path").Path | R>;
+/**
+ * The refusal a sealed host answers a call outside its container with.
+ *
+ * @category errors
+ * @since 1.0.0-rc.1
+ */
+export declare const outsideContainer: (sealedTo: string, requested: string | undefined) => StdError.StdError;
+/**
+ * {@link run}, sealed to one container.
+ *
+ * A host that must not be reachable from the cell (a benchmark host holding
+ * other tasks' tests and reference solutions, say) binds this instead of
+ * {@link run}: a call naming `sealedTo` runs as usual, and every other call,
+ * including one with no container that would run on the host, fails with
+ * `outside_container` before anything is spawned.
+ *
+ * @category handlers
+ * @since 1.0.0-rc.1
+ */
+export declare const sealed: (sealedTo: string) => (input: Input) => Effect.Effect<Output, StdError.StdError, ChildProcessSpawner.ChildProcessSpawner | Path.Path>;
+//# sourceMappingURL=Bash.d.ts.map

package/dist/esm/Bash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Bash.d.ts","sourceRoot":"","sources":["../../src/Bash.ts"],"names":[],"mappings":"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"}