approval-md 0.1.0 → 0.2.0

package/dist/src/core/task-file.d.ts

@@ -0,0 +1,185 @@
+/**
+ * The task-file writer: round-trip rewriting that preserves everything it does
+ * not own (SPEC.md §6, APRV-61).
+ *
+ * SPEC.md §6 is a MUST: "Implementations MUST preserve unknown frontmatter keys
+ * when rewriting files." `core/frontmatter.ts` is the reader and is read-only in
+ * the strongest sense; this module is its counterpart, and the only place in the
+ * codebase that produces new task-file bytes.
+ *
+ * The bar is not "preserve the keys we can think of". Backlog.md 1.49.3 itself
+ * fails this MUST — the `envelope-edit-before` / `envelope-edit-after` fixtures
+ * record it dropping our whole `approval:` key on an unrelated `task edit` — and
+ * we extend that convention rather than fork it, so the writer that has to be
+ * trustworthy is ours.
+ *
+ * ## Why lines, not a YAML document
+ *
+ * The obvious implementation reserialises the frontmatter through the `yaml`
+ * library's Document API. It preserves more than a naive `parse`/`stringify`
+ * round trip, but it does not preserve *bytes*: quoting style, intra-line
+ * spacing, comment placement, and blank-line runs are all reconstructed from the
+ * library's own defaults. Every one of those is a spurious diff in a user's git
+ * history, and a diff nobody can explain is how a board tool's metadata gets
+ * quietly eaten.
+ *
+ * So this module treats the frontmatter as **lines with their terminators**, and
+ * the parsed YAML only as an oracle:
+ *
+ *   - the hardened parser decides whether the block is *structurally* valid at
+ *     all (and, being hardened, rejects duplicate keys, tags, and unbounded
+ *     aliases before any of them can reach a rewrite);
+ *   - a column-0 line scan finds the `approval:` key's line range;
+ *   - only that range is rewritten, and for a state-only edit only the single
+ *     `state:` line inside it;
+ *   - every other line — every other key, its order, its quoting, its comments,
+ *     the blank lines between them, both `---` delimiters, and the entire body
+ *     after the closing delimiter — is re-emitted as the exact bytes that came
+ *     in, terminator included.
+ *
+ * Byte-identity is therefore a property of the construction, not of a
+ * comparison performed afterwards: untouched lines are never parsed and never
+ * rebuilt. The corpus test (`tests/task-file.test.ts`) still asserts it against
+ * every real Backlog.md fixture, because a construction argument that is not
+ * checked is a construction argument that has already drifted.
+ *
+ * ## What "unknown key" means here
+ *
+ * Every frontmatter key except `approval:` is unknown to this writer, and that
+ * is deliberate. `id`, `title`, `status`, `milestone`, `ordinal`,
+ * `parent_task_id` and the rest belong to Backlog.md; a key some future board
+ * tool invents belongs to it. This module has no allow-list of keys it tolerates
+ * — it has one key it owns and rewrites, and it cannot express a change to
+ * anything else. There is no edit in {@link TaskFileEdit} that removes a key,
+ * reorders keys, or touches the body.
+ *
+ * ## This writer never touches the log
+ *
+ * A task file is a **projection** (SPEC.md §6.3): the daemon writes `state:`
+ * into the file *after* the event is appended, never the reverse. Nothing here
+ * opens `.approval/`, appends to `events.jsonl`, or computes a hash chain.
+ * {@link rewriteTaskFile} is a pure function of (bytes, edit) with no clock, no
+ * network, and no filesystem access at all; {@link writeTaskFileAtomic} writes
+ * exactly the one path it is handed.
+ *
+ * Determinism: same input bytes and same edit, same output bytes, always. Never
+ * throws — every failure is a structured result carrying one of the codes in
+ * {@link TaskFileErrorCode}.
+ */
+import type { EnvelopeState } from "../daemon/projection.js";
+/** The frontmatter key this module owns. Everything else is preserved verbatim. */
+export declare const ENVELOPE_KEY = "approval";
+/** The schema id (`schema/envelope.schema.json`) the result is validated against. */
+export declare const ENVELOPE_SCHEMA_ID = "envelope";
+/**
+ * Why a rewrite was refused. Closed union, pinned by `tests/task-file.test.ts`:
+ * a caller distinguishing "this file has no envelope yet" from "this file is
+ * corrupt" must be able to do so mechanically.
+ */
+export type TaskFileErrorCode = 
+/** The file does not begin with a `---` line: no frontmatter to rewrite. */
+"no-frontmatter"
+/** An opening `---` with no closing `---` before end of file. */
+ | "unterminated"
+/** The frontmatter is not parseable under the hardened YAML settings. */
+ | "yaml-error"
+/** The frontmatter parsed, but not to a mapping. */
+ | "not-a-map"
+/** A state edit was asked for and the file carries no `approval:` key. */
+ | "no-envelope"
+/** An `approval:` key exists and its value is not a mapping. */
+ | "envelope-not-a-map"
+/** The `approval:` block is not block-style mapping this writer can line-edit. */
+ | "unsupported-shape"
+/** The envelope the edit would produce fails `envelope.schema.json`. */
+ | "invalid-envelope"
+/** The envelope could not be serialised to YAML. */
+ | "serialize-failed"
+/** Self-check: the rewritten bytes did not re-read as the intended document. */
+ | "round-trip-failed"
+/** An unexpected throw, converted rather than propagated. */
+ | "internal-error"
+/** {@link writeTaskFileAtomic} only: the bytes did not reach the disk. */
+ | "write-failed";
+/** Outcome of {@link rewriteTaskFile}. */
+export type RewriteResult = {
+    ok: true;
+    bytes: string;
+    changed: boolean;
+} | {
+    ok: false;
+    code: TaskFileErrorCode;
+    message: string;
+};
+/**
+ * The changes this writer can express. Deliberately tiny, and deliberately
+ * additive: there is no edit that removes the envelope, removes any other key,
+ * reorders keys, or reaches the body.
+ *
+ * - `none` — rewrite nothing. The output is the input, byte for byte, once the
+ *   frontmatter has been confirmed structurally sound. Used to prove the reader
+ *   and the writer agree on a file before anything is changed.
+ * - `set-state` — replace the value on the envelope's direct `state:` line
+ *   (SPEC.md §6.3). Exactly one line of the file changes.
+ * - `set-envelope` — write the whole `approval:` subtree, inserting the key when
+ *   the file has none.
+ */
+export type TaskFileEdit = {
+    kind: "none";
+} | {
+    kind: "set-state";
+    state: EnvelopeState;
+} | {
+    kind: "set-envelope";
+    envelope: Record<string, unknown>;
+};
+/** Options accepted by {@link rewriteTaskFile}. */
+export interface RewriteOptions {
+    /** Schema directory, forwarded to {@link validate}. Injectable for tests. */
+    schemaDir?: string;
+}
+/**
+ * Rewrite a task file's `approval:` subtree, preserving everything else byte for
+ * byte.
+ *
+ * Returns the new bytes, plus `changed` so a caller can skip a pointless write.
+ * On any refusal the input is untouched and nothing has been written anywhere:
+ * this function does not touch the filesystem at all.
+ *
+ * Insertion position (`set-envelope` on a file with no `approval:` key): the key
+ * is appended as the **last** top-level key, immediately before the closing
+ * delimiter. The corpus is the reason this needed a decision rather than a
+ * default. Backlog.md does not append its own new keys — in `milestone-assign/`
+ * the CLI put `milestone:` between `labels:` and `dependencies:`, because it
+ * rewrites frontmatter from its own model in its own canonical order — and at
+ * 1.49.3 it does not preserve unknown keys at all, so no position we pick
+ * survives its next edit. Given that no position is safe from the CLI, the
+ * choice is made on the diff: last keeps a multi-line block out of the middle of
+ * the board's short scalar keys, so inserting it moves no existing line, and it
+ * matches where the hand-written `envelope-edit-before` fixture put the envelope.
+ */
+export declare function rewriteTaskFile(text: string, edit: TaskFileEdit, options?: RewriteOptions): RewriteResult;
+/** Outcome of {@link writeTaskFileAtomic}. */
+export type WriteTaskFileResult = {
+    ok: true;
+    path: string;
+    bytes: number;
+} | {
+    ok: false;
+    code: TaskFileErrorCode;
+    message: string;
+};
+/**
+ * Write task-file bytes atomically: temp file in the destination directory, then
+ * rename.
+ *
+ * The same idiom as `core/payload-store.ts` and `channels/render-queue.ts`, for
+ * the same reason: a reader — a board tool, an editor, the next agent — sees
+ * either the previous complete file or the new one, never a half-written task.
+ * The temp name is the only non-deterministic thing here and it never reaches
+ * the file's contents; it is removed on every failure path, so a failed write
+ * leaves no debris beside the task.
+ *
+ * Writes this one path and nothing else. It does not open the log.
+ */
+export declare function writeTaskFileAtomic(path: string, bytes: string): WriteTaskFileResult;

