@manyoars/oars 0.3.0 → 0.4.1

package/dist/sessions/pool-command.d.ts

@@ -1,16 +1,49 @@
 import type { Outcome, RunDeps } from '../cli.js';
-import { type Outgoing } from './pool-print.js';
+import { CliError } from '../errors.js';
+import { Masker, type Outgoing } from './pool-print.js';
+import { isObject, loadSignIns, textIn, type SignIn } from './pool-replica.js';
+import { type SessionsRuntime } from './store.js';
+import { type Git } from './survival.js';
+export declare const DEPOSIT = "pool-deposit";
 export declare const POOL_PROVIDERS: readonly ["github", "google"];
-/** `--server`, else `OARS_POOL_URL`; never a default. A token and a session's shape cross this connection, so plain http goes only to this machine. */
+export { isObject, loadSignIns, textIn };
+/** The Many Oars pool, used when neither `--server` nor `OARS_POOL_URL` names another. */
+export declare const DEFAULT_POOL_URL = "https://pool.manyoars.com";
+/** `--server`, else `OARS_POOL_URL`, else the Many Oars pool. A token and a session's shape cross this connection, so plain http goes only to this machine. */
 export declare const poolServer: (env: NodeJS.ProcessEnv, step: string, named?: string) => string;
+export declare const runtimeOf: (deps: RunDeps) => SessionsRuntime;
+export declare const signedIn: (deps: RunDeps, storeDir: string, server: string, step: string) => Promise<SignIn>;
 export interface Reply {
     status: number;
     body: unknown;
     headers: Headers;
 }
-/** How a request leaves this machine. The command line passes none and so sends no batch; the lock in `deposit --send` is tested with one. */
+interface Call {
+    body?: unknown;
+    /** A body already serialized, sent as it is: a batch from the outbox, whose bytes were hashed and printed. */
+    bytes?: string;
+    token?: string;
+    /** One part of a batch sent in several: its position (from 1), how many there are, and the SHA-256 of the whole batch, which is what keeps the parts one deposit. */
+    part?: {
+        index: number;
+        count: number;
+        batch: string;
+    };
+    /** The ETag of the bundle already kept, so the pool can answer 304 with no bundle. */
+    ifNoneMatch?: string;
+    /** Set for a command that prints what it sends: the print comes first, with these secrets masked. */
+    show?: Masker;
+    /** A raw part is a PUT of bytes that are not JSON; every other call is a GET, or a POST when it has a body. */
+    method?: 'PUT';
+    type?: string;
+    /** Headers beyond the usual ones (the raw routes state their redaction and capture versions, and the raw consent). */
+    extra?: Array<[string, string]>;
+}
+/** How a request leaves this machine. The command line passes none, so a send goes over the network (`networkSender`); a test passes one to read what would leave. */
 export type Sender = (request: Outgoing) => Promise<Reply>;
-/** The sender a real send would use: the request goes out over the network as built. The command line does not pass it (sending waits on the covenant); the loopback test does, to read what reaches the socket. */
+/** One call to the pool. A redirect is an error: it could carry a batch or a token somewhere the checks on the named server never saw. */
+export declare const ask: (deps: RunDeps, step: string, server: string, path: string, init: Call, via?: Sender) => Promise<Reply>;
+/** The sender `deposit --send` uses when none is given: the request goes out over the network as built. The loopback test passes it to read what reaches the socket. */
 export declare const networkSender: (deps: RunDeps, step: string) => Sender;
 /**
  * `oars pool login` (spec Section 1.4): the device flow runs here, against the provider, and the pool sees only the provider's token, once, and answers its own credential. Every request prints before it is sent, with the device code, the provider's token,
@@ -20,6 +53,27 @@ export declare const poolLogin: (deps: RunDeps, options: {
     server?: string | undefined;
     provider?: string | undefined;
 }) => Promise<Outcome>;
+export declare const vocabularyExpired: (deps: RunDeps) => CliError | undefined;
+/** One batch to the pool: a batch past one request's bytes goes in parts, in order, each answered 202 until the last completes the deposit with 201. A part sent again is harmless, so the retry covers every part alike. */
+export declare const postBatch: (deps: RunDeps, options: {
+    server: string;
+    token: string;
+    bytes: string;
+    hash: string;
+    via: Sender;
+}) => Promise<void>;
+/**
+ * One redacted raw copy to the pool: its parts by PUT, then the completion, which the pool checks against the SHA-256 in the path. Every request states the redaction and capture versions and that the person said yes to the raw prompt;
+ * the caller sends only for a person who did. A part sent again replaces itself, and one for an object that stands writes nothing, so a copy that failed halfway is sent again whole.
+ */
+export declare const postRaw: (deps: RunDeps, options: {
+    server: string;
+    token: string;
+    hash: string;
+    body: string;
+    bytes: number;
+    via: Sender;
+}) => Promise<void>;
 /**
  * `oars pool deposit`: every session in the store that passes both session gates is built into a canonical batch in the outbox, and the command stops: nothing is sent. The gates run before any projection does: the folder
  * allowlist, then the exclusion check. A session that fails either, or has no raw to scan, is counted and never built. A session is built only once it has ended: no transcript of it, main or subagent, has gained a line (the later of its capture
@@ -30,8 +84,9 @@ export declare const poolDeposit: (deps: RunDeps, options: {
     acceptCovenant?: string | undefined;
     send?: string | undefined;
     via?: Sender | undefined;
+    git?: Git | undefined;
 }) => Promise<Outcome>;
-/** `oars pool outbox`: prints each batch as it would be sent, the request line and every header included, with the bearer credential as its size and nothing else masked, then its SHA-256, and records that it was shown. `--explain` adds each field's rule. */
+/** `oars pool outbox`: prints each batch as it would be sent (a batch past one request prints each part's request, in order), the request line and every header included, with the bearer credential as its size and nothing else masked, then its SHA-256, and records that it was shown. `--explain` adds each field's rule. */
 export declare const poolOutbox: (deps: RunDeps, options: {
     server?: string | undefined;
     explain?: boolean | undefined;
@@ -42,3 +97,19 @@ export declare const poolFetch: (deps: RunDeps, options: {
     harness?: string | undefined;
     harnessVersion: string;
 }) => Promise<Outcome>;
+/** The raw prompt, in plain words: shown by `oars pool raw` until it is answered, and what the nightly send relies on. Redaction is best effort and the text says so. */
+export declare const RAW_PROMPT: string;
+/** `oars pool raw`: shows the raw prompt and the answer so far; `--consent yes|no` records the answer; `--folder <entry> --mode all|skeleton|off` sets what one folder may send. */
+export declare const poolRaw: (deps: RunDeps, options: {
+    consent?: string | undefined;
+    folder?: string | undefined;
+    mode?: string | undefined;
+}) => Promise<Outcome>;
+/**
+ * `oars pool coverage`: the two bands only the operator can state, kept on this machine and read at deposit. They are what the pool can say about whom a deposit covers, not a filter; `unknown` states nothing.
+ * With no flag it prints what is set.
+ */
+export declare const poolCoverage: (deps: RunDeps, options: {
+    orgSize?: string | undefined;
+    repoVisibility?: string | undefined;
+}) => Promise<Outcome>;