@foldrun/core 0.3.0 → 0.5.0

package/dist/src/flow-patterns.d.ts

@@ -0,0 +1,141 @@
+import { type FlowStep } from "./store.ts";
+import { type Groups } from "./arrange.ts";
+import { type RemovalImpact } from "./step-removal.ts";
+/** A flow's steps as groups of indices into its parsed steps — what
+ *  reorderFlowSteps and the arrange helpers take. */
+export declare function flowGroups(steps: FlowStep[]): Groups;
+/** The step options a pattern writes. Everything else in a step stays the
+ *  author's (and updateFlowStep's) business. */
+export declare const PATTERN_OPTION_KEYS: readonly ["ask", "wait", "on-fail", "each", "max", "loop", "until", "verify", "case", "else", "when", "retry", "approve"];
+export type PatternOptionKey = (typeof PATTERN_OPTION_KEYS)[number];
+export type PatternOptions = Partial<Record<PatternOptionKey, string | null>>;
+export type PatternEdit = 
+/** Chain (at.rail: its own group there) or Parallel (at.column: join
+ *  the group in that column). Rail 0 is before every group. */
+{
+    op: "insert";
+    target: string;
+    subflow?: boolean;
+    instruction?: string;
+    at: {
+        rail: number;
+    } | {
+        column: number;
+    };
+    options?: PatternOptions;
+}
+/** Router: a triage step, then one group of case:/else: branches. */
+ | {
+    op: "router";
+    router: string;
+    instruction?: string;
+    rail: number;
+    cases: {
+        value: string;
+        target: string;
+    }[];
+    else?: string;
+}
+/** Fan-out, evaluator loop, ask, wait, rescue: options on one step. */
+ | {
+    op: "options";
+    step: number;
+    set: PatternOptions;
+}
+/** Approval gate: the `!` marker. */
+ | {
+    op: "approve";
+    step: number;
+    on: boolean;
+}
+/** Delete one step (removeStep). */
+ | {
+    op: "remove";
+    step: number;
+}
+/** Copy one step beside itself (duplicateStep). */
+ | {
+    op: "duplicate";
+    step: number;
+}
+/** Copied step markdown, placed (pasteSteps). */
+ | {
+    op: "paste";
+    text: string;
+    at: {
+        rail: number;
+    } | {
+        column: number;
+    };
+};
+/** A new step, placed; the file, the new step's index and its column. */
+declare function insertFlowStepLF(raw: string, o: {
+    target: string;
+    subflow?: boolean;
+    instruction?: string;
+    at: {
+        rail: number;
+    } | {
+        column: number;
+    };
+    options?: PatternOptions;
+}): {
+    text: string;
+    index: number;
+    column: number;
+};
+/**
+ * Paste copied steps (stepSource output, one block or several) into a flow.
+ * Steps copied with the same group number stay parallel with each other.
+ * `{ rail }` places the pasted groups as their own consecutive groups there
+ * (0 is before every group); `{ column }` puts every pasted step in that
+ * existing group. Groups renumber; prose stays where it was. Returns the
+ * file and the pasted steps' indices in it. Refused when the paste does not
+ * parse as those steps, or when `check` would gain an error.
+ */
+declare function pasteStepsLF(raw: string, text: string, at: {
+    rail: number;
+} | {
+    column: number;
+}): {
+    text: string;
+    indices: number[];
+};
+export declare const setStepOptions: (raw: string, index: number, set: PatternOptions) => string;
+export declare const setStepApprove: (raw: string, index: number, on: boolean) => string;
+export declare function insertFlowStep(...[raw, o]: Parameters<typeof insertFlowStepLF>): ReturnType<typeof insertFlowStepLF>;
+export declare const removeStepImpact: (raw: string, index: number) => RemovalImpact;
+export declare const removeStep: (raw: string, index: number) => string;
+export declare const stepSource: (raw: string, index: number) => string;
+export declare const duplicateStep: (raw: string, index: number) => string;
+export declare function pasteSteps(...[raw, text, at]: Parameters<typeof pasteStepsLF>): ReturnType<typeof pasteStepsLF>;
+export declare const applyPatternEdit: (raw: string, edit: PatternEdit) => string;
+/** The frontmatter list fields an agent's team lives in: whom it delegates
+ *  to, whom it consults, and what it may do (`ask` among them). */
+export declare const TEAM_LIST_KEYS: readonly ["subagents", "agents", "tools"];
+export type TeamListKey = (typeof TEAM_LIST_KEYS)[number];
+/** The names a frontmatter list holds, read the way the file says them. */
+export declare function frontmatterList(raw: string, key: string): string[];
+/**
+ * Add `name` to, or remove it from, the list under `key`, touching only the
+ * lines that list is on. Flow style (`key: [a, b]`) stays flow style, block
+ * style stays block style, a trailing `# comment` stays put, and the other
+ * items keep their spelling. A list emptied by a removal is written
+ * `key: []` rather than deleted: the file still says "none", which for
+ * `tools:` is not the same as saying nothing.
+ */
+export declare function editFrontmatterList(raw: string, key: string, name: string, action: "add" | "remove"): string;
+/** A YAML scalar for a one-line value: plain when plain reads back as the
+ *  same string, double-quoted (JSON is valid YAML) when it would not. */
+export declare function yamlScalar(value: string): string;
+/** Set one scalar key — `description:`, `model:`. Replaces its line (and the
+ *  indented lines of a `>`/`|` block under it); absent, it goes right after
+ *  `name:`, or last. */
+export declare function setFrontmatterScalar(raw: string, key: string, value: string): string;
+/** A new agent file: the template with the answers to "what is it for"
+ *  and "which model" written into it, the rest as the template wrote it. */
+export declare function newAgentFile(template: string, o: {
+    description?: string;
+    model?: string;
+}): string;
+export {};