toolroll 0.9.84 → 0.9.85

package/dist/youiyoux-intake.d.ts

@@ -0,0 +1,234 @@
+/**
+ * youiyoux change and options requests become tasks (docs/guide/getting-started.md, "Change requests from youiyoux").
+ *
+ * youiyoux is a design-system tool: in its hub a person points at a component on a screenshot of their app and asks
+ * for a change, and it saves the request as `<project>/.youi/requests/<id>.json` (`youi.request/v1`). A project that
+ * uses youiyoux (a `youi.project.json` at its root, or a `.youi/requests` folder) has this intake on with no step of
+ * its own, unless a person turned it off in Settings → Integrations.
+ *
+ * On the worker's flow pass this reads the project's main checkout — the path from Toolroll's own records, resolved
+ * with realpath — and files each open change request with a task exactly once, keyed by the project and the request
+ * id in `youiyoux_request`: never again, whatever the file says later. Everything in the folder is outside text,
+ * written by whoever can write the project's folder:
+ *
+ * - the folders and files must be real (never a link), a file a single link to itself, at most 64 KB, read without
+ *   following a link or waiting on a pipe, and at most 200 are read in one pass;
+ * - a file whose name, schema or id is wrong is counted (the integration says so) and never filed;
+ * - text that looks like a key or password is left out (recorded once, never filed), as flow triggers do;
+ * - a path the task may touch is kept only when youiyoux knew them all and every one is a plain relative path;
+ * - the task is filed through the one filing door (proposal.ts) by the "youiyoux" automation, unplanned, and waits
+ *   for a person: its provenance (`filed_via = 'youiyoux'`) keeps every seal no person looked at off it (store.ts,
+ *   the outside-request quarantine), so no operating mode, grant, schedule or automatic seal approves it. A person
+ *   approves it in Toolroll, or with their own two taps in their paired chat where they turned approving from chat
+ *   on (chat-decide.ts), bound to the exact scope the card showed.
+ *
+ * Beside each request it writes `<id>.task.json` (`youi.request-task/v1`): the task and its status, and, when the
+ * console has an address (the one the installation names, else this machine's own console where `up` serves it, on
+ * loopback), the task's link and `home`, where a person approves all waiting work. It is written when filed, whenever
+ * the status changes, and once more when that address changes. Beside an options request's options file (below), it is
+ * the only file it writes in the checkout: written whole (a temporary file in the same folder, then renamed over),
+ * refused when the folder or the target is a link, never the request itself. The status is also kept in the store;
+ * nothing Toolroll decides reads the file back.
+ *
+ * Status words (task-status.ts headline → youiyoux): Queued → queued; Planning, Building and Waiting (work going on
+ * by itself) → building; Needs you → needs-you; Ready for review → ready; Complete → done; Failed → failed;
+ * Stopped → stopped.
+ *
+ * An options request (`kind: "options"`) asks an agent for two to four options for one component, which youiyoux shows
+ * on its Screens canvas. It is filed the same way, once, waiting for a person, and only as youiyoux's contract has it:
+ * its offer names `p-<its own hex>`, that proposal's file `.youi/proposals/p-<hex>.json`, and the task may touch that
+ * one file (anything else is counted as a file that couldn't be read, and never filed). The proposal it names is kept
+ * when filed; the request is never read for it again. Then (runYouiyoux, the worker's pass):
+ *
+ * - When the task is Ready for review (or Complete), its result is read: the file at the result's commit, the commit
+ *   Toolroll recorded for the build (never the checkout the agent had, which it controls and the pool hands on), read
+ *   with the hardened git (teardown-git.ts). It must be a plain file in that commit (never a link), at most 64 KB, a
+ *   `youi.proposal/v1` file whose id is the proposal, which answers this request, still open (an agent proposes; only a
+ *   person decides), by an agent, with no key-like text. Then it is copied, byte for byte, into the project's main
+ *   checkout as `.youi/proposals/<id>.json` the way the status file is written (folders real, never through a link;
+ *   a temporary file, then linked into place, which never replaces a file already there: a person may have decided on
+ *   it). A file missing from the result, or one that isn't safe, is said in the status file and never copied; a newer
+ *   result is read again.
+ * - Only a file Toolroll copied is read for a decision: one already at that name is left as it was (a person may
+ *   have decided on it) and never read for one, unless it is byte for byte the result's (an earlier pass's copy).
+ * - When that copy says a person chose an option or dismissed them all (youiyoux's hub writes that), and it is still
+ *   the proposal copied (only its status, choice, decidedBy, decidedAt, request and updatedAt may differ), decided by
+ *   a person, at a time, the task is marked complete by Toolroll, as landed work is (result-completion.ts LANDED_ACTOR), without
+ *   merging or publishing its branch: its deliverable was the options, and youiyoux has used them. Only the exact
+ *   result whose file was copied, and only through every guard a person's completion passes (landed-cleanup.ts
+ *   completionProblem): otherwise it stays Ready for review and the ledger says why. The ledger keeps who decided
+ *   what, as youiyoux wrote it (outside text, cleaned). A decision never approves, publishes or merges anything.
+ */
+import type { Store } from "./store.js";
+import type { Headline } from "./task-status.js";
+import { type Git } from "./landed-cleanup.js";
+import { YOUIYOUX_FILED_VIA, type YouiyouxRequest, type YouiyouxRequestTask, type YouiyouxTaskStatus } from "./contracts/youiyoux-request.js";
+export { YOUIYOUX_FILED_VIA };
+/** Who files the tasks: an automation, like a flow trigger. */
+export declare const YOUIYOUX_ACTOR = "youiyoux";
+export declare const REQUEST_BYTES: number;
+export declare const REQUESTS_PER_PASS = 200;
+export declare const FILED_PER_PASS = 10;
+/** The ledger's word for a decision youiyoux's hub made on a task's options. */
+export declare const OPTIONS_DECIDED_ACTION = "youiyoux options decided";
+export declare const OPTIONS_COPIED_ACTION = "youiyoux options copied";
+/** The flow pass runs every 15 seconds; the folder is read at most this often. */
+export declare const INTAKE_EVERY_MS = 30000;
+export declare const STATUS_OF_HEADLINE: Readonly<Record<Headline, YouiyouxTaskStatus>>;
+/** Whether a project uses youiyoux: a `youi.project.json` at its root, or a `.youi` folder. Only their presence is
+ * read here (a link counts, so the integration can say it is Broken); requestsFolder decides what may be read. */
+export declare function usesYouiyoux(repo: string): boolean;
+/** The paths a request may touch: every one a plain relative path inside the project, or none at all. */
+export declare function safeTouches(touches: readonly string[]): string[] | null;
+export type RequestTask = {
+    title: string;
+    goal: string;
+    outOfScope: string | null;
+    touches: string[];
+    acceptance: {
+        id: string;
+        statement: string;
+        how: null;
+        evidence: string[];
+    }[];
+    /** Where the person pointed, for the task page: the route, the component, and `file:line` when youiyoux knew a plain one. */
+    pointed: {
+        route: string;
+        component: string;
+        at: string | null;
+    };
+};
+/** The task a request asks for, in Toolroll's terms. Text is cleaned here; whether it may be filed is decided by the caller. */
+export declare function requestTask(request: YouiyouxRequest): RequestTask;
+/** A person turns the intake off or back on for a project; the ledger keeps who. */
+export declare function setYouiyouxIntake(store: Store, repo: string, on: boolean, by: string, now: Date): void;
+export type YouiyouxState = {
+    /** The project uses youiyoux, as the worker's last pass found. */
+    uses: boolean;
+    /** Requests become tasks: it uses youiyoux and nobody turned it off. */
+    on: boolean;
+    /** A person turned it off. */
+    off: boolean;
+    /** Filed tasks not yet done, failed or stopped. */
+    queued: number;
+    filed: number;
+    invalid: number;
+    problem: string | null;
+    checkedAt: string | null;
+};
+/** How the intake stands for one project, from the store alone: a page reads it on every render, so it never reads the
+ * project's folder (one that doesn't answer must not hold the console). Whether it uses youiyoux is the last pass's. */
+export declare function youiyouxState(store: Store, repo: string): YouiyouxState;
+/** The one line `toolroll onboard` says for a project that uses youiyoux; null when it doesn't. */
+export declare function youiyouxOnboardLine(store: Store, repo: string): string | null;
+/** The console the links name: the address the installation names (CONSOLE_URL or the console-url file), else, with
+ * none named, this machine's own console where `up` serves it (loopback http only, never a guessed host); null without
+ * either. Either way http(s) with no credentials, query or fragment. */
+export declare function consoleBase(env: Record<string, string | undefined>, dir: string | null): string | null;
+/** The task's page in that console; null without one. */
+export declare function taskLink(env: Record<string, string | undefined>, dir: string | null, taskId: string): string | null;
+/**
+ * Write `<id>.task.json` beside its request, whole. The folders are checked again now (a link is refused), the request
+ * must still be a plain file, the target must be a plain file or absent, and the content goes to a fresh temporary file
+ * in the same folder (created exclusively, never through a link) that is then renamed over the target.
+ */
+export declare function writeStatusFile(repo: string, body: YouiyouxRequestTask): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Put an options file into the project's main checkout as `.youi/proposals/<id>.json`, whole, and never over a file
+ * already there (a person may have decided on it). The folders are checked as the status file's are (`.youi/proposals`
+ * is made, as a real folder, when missing), the content goes to a fresh temporary file in the same folder (created
+ * exclusively, never through a link), the folders are checked again, and the temporary file is linked into place, which
+ * fails rather than replace anything at that name, a link included. `same`: that exact content was already there;
+ * `taken`: something else was, and is left as it was.
+ */
+export declare function writeProposalFile(repo: string, id: string, text: string): {
+    ok: true;
+    made: "written" | "same" | "taken";
+} | {
+    ok: false;
+    problem: string;
+};
+/** `git`: the hardened git an options request's result is read with (landed-cleanup.ts gitOf), and `evidenceRoot`, where
+ * results' saved evidence is (a completion is bound to the receipt read with it). Without either, options wait. */
+export type YouiyouxIo = {
+    dir: string | null;
+    env: Record<string, string | undefined>;
+    git?: Git;
+    evidenceRoot?: string | null;
+};
+/** `copied`: options files that went to the hub; `decided`: decisions in the hub Toolroll acted on. */
+export type YouiyouxPass = {
+    filed: number;
+    skipped: number;
+    invalid: number;
+    updated: number;
+    copied: number;
+    decided: number;
+    problems: string[];
+};
+export declare const NO_YOUIYOUX_PASS: Readonly<YouiyouxPass>;
+/** File one request's task, exactly once: the claim and the filing are one transaction (two passes, in two processes
+ * or one, make one task). */
+export declare function fileYouiyouxRequest(store: Store, repo: string, request: YouiyouxRequest, now: Date): {
+    made: "filed";
+    taskId: string;
+} | {
+    made: "seen";
+} | {
+    made: "skipped";
+    note: string;
+};
+/**
+ * One message for what a pass filed, however many: the person's paired chats draw it as one card (chat-decide.ts) that
+ * lists each new task, with Approve all and each one's own Approve and Open, and a phone push links to what needs
+ * them. Keyed by the pass's first task, so a pass says it once; the tasks are the ones filed with it (one project, one
+ * moment: requestPassOf). Titles are cleaned outside text, as filed.
+ */
+export declare function noteYouiyouxFiled(store: Store, taskIds: readonly string[], now: Date): void;
+/** What a pass's tasks were asked for, in a word: "change request", "options request", or "request" for both. */
+export declare function requestKindWord(store: Store, taskIds: readonly string[]): string;
+/** The tasks one pass filed beside this one (one project, one moment), in request order; empty for any other task. */
+export declare function requestPassOf(store: Store, taskId: string): string[];
+/**
+ * One project's pass: read new requests and file them, then write each filed task's status where it changed (no
+ * options moved: runYouiyoux does that too). The folder read is the project in Toolroll's records that `given`
+ * resolves to; anything else is left alone.
+ */
+export declare function runYouiyouxIntake(store: Store, given: string, now: Date, io: YouiyouxIo, options?: {
+    force?: boolean;
+}): YouiyouxPass;
+/** The worker's pass for one project (flow-cadence.ts): the intake, then each options request's options, both ways. */
+export declare function runYouiyoux(store: Store, given: string, now: Date, io: YouiyouxIo, options?: {
+    force?: boolean;
+}): Promise<YouiyouxPass>;
+export type OptionsRow = {
+    request: string;
+    taskId: string;
+    proposal: string;
+    state: string | null;
+    run: number | null;
+    digest: string | null;
+};
+/** The digest of an options file apart from what a decision changes: the proposal itself, every other key included. */
+export declare function proposalIdentity(raw: unknown): string | null;
+/** Why an agent's options file can't go to the hub as it stands, or null. Toolroll checks what makes it safe to copy
+ * and this request's; youiyoux checks each option against the component's contract when it reads it. */
+export declare function proposalProblem(text: string, proposal: string, request: string): string | null;
+export type Decision = {
+    status: "chosen" | "dismissed";
+    choice: string | null;
+    label: string | null;
+    by: string | null;
+    at: string | null;
+};
+/**
+ * A person decided in the hub: mark the task complete as landed work is, bound to the exact result whose options were
+ * copied, through every guard a person's completion passes, or leave it Ready for review and say why. Once per request,
+ * in one transaction with the read. Waits (false) while the task isn't Ready, Complete or cancelled.
+ */
+export declare function actOnDecision(store: Store, repo: string, row: OptionsRow, decision: Decision, now: Date, root: string): boolean;