@jawache/flow 0.1.0

package/dist/types/engine/state.d.ts

@@ -0,0 +1,104 @@
+import type { Category, SessionFacts } from "../language/domain.ts";
+import { type Attribution, type Identity, type RecordedStep, type Recording, type Row, type SessionRows, type SessionState } from "./domain.ts";
+/**
+ * Create `.flow/`, self-ignored, and answer whether it is there.
+ *
+ * The `.gitignore` is written by whoever gets there first rather than by an install step, because
+ * the first writer is usually a hook: a repo whose guard ran before anyone typed a flow command
+ * would otherwise find a directory of telemetry sitting in `git status`. It is idempotent and it
+ * covers itself — `*` ignores the ignore file too.
+ */
+export declare function ensureFlowDir(root: string): boolean;
+/**
+ * Is the guard switched off here?
+ *
+ * Fail-safe in the ON direction, deliberately: any error reading the marker is treated as "on", so
+ * a filesystem hiccup can never silence a gate. The only thing that turns flow off is a file that
+ * is definitely there.
+ */
+export declare function isOff(root: string): boolean;
+/** This session × agent's stored state. Absent, unreadable or corrupt → nothing known. */
+export declare function loadState(root: string, session: string, agent: string): SessionState;
+/** Store it. Dropped silently on any error — see the note at the top of this file. */
+export declare function saveState(root: string, session: string, agent: string, state: SessionState): boolean;
+/**
+ * Who this session × agent is, read once and then remembered — the sticky verdict, tied to disk.
+ *
+ * The two halves are proved separately next door and here; this is the ONE place they meet, so
+ * there is no second spelling of "look it up, and if it was fresh, write it down". A caller that
+ * assembled it by hand would eventually be a caller that forgot the write, and a classification
+ * that silently re-derives every hook is the flapping identity the sticky rule exists to prevent.
+ */
+export declare function stickyIdentity(root: string, session: string, agent: string, facts: SessionFacts, categories: readonly Category[]): Identity;
+export interface LogContext {
+    readonly root: string;
+    readonly session: string;
+    /** The branch this worktree has out, for the stream's meta row. The adapter knows it; this does not. */
+    readonly branch: string | null;
+    /** Injected, because a clock inside a decision is a decision nobody can test. */
+    readonly now?: () => Date;
+}
+/**
+ * Append rows to this session's stream, stamping each with the time and the next event index.
+ *
+ * The FIRST write creates the file with its meta row, which is the fail-loud "armed" marker — a
+ * present-but-quiet log and a missing one are different facts, and a reader that cannot tell them
+ * apart reports an armed guard as an absent one.
+ */
+export declare function appendRows(ctx: LogContext, rows: readonly Row[]): boolean;
+/** Every row in one stream file, in the order it was written. Unreadable → nothing. */
+export declare function readRowsFile(file: string): Row[];
+/** Every row of one session's stream. */
+export declare function readRows(root: string, session: string): Row[];
+/**
+ * Every session that has a stream here, oldest file first.
+ *
+ * `commit` is included: its rows still count toward what an entry has done, and only the SESSION
+ * count excludes it — a shared file is not a chat, and the metrics say so where it matters.
+ */
+export declare function sessionIds(root: string): string[];
+/** The whole recorded history of a repo — every stream, read. */
+export declare function readHistory(root: string): SessionRows[];
+/**
+ * The conversations already dealt with. Existence is the fact; a marker means READ, never merely
+ * seen. Unreadable or absent is an empty set, which re-offers history — the harmless direction.
+ */
+export declare function alreadyRead(root: string): Set<string>;
+/**
+ * Mark conversations read, so the backlog starts after them next time.
+ *
+ * Only ANALYSED ids are ever passed — never the deferred ones — which is what keeps "a marker
+ * means read" true and stops a capped run declaring skipped history done. Bookkeeping, so it
+ * answers with a count rather than throwing, like every other writer in this file.
+ */
+export declare function markRead(root: string, ids: readonly string[]): number;
+/**
+ * Is this repo capturing replayable recordings?
+ *
+ * Fail-safe in the OFF direction, which is the opposite of the kill switch's and right for the
+ * opposite reason: a filesystem hiccup must never silence a gate, and it must never start writing
+ * a megabyte of transcript nobody asked for either.
+ */
+export declare function isRecording(root: string): boolean;
+/**
+ * Append steps to this session's recording. Best-effort, like every other writer in this file.
+ *
+ * The header is written by whoever gets there first, exactly as the log's meta row is — the first
+ * writer is a hook, and a recording that only became valid once somebody ran a command would miss
+ * the opening of every session.
+ */
+export declare function appendSteps(root: string, session: string, steps: readonly RecordedStep[]): boolean;
+/** One recording, read off disk. A file that is not there is an empty one, never an error. */
+export declare function loadRecording(file: string): Recording;
+/**
+ * Leave the live session × agent where the commit gate can find it.
+ *
+ * The gate is spawned by git, outside any session, so it cannot know which chat a commit belongs to
+ * — nor which of that chat's actors was working, which is a second question and the one that
+ * decides whether an actor-scoped rule can fire at the commit moment. Written on every edit, so the
+ * marker tracks the session's latest activity and its timestamp is what `attribution` judges
+ * freshness by.
+ */
+export declare function writeMarker(root: string, session: string, agent: string, branch: string | null, at?: Date): boolean;
+/** Who this worktree's commit belongs to — the fresh marker's session × agent, or `commit`. */
+export declare function commitAttribution(root: string, branch: string | null, nowMs?: number): Attribution;

