@jawache/flow 0.1.2 → 0.2.1

package/dist/types/checks/domain.d.ts

@@ -33,9 +33,20 @@ export declare const textBan: (options: {
  * (which is right for a file, where a hit must be able to name its line) every one of those
  * patterns matches nothing, silently: the rule loads, counts, and cannot catch the thing it
  * names.
+ *
+ * WITHOUT ITS HEREDOC BODIES (`elideHeredocs`), by default. A heredoc is text fed to a program,
+ * and a python script or a note that names a banned command is not a use of it: matched whole,
+ * `python3 - <<'PY'` scripts were refused for naming a recipe in a string. Only the bodies go —
+ * the newlines the patterns above span are kept — and a body a shell reads stays, because it is
+ * commands.
+ *
+ * `matchHeredocs: true` matches the whole command instead. A rule about what a command is FED —
+ * the text of a commit message given on stdin, `git commit -F - <<'EOF'` — has to see the body,
+ * and would be blind to that message without it.
  */
 export declare const banCommands: (options: {
     ban: readonly string[];
+    matchHeredocs?: boolean;
 }) => Check;
 /**
  * A `banCommands` pattern for: a command that writes permanent prose, with a BACKTICK inside a
@@ -86,6 +97,24 @@ export declare const SUBSTITUTION_MESSAGE: string;
 export declare const protectedPath: (options: {
     existingOnly?: boolean;
 }) => Check;
+/**
+ * Only the listed categories may change a file: a write or a delete by any other actor is refused.
+ *
+ * It reads `ctx.actor` — the categories the acting session wears, recognised from what the host
+ * wrote about it, never from a claim it made — and nothing about the file. A session wearing none
+ * of `writers` is refused whatever it wrote, and one wearing none at all is refused too: "no
+ * category" is not "every category".
+ *
+ * `.for(…)` on an entry says which actors a RULE applies to; this says which actors may WRITE. Both
+ * read the same categories, and they answer different questions — a rule for a checker says what a
+ * checker may not do, this says that everybody but a builder may not write.
+ *
+ * An empty `writers` is refused at load: it would refuse every change by everyone, which is a
+ * frozen worktree, not a rule about who writes it.
+ */
+export declare const oneWriter: (options: {
+    writers: readonly string[];
+}) => Check;
 /**
  * A file must have a required companion on disk — every `src/domain/**` needs its `.test.ts`.
  *
@@ -241,6 +270,44 @@ export declare const changeTogether: (options: {
  * aimed at a directory called HEAD.
  */
 export declare const GIT_VALUE_OPTS: ReadonlySet<string>;
+/** A heredoc's opener: its delimiter, whether `<<-` strips leading tabs, and where the opener ends. */
+export interface HeredocOpen {
+    readonly delim: string;
+    readonly tabs: boolean;
+    readonly end: number;
+}
+/**
+ * The first heredoc opener anywhere in a line, quoted context or not — the one definition of "this
+ * line carries a heredoc". A here-string (`<<<`) is stepped over whole, so its tail is not read as
+ * one.
+ */
+export declare function firstHeredoc(s: string): HeredocOpen | null;
+/**
+ * Where a `$(` closes, honouring quotes, nesting and any heredoc inside it — a body is text, so an
+ * apostrophe or a `)` in it closes nothing. -1 when it never closes.
+ */
+export declare function closeParen(s: string, from: number): number;
+/** Where a double-quoted run closes — a `"` inside a `$(…)` in it does not close it. -1 when it never does. */
+export declare function dquoteEnd(s: string, from: number): number;
+/**
+ * THE COMMAND LINE WITHOUT ITS HEREDOC BODIES — what a command ban matches unless the rule sets
+ * `matchHeredocs`.
+ *
+ * A heredoc is text fed to a program on its standard input: a python script, a file being written,
+ * a note. The words of a banned command inside it are not a use of that command, and matching
+ * them refused `python3 - <<'PY'` scripts for naming a recipe in a string. Every body is removed
+ * (its terminator line stays, so the opener still ends), whether the delimiter is quoted or not,
+ * and wherever the heredoc sits —
+ * inside a `$(…)` or a quoted argument too. EVERYTHING ELSE IS LEFT AS WRITTEN — newlines
+ * included, because the patterns that police a commit message span them.
+ *
+ * One exception keeps a body: a heredoc fed to a SHELL (`bash`, `sh`, `zsh`, `eval`, or a pipeline
+ * into one), whose body is commands, and a banned one in it will run.
+ *
+ * Best-effort, and it errs toward matching: from a word whose quote never closes, the line is
+ * returned as written, so a ban still sees everything it saw before.
+ */
+export declare function elideHeredocs(command: string): string;
 /**
  * A shell-ish tokeniser: quotes respected (so a commit message mentioning `git commit` is not a
  * second command), operators emitted as their own tokens.
@@ -266,19 +333,6 @@ export interface GitInvocation {
  * operator — so a `git` inside a quoted message or as an argument to something else is not one.
  */
 export declare function gitInvocations(command: string): GitInvocation[] | null;
-/**
- * The body of the first heredoc in the raw command, or null.
- *
- * `git commit -F -` reads its message on stdin, and a QUOTED heredoc is the safe way to write one
- * containing backticks — a form this codebase's own rules push commits toward. The argument scan
- * cannot see it: there is no `-m` token, so a message written that way goes unjudged, and every
- * rule that reads a commit message is inert on it.
- *
- * Deliberately last-resort and deliberately dumb — it runs only when no inline message was found,
- * and reads the FIRST heredoc, because a commit command carrying two is not a shape anyone writes
- * and guessing between them would be worse than the gap.
- */
-export declare function heredocBody(command: string): string | null;
 /**
  * The message a `git commit` in this command line carries, or null when there is no judgeable
  * commit in it at all. Null is the "not our business" answer and every caller passes on it.
@@ -296,7 +350,10 @@ export declare function heredocBody(command: string): string | null;
  *
  *   git commit -m MSG · -mMSG · --message MSG · --message=MSG      judged
  *   git commit -m SUBJECT -m BODY   (repeated, any mix of forms)   judged, joined as git joins them
- *   git commit -F - <<'EOF' … EOF   (any heredoc on the line)      judged, via the heredoc body
+ *   git commit -F - <<'EOF' … EOF   (the commit reads stdin)        judged, via the heredoc body
+ *   python3 - <<'PY' … PY; git commit -F msg.txt                    NOT judged — the heredoc is
+ *                                                                  another command's script, and
+ *                                                                  the message is on disk
  *   git commit -F path/to/file                                     NOT judged — the message is on
  *                                                                  disk, and reading it is a read
  *                                                                  of the world this layer does not

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

@@ -266,8 +266,16 @@ export declare const FLOW_DIR = ".flow";
 export declare const FLOW_GITIGNORE = "# flow's own state \u2014 telemetry and session marks, never committed.\n*\n";
 /** The log schema this build writes, stamped into every session file's first row. */
 export declare const LOG_VERSION = 1;
-/** Every kind a log row may be. Closed — a reader that meets another word has met corruption. */
-export declare const ROW_KINDS: readonly ["meta", "tool", "breadcrumb", "guardrail", "compaction", "run"];
+/**
+ * Every kind a log row may be. Closed — a reader that meets another word has met corruption.
+ *
+ * `read` and `write` are what went ROUND the tool rows: a file a shell command read by name, and a
+ * file a call changed that the call did not name — a heredoc, a `sed -i`, a script. A `tool` row
+ * says a call happened; these say what it did to the tree, so the coverage and lead numbers count
+ * work done through the shell as well as through Edit. `mismatch` is the host's own list of the
+ * files a command changed disagreeing with flow's diff: a fact to read, never an input to a rule.
+ */
+export declare const ROW_KINDS: readonly ["meta", "tool", "breadcrumb", "guardrail", "compaction", "run", "read", "write", "mismatch"];
 export type RowKind = (typeof ROW_KINDS)[number];
 export declare function flowDir(root: string): string;
 /** A session id becomes a filename, so it is held to a filename's charset. */

package/dist/types/index.d.ts

@@ -2,7 +2,7 @@ export { guardrail, breadcrumb, type Sentence, type EntrySpec, type GuardrailSpe
 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, withFaults, faultsOf, 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 Layer, type DiffAdds, type ForbidEdge, type JsonAssert, type RequireEdge, } from "./checks/domain.ts";
+export { astGrep, banCommands, canonicalFiles, changeTogether, commitReason, depcruise, execPasses, jsonInvariant, oneWriter, protectedPath, ranSinceEdit, siblingExists, symbolsInSibling, textBan, type CanonOptions, type ChangeGroup, type Dialect, type Layer, 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";

package/dist/types/language/domain.d.ts

@@ -141,6 +141,12 @@ export interface Ctx {
     readonly staged?: readonly string[] | undefined;
     /** turn-end: what the actor did this turn, in order. */
     readonly turn?: readonly TurnAction[] | undefined;
+    /**
+     * Every moment: the category names that match the session making this change — the categories
+     * some bound entry names, whose recognizer said yes to the host-written evidence about it. Empty
+     * when it matches none, which is not "every category".
+     */
+    readonly actor: readonly string[];
     exec(cmd: string): Promise<ExecResult>;
     readonly fs: {
         read(path: string): Promise<string>;
@@ -263,16 +269,20 @@ export type Case =
 string | {
     readonly command: string;
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 } | {
     readonly path: string;
     readonly content: string;
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 } | {
     readonly staged: readonly string[];
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 } | {
     readonly actions: readonly TurnAction[];
     readonly world?: CaseWorld;
+    readonly actor?: readonly string[];
 };
 /** The cases an entry carries: what must pass it, and what must be blocked by it. */
 export interface Cases {
@@ -538,6 +548,19 @@ export interface Settings {
      * it two ways.
      */
     readonly grammars?: readonly Grammar[];
+    /**
+     * Globs for the IGNORED paths the snapshot records as well. The snapshot is git's view of the
+     * tree — tracked files, and untracked ones git does not ignore — so a shell write to an ignored
+     * file is never seen unless a glob here brings it back. `.env` is the usual one.
+     */
+    readonly snapshotInclude?: readonly string[];
+    /**
+     * What is put back when a rule refuses a write that has already landed: `"refused"` (the default)
+     * writes back only the files a rule refused, `"all"` every file that call changed. While another
+     * agent's call overlaps it, only the refused files are put back whatever this says — that call's
+     * writes can be in the same diff.
+     */
+    readonly revert?: "refused" | "all";
 }
 /**
  * One hand-built tree-sitter grammar, as `registerDynamicLanguage` wants it.

package/dist/types/packs/docs.d.ts

@@ -5,9 +5,9 @@
  * least possible cognitive load, and the agent wants almost nothing in context. So `docs/` has
  * exactly two doors and everything inside follows its door's rules.
  *
- * @setup A `docs/` folder holding exactly `user/` and `agent/`, each with its own index —
- * `docs/user/index.html` for people and `docs/agent/README.md` as a list of pointers. The two
- * guardrails below refuse anything else at the top of the folder, so a repo with a different shape
+ * @setup A `docs/` folder holding exactly `user/` and `agent/`, each with its own index — an index
+ * file under `docs/user/` for people and `docs/agent/README.md` as a list of pointers. The
+ * guardrail below refuses anything else at the top of the folder, so a repo with a different shape
  * either moves its pages or does not bind this pack.
  */
 export interface Doors {
@@ -45,5 +45,4 @@ export declare const docs: import("../index.ts").Pack<{
      * drawer, and neither audience's rules can be applied to what is in it.
      */
     docsShape: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
-    noMarkdownInUserDocs: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
 }, Doors | undefined>;

package/dist/types/packs/work.d.ts

@@ -17,6 +17,20 @@ export declare const builder: import("../index.ts").Category;
  * a frontmatter list somebody can widen.
  */
 export declare const checker: import("../index.ts").Category;
+/** The rungs that may be named as writers — a checker is the rung that never writes. */
+export type Writer = "builder" | "parent";
+/** What a repo may say about how it runs the lifecycle. Every field is optional. */
+export interface Rungs {
+    /**
+     * The rungs allowed to change files in a worktree, turning on ONE WRITER: a write or a delete by
+     * any other actor is refused — an Edit before it lands, anything else put back after.
+     *
+     * OPTIONAL, and with no list there is no entry at all. One writer is for a worktree several
+     * agents share with one builder in it; in a repo where a helper agent of any other kind is
+     * expected to write, it would refuse that helper's every change, so it is off until a repo asks.
+     */
+    readonly writers?: readonly Writer[];
+}
 /**
  * The WORK LIFECYCLE's rungs: who is acting, and what each rung may do.
  *
@@ -38,12 +52,14 @@ export declare const checker: import("../index.ts").Category;
  * so in a repo that does not run the lifecycle they are five rules that can never fire.
  * @adopt Bind it only in a repo whose tasks are actually run through the lifecycle. The three rung
  * rules are scoped to categories this pack defines, so they judge nobody until a session is
- * classified as a builder or a checker — a human at a keyboard is neither.
+ * classified as a builder or a checker — a human at a keyboard is neither. Name `writers` to let
+ * only those rungs change files in the worktree.
  */
 export declare const work: import("../index.ts").Pack<{
+    builderWrites?: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "write" | "delete">;
     planIsTheParents: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "for" | "description", "command">;
     checkersDoNotWrite: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "for" | "description", "write">;
     ticksAreTheChilds: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "for" | "description", "command">;
     noAgentInboxItems: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
     noShellSubstitutionInProse: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
-}, undefined>;
+}, Rungs | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jawache/flow",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Guardrails and breadcrumbs as code — packs you import, a config that typechecks, one adapter per harness.",
   "license": "MIT",
   "repository": {