@jawache/flow 0.2.1 → 0.3.0

package/dist/types/adapter/claude.d.ts

@@ -1,5 +1,6 @@
 import { type ExecResult, type FlowConfig, type LoadResult, type Grammar, type Settings, type World } from "../language/domain.ts";
-import { type CallRecord, type Change, type Delta, type HookEvent, type HookPayload, type HookResult } from "./domain.ts";
+import { type AgentOf } from "../engine/domain.ts";
+import { type CommitScope, type CallRecord, type Change, type Delta, type HookEvent, type HookPayload, type HookResult } from "./domain.ts";
 /**
  * Run one command the way a check means it — through a shell, in the repo, hermetically.
  *
@@ -13,7 +14,7 @@ import { type CallRecord, type Change, type Delta, type HookEvent, type HookPayl
  * installed refuses the commit instead of passing it. bash answers 127 itself; the only case left
  * is bash being unspawnable, which is the same fact one level up and is answered the same way.
  */
-export declare function runCommand(command: string, root: string): ExecResult;
+export declare function runCommand(command: string, root: string, env?: Record<string, string | undefined>): ExecResult;
 /** A file's text, or null when it is not there / not readable. */
 export declare function readText(root: string, path: string): string | null;
 /**
@@ -52,14 +53,14 @@ export declare function currentBranch(root: string): string | null;
  * who is here — and a rule that fires at the gate for a wearer status never showed is the exact
  * surprise the marker exists to prevent.
  *
- * `agent` is null when the marker is missing, stale or malformed, and then the wearer wears NOTHING
- * rather than a guess: there is no transcript and no sidecar out here, so the stored verdict is the
- * only truthful answer there can be.
+ * `who` is null when the marker is missing, stale or malformed, and then the wearer wears NOTHING
+ * rather than a guess: there is no transcript and no hook message out here, so the stored verdict is
+ * the only truthful answer there can be.
  */
 export declare function wearer(root: string): {
     readonly branch: string | null;
     readonly session: string;
-    readonly agent: string | null;
+    readonly who: AgentOf | null;
     readonly wearing: readonly string[];
 };
 /**
@@ -76,7 +77,8 @@ export declare function takeSnapshot(root: string, key: string, include: readonl
 }): void;
 /**
  * WHAT THE CALL CHANGED: the tree now against the tree its snapshot recorded, path by path, with
- * the content either side. The before-snapshot is kept — a revert reads from it — until `forget`.
+ * the content either side, less each path git put there (see `authored`). The before-snapshot is
+ * kept — a revert reads from it — until `forget`.
  */
 export declare function observeDelta(root: string, key: string, include: readonly string[]): Delta & {
     readonly before?: string;
@@ -115,10 +117,10 @@ export declare function projectRoot(cwd: string): string;
  * once in the host's settings and fire in every repo the agent visits, so a missing config is the
  * ordinary case and blocking on it would make flow unusable the moment it was installed.
  *
- * `broken` is the opposite fact and gets the opposite answer: a config file that is THERE and will
- * not even import is a guard that cannot run, which is what fail-loud exists for. (A config that
- * imports and then will not load is the engine's own path — `load.ok === false` — and refuses with
- * the same shape from inside `guard`.)
+ * `broken` is the opposite fact and must never be silent: a config file that is THERE and will
+ * not even import is a guard that cannot run. The hook rail hands it to `whileBroken`, which lets
+ * every call through with the load error, and the commit gate refuses. (A config that imports and
+ * then will not load — `load.ok === false` — is the same fact and gets the same two answers.)
  */
 export type Regime = {
     readonly kind: "none";
@@ -165,10 +167,10 @@ export declare function runHook(hook: HookEvent, payload: HookPayload, root: str
  * WHO IT IS comes from the marker the PreToolUse rail left — session AND agent — so a commit's rows
  * land in the session that caused them and an actor-scoped rule fires at this moment as honestly as
  * at any other. The classification itself is never re-derived here: there is no transcript and no
- * sidecar outside a session, so the STORED verdict is the only truthful answer, and a fresh commit
+ * hook message outside a session, so the STORED verdict is the only truthful answer, and a fresh commit
  * on a stale or absent marker wears nothing rather than wearing a guess.
  */
-export declare function runCommit(root: string, files: readonly string[]): Promise<HookResult>;
+export declare function runCommit(root: string, scope: CommitScope): Promise<HookResult>;
 /** What came in on stdin: a payload, or which of the two ways reading it failed. */
 export type PayloadRead = {
     readonly ok: true;
@@ -206,5 +208,11 @@ export declare function readPayload(): PayloadRead;
  * is silence rather than a usage message in front of the model.
  */
 export declare function hookEntry(event: string, cwd: string): Promise<HookResult>;
-/** The git gate, end to end. Paths arrive repo-relative from git; a stray absolute one is folded. */
-export declare function commitEntry(files: readonly string[], cwd: string): Promise<HookResult>;
+/**
+ * The git gate, end to end — `flow hook commit`, or `flow hook commit --all` for the whole tree.
+ *
+ * It takes no file list: git is asked. `flow commit <files…>`, the name an older hook still calls,
+ * arrives here with `legacy` set and its list is dropped, because git's answer is the only list — a
+ * second source of the staged set is two answers that can disagree.
+ */
+export declare function commitEntry(args: readonly string[], cwd: string, legacy?: boolean): Promise<HookResult>;