package/dist/types/errors.d.ts

@@ -0,0 +1,14 @@
+import { type Refusal, type LoadResult, type LoadedEntry } from "./language/domain.ts";
+/**
+ * The config would not load. Every refusal rides along, each naming the entry it is about.
+ *
+ * The WORDING is `refusalText`'s, not this file's. The engine refuses a gated moment with the same
+ * block of text, so a person who has read one has read the other — and a second copy of the
+ * sentence here is how the exception and the block would come to disagree.
+ */
+export declare class FlowConfigError extends Error {
+    readonly refusals: readonly Refusal[];
+    constructor(refusals: readonly Refusal[]);
+}
+/** The loaded entries, or the error carrying every reason there are none. */
+export declare function entriesOrThrow(result: LoadResult): readonly LoadedEntry[];

package/dist/types/flow.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/glob.d.ts

@@ -0,0 +1,53 @@
+export declare function escapeRe(s: string): string;
+/** One piece of a glob. The whole dialect: `**` · `*` · `?` · `{a,b}` · literal text. */
+export type GlobToken = {
+    readonly kind: "literal";
+    readonly text: string;
+}
+/** `*` — anything within one path segment. */
+ | {
+    readonly kind: "star";
+}
+/** `**` — anything, across segments. Consumes a `/` immediately after it. */
+ | {
+    readonly kind: "globstar";
+}
+/** `?` — exactly one character, not a separator. */
+ | {
+    readonly kind: "single";
+}
+/** `{a,b}` — one of these literals. */
+ | {
+    readonly kind: "options";
+    readonly options: readonly string[];
+};
+/**
+ * Read a glob as tokens.
+ *
+ * An UNCLOSED `{` is a literal brace rather than an error or a swallowed rest-of-string. It cannot
+ * throw (this is a pure home) and refusing would mean every caller needs a failure path for a glob
+ * that is almost certainly just a brace in a filename; reading it literally is what the shell does
+ * too.
+ */
+export declare function tokenizeGlob(glob: string): GlobToken[];
+/**
+ * One token → its regex source.
+ *
+ * Every construct emits something with NO quantifier of its own beyond a bare `.*` or `[^/]*`, and
+ * an alternation carries none at all — which is what keeps the output inside dependency-cruiser's
+ * ReDoS guard (it rejects grouped and nested quantifiers, never a plain group). The two emitters
+ * differ only in how they anchor the whole string, never in what a token means.
+ */
+export declare function globTokenToRegExp(token: GlobToken): string;
+/** A glob → an anchored RegExp. Supports `**` (across /), `*` (within a segment), `?`, `{a,b}`. */
+export declare function globToRegExp(glob: string): RegExp;
+export declare function matchGlob(path: string, glob: string): boolean;
+export declare function matchAny(path: string, globs: readonly string[] | null | undefined): boolean;
+export interface FileParts {
+    dir: string;
+    base: string;
+    name: string;
+    path: string;
+}
+export declare function fileParts(file: string): FileParts;
+export declare function expandTemplate(tpl: string, file: string): string;

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+export { guardrail, breadcrumb, type Sentence, type EntrySpec, type GuardrailSpec, type BreadcrumbSpec, type GuardrailSentence, type BreadcrumbSentence, type EntryGroup, type DisabledMark, } from "./language/domain.ts";
+export { definePack, pack, override, defineConfig, type Pack, type PackDefinition, type EntryRef, type RefTarget, type FlowConfig, type Binding, type PackBinding, type OverrideBinding, type ConfigSentence, } from "./language/domain.ts";
+export { defineCheck, type Check, type Ctx, type World, type Verdict, type ExecResult, type TurnAction, type Case, type CaseWorld, type Cases, } from "./language/domain.ts";
+export { defineCategory, type Category, type Classifier, type SessionFacts } from "./language/domain.ts";
+export { astGrep, banCommands, canonicalFiles, changeTogether, commitReason, depcruise, execPasses, jsonInvariant, protectedPath, ranSinceEdit, siblingExists, symbolsInSibling, textBan, type CanonOptions, type ChangeGroup, type Dialect, type DiffAdds, type ForbidEdge, type JsonAssert, type RequireEdge, } from "./checks/domain.ts";
+export { substitutionInProse, SUBSTITUTION_MESSAGE } from "./checks/domain.ts";
+export { commitMessage, gitDirPrefix, gitInvocations, givesReason, quoteArg, tokenizeCommand, type GitInvocation, } from "./checks/domain.ts";
+export { spawnedAs, type SpawnRecipe } from "./engine/domain.ts";
+export { write, command, commit, deletion, turnEnd, session, touch, type Moment, type GuardrailMoment, type BreadcrumbMoment, } from "./language/domain.ts";
+export { loadConfig, refusalText, REFUSAL_CODES, type Refusal, type RefusalCode, type LoadResult, type LoadedEntry, type Settings, } from "./language/domain.ts";
+export { escapeRe } from "./glob.ts";
+export { FlowConfigError, entriesOrThrow } from "./errors.ts";