package/dist/src/core/telegram-config.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Telegram configuration NAMES (SPEC.md §5.1 `channels.telegram.token_env` /
+ * `chat_id_env`, amended §5.2 by APRV-72).
+ *
+ * Constants and resolvers live in core, not in `channels/`, because more than
+ * one layer needs them: the Telegram CLI, doctor, and `approval env` (APRV-73)
+ * all ask "which variable holds the token?" and none of them may answer it
+ * differently. Placing them here also keeps `core/` free of any import from
+ * `channels/`, in the spirit of `tests/layering.test.ts`.
+ *
+ * NAMES only, in both directions: a policy that carried the token would be a
+ * bot credential in a file agents may read, which is exactly what §5.1's
+ * name-indirection exists to prevent. A policy that failed to load names
+ * nothing, so the default applies: a variable name is not a permission, and
+ * treating it as one would mean an unrelated policy typo locked the operator
+ * out of their own channel. This is `passphraseEnvFor`'s argument, verbatim,
+ * for the same reason: these are the same kind of key.
+ *
+ * Nothing here reads `process.env`. The CLI layer takes the name and looks
+ * the value up.
+ */
+import type { CredentialSpec } from "./credential-spec.js";
+import type { PolicyLoadResult } from "./policy-load.js";
+/**
+ * The environment variable the bot token is read from when the policy declares
+ * no `channels.telegram.token_env`. A DEFAULT, not a fixed name: see
+ * {@link telegramTokenEnvFor}.
+ */
+export declare const TELEGRAM_TOKEN_ENV = "APPROVAL_TG_TOKEN";
+/**
+ * The environment variable the approver chat id is read from when the policy
+ * declares no `channels.telegram.chat_id_env`. Also a default.
+ */
+export declare const TELEGRAM_CHAT_ENV = "APPROVAL_TG_CHAT";
+/** The NAME of the variable this policy says the bot token lives in. */
+export declare function telegramTokenEnvFor(load: PolicyLoadResult): string;
+/** The NAME of the variable this policy says the approver chat id lives in. */
+export declare function telegramChatEnvFor(load: PolicyLoadResult): string;
+/**
+ * How a listener puts the pending set in front of the approver (APRV-216).
+ *
+ * `paced` sends one summary line and the oldest pending request, and the next
+ * one only once that request is decided, skipped, or passed over. `burst` is
+ * the pre-APRV-216 behaviour: every pending request this process has not sent
+ * yet, on every cycle, behind the APRV-196 re-delivery banner.
+ *
+ * Not a credential and not a name, so it sits beside the two that are for one
+ * reason: it is the third thing a caller asks the policy about the Telegram
+ * channel, and a second resolver module would be a second place for the
+ * fallback rule to drift.
+ */
+export type TelegramDelivery = "paced" | "burst";
+/**
+ * What an absent `channels.telegram.delivery` means.
+ *
+ * Paced, since APRV-216. The incident behind it is the one APRV-196 softened
+ * rather than closed: a restart with six pending policy edits put six prompts
+ * on a phone at once, and an approver reading a wall of near-identical
+ * questions is an approver who taps rather than reads. A default is a claim
+ * about which failure is worse, and the worse one here is inattentive approval
+ * rather than a slower queue: pacing withholds nothing, because every request
+ * stays pending in the log whether or not it has been shown, and `/queue`
+ * lists the whole set on demand.
+ */
+export declare const TELEGRAM_DEFAULT_DELIVERY: TelegramDelivery;
+/**
+ * The delivery mode this policy declares, or the default.
+ *
+ * Fail-soft in the same direction as the two name resolvers above: a policy
+ * that did not load declares nothing, and a delivery mode is not a permission,
+ * so an unrelated policy typo must not decide how requests are shown. The
+ * schema closes the enum, so a policy that LOADED can only carry one of the
+ * two; anything else reaching here (a hand-built load result, a key from a
+ * later version) falls back rather than being guessed at.
+ */
+export declare function telegramDeliveryFor(load: PolicyLoadResult): TelegramDelivery;
+/**
+ * The Telegram channel's credential manifest (APRV-79).
+ *
+ * The same shape an adapter declares (`core/credential-spec.ts`), for the same
+ * reason: `approval setup channel telegram` runs the shared conversation in
+ * `cli/setup-flow.ts`, and that conversation is DERIVED from a manifest. What
+ * differs from an adapter's is the destination and not the vocabulary — a
+ * channel's two values go to the OS keystore and `.approval/env`, because a
+ * channel holds no state and its token is what unlocks the machine, while an
+ * adapter's go to the vault (SPEC.md §4, §10.3, §10.4).
+ *
+ * The NAMES are the policy's, resolved through the two functions above, so the
+ * checklist an operator reads names the variables their own policy declares.
+ * A spec carries no value and no default on either entry: the token is the
+ * operator's and the chat id is discovered.
+ */
+export declare function telegramCredentialSpecs(load: PolicyLoadResult): CredentialSpec[];