dorfl 0.0.0 → 0.1.0

package/dist/verify-workflow-template.js

@@ -0,0 +1,126 @@
+/**
+ * The `install-ci` VERIFY-WORKFLOW capability (prd
+ * `land-time-reverify-and-parallel-merge-ceiling`, task
+ * `install-ci-tier1-branch-protection`; Story 11 — the Tier-1 GitHub ceiling).
+ * Emits a small `verify.yml` workflow whose ONLY job is `verify` and runs on
+ * `pull_request` (and `merge_group`, the Tier-2 forward seam). It produces the
+ * GitHub check named exactly {@link VERIFY_CHECK_CONTEXT}, which the
+ * branch-protection step ({@link installCIBranchProtectionStep}) names as the
+ * required-status check `context`. Co-locating the two strings — the EMITTED
+ * job/check name AND the REQUIRED context — in one constant pins the
+ * acceptance-criterion "context matches the workflow's job name" by construction
+ * (a single test diffs the two).
+ *
+ * The workflow is deliberately thin: it wires the same composite setup action
+ * the other capabilities use, then runs `dorfl verify` — the deterministic shell
+ * gate the repo declares in `.dorfl.json`. No agent, no provider secrets, no
+ * `gh` mutation; it is read-only with respect to `work/`.
+ *
+ * `merge_group` is present (with no extra wiring) so a follow-on Tier-2 task
+ * (GitHub Merge Queue) can flip the ruleset on without changing this workflow's
+ * trigger surface — the forward seam the spec's Applied Answers q3 names.
+ */
+/**
+ * The required-status-check CONTEXT install-ci sets via branch protection AND the
+ * job/check name the emitted verify workflow produces. ONE source of truth so
+ * the two strings can never drift (the "context matches the workflow's job name"
+ * acceptance criterion is enforced by both reading this constant).
+ */
+export const VERIFY_CHECK_CONTEXT = 'verify';
+/** The capability id (the registry key + the emitted workflow file stem). */
+export const VERIFY_CAPABILITY_ID = 'verify';
+/** The wizard-facing label for the verify capability. */
+export const VERIFY_CAPABILITY_LABEL = 'Run the repo `verify` gate on every PR (the Tier-1 GitHub ceiling: produces the required-status check `verify` that branch protection requires)';
+/** The repo-relative path (under the output base) of the emitted workflow. */
+export const VERIFY_WORKFLOW_PATH = 'workflows/verify.yml';
+/**
+ * Generate the verify workflow YAML. Deterministic: the same config produces
+ * byte-identical output. The job is named exactly {@link VERIFY_CHECK_CONTEXT}
+ * so the GitHub check it produces matches the required-status `context` install-ci
+ * configures on `main` — by construction, not by hand-typed agreement.
+ */
+export function generateVerifyWorkflow(_config) {
+    return `\
+# dorfl — the VERIFY workflow (Tier-1 GitHub ceiling; prd
+# land-time-reverify-and-parallel-merge-ceiling, task
+# install-ci-tier1-branch-protection). EMITTED by \`dorfl install-ci\`; the
+# human commits it. DO NOT hand-edit a copy — re-run install-ci to upgrade.
+#
+# This workflow exists SOLELY to produce a GitHub check named \`${VERIFY_CHECK_CONTEXT}\`
+# on every pull request, which install-ci's branch-protection step requires
+# (\`required_status_checks.strict: true\` + a required \`${VERIFY_CHECK_CONTEXT}\` context)
+# so a PR cannot be merged stale. The merge button is disabled until \`${VERIFY_CHECK_CONTEXT}\`
+# reports success on the rebased PR head — closing the PR-merge-time drift window
+# story 7 names.
+#
+# \`merge_group\` is listed so a follow-on Tier-2 task (GitHub Merge Queue) can
+# enable speculative-rebase merging by flipping the ruleset, WITHOUT changing
+# this workflow's trigger surface (the Applied Answer q3 forward seam).
+#
+# CONTEXT NAMING — the job is named EXACTLY \`${VERIFY_CHECK_CONTEXT}\`. install-ci
+# names the same string as the required-context, so they cannot drift. If you
+# rename the job here you MUST re-run install-ci (or the protection's required
+# context will not match this workflow and every PR will block forever).
+#
+# SAFETY (US #9): the running job requests NO \`workflows\` permission and runs
+# only \`dorfl verify\` (a deterministic shell gate; \`pnpm format:check && pnpm
+# build && pnpm test\` for the dorfl repo). It cannot edit \`.github/workflows/**\`
+# or mutate \`work/\`.
+
+name: ${VERIFY_CHECK_CONTEXT}
+
+on:
+  pull_request:
+  # Tier-2 forward seam: a follow-on task enables GitHub Merge Queue and the
+  # same job re-runs on the speculative-rebase merge-group head, no template edit.
+  merge_group:
+
+# Serialise overlapping verify runs on the same ref (the latest commit wins —
+# stale runs are cancelled, since \`verify\` is a pure pass/fail gate).
+concurrency:
+  group: ${VERIFY_CHECK_CONTEXT}-\${{ github.ref }}
+  cancel-in-progress: true
+
+# NO \`workflows\` permission (US #9). \`contents: read\` is all the gate needs.
+permissions:
+  contents: read
+
+jobs:
+  # The job name IS the GitHub check context — it must equal VERIFY_CHECK_CONTEXT
+  # (\`${VERIFY_CHECK_CONTEXT}\`) or install-ci's branch protection will require a
+  # context this workflow does not produce.
+  ${VERIFY_CHECK_CONTEXT}:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/dorfl-setup
+      - name: run the repo verify gate
+        run: dorfl verify
+`;
+}
+/**
+ * Structurally validate the verify workflow against the task's acceptance
+ * criteria (job name = required context, runs on `pull_request`, ships the
+ * `merge_group` seam, no `workflows:` permission).
+ */
+export function validateVerifyWorkflow(text) {
+    const problems = [];
+    const require = (id, present, message) => {
+        if (!present)
+            problems.push({ id, message });
+    };
+    const operative = text
+        .split('\n')
+        .filter((line) => !/^\s*#/.test(line))
+        .join('\n');
+    require('job-named-verify-context', new RegExp(`^\\s{2}${VERIFY_CHECK_CONTEXT}:\\s*$`, 'm').test(operative), `the workflow must declare a job named exactly \`${VERIFY_CHECK_CONTEXT}\` ` +
+        '(its name IS the GitHub check context install-ci requires).');
+    require('trigger-pull-request', /\bon:\s*[\s\S]*?\bpull_request\s*:/.test(operative), 'must trigger on `pull_request` (the check must run on every PR).');
+    require('trigger-merge-group-seam', /\bmerge_group\s*:/.test(operative), 'must list `merge_group` as a trigger (the Tier-2 GitHub Merge Queue forward seam).');
+    require('no-workflows-permission', !/\bworkflows\s*:\s*write\b/.test(operative), 'must request NO `workflows` permission (US #9).');
+    require('runs-dorfl-verify', /dorfl verify\b/.test(operative), 'the job must run `dorfl verify` (the deterministic shell gate the repo declares).');
+    return { ok: problems.length === 0, problems };
+}
+//# sourceMappingURL=verify-workflow-template.js.map

package/dist/verify-workflow-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-workflow-template.js","sourceRoot":"","sources":["../src/verify-workflow-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAE7C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAE7C,yDAAyD;AACzD,MAAM,CAAC,MAAM,uBAAuB,GACnC,iJAAiJ,CAAC;AAEnJ,8EAA8E;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAyB;IAC/D,OAAO;;;;;;kEAM0D,oBAAoB;;4DAE1B,oBAAoB;yEACP,oBAAoB;;;;;;;;gDAQ7C,oBAAoB;;;;;;;;;;QAU5D,oBAAoB;;;;;;;;;;;WAWjB,oBAAoB;;;;;;;;;SAStB,oBAAoB;;IAEzB,oBAAoB;;;;;;;;;CASvB,CAAC;AACF,CAAC;AAcD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IAClD,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,MAAM,OAAO,GAAG,CAAC,EAAU,EAAE,OAAgB,EAAE,OAAe,EAAQ,EAAE;QACvE,IAAI,CAAC,OAAO;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAC,EAAE,EAAE,OAAO,EAAC,CAAC,CAAC;IAC5C,CAAC,CAAC;IACF,MAAM,SAAS,GAAG,IAAI;SACpB,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACrC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,OAAO,CAAC,0BAA0B,EAAE,IAAI,MAAM,CAC7C,UAAU,oBAAoB,QAAQ,EACtC,GAAG,CACH,CAAC,IAAI,CACL,SAAS,CACT,EAAE,mDAAmD,oBAAoB,KAAK;QAC9E,6DAA6D,CAAC,CAAC;IAChE,OAAO,CAAC,sBAAsB,EAAE,oCAAoC,CAAC,IAAI,CACxE,SAAS,CACT,EAAE,kEAAkE,CAAC,CAAC;IACvE,OAAO,CAAC,0BAA0B,EAAE,mBAAmB,CAAC,IAAI,CAC3D,SAAS,CACT,EAAE,oFAAoF,CAAC,CAAC;IACzF,OAAO,CAAC,yBAAyB,EAAE,CAAC,2BAA2B,CAAC,IAAI,CACnE,SAAS,CACT,EAAE,iDAAiD,CAAC,CAAC;IACtD,OAAO,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,IAAI,CACjD,SAAS,CACT,EAAE,mFAAmF,CAAC,CAAC;IACxF,OAAO,EAAC,EAAE,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,EAAC,CAAC;AAC9C,CAAC"}

package/dist/verify.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The per-repo acceptance gate, run as `dorfl verify`. It is a
+ * deterministic shell gate — a declared, per-repo command (or ordered list of
+ * commands) — NOT prose interpreted by a model. There is no LLM in this loop:
+ * the gate is known by reading config, and it either passes (exit 0) or it does
+ * not. This same mechanism is consumed by the human `complete` command (where it
+ * is a default-on, `--skip-verify`-able safety-net) and by the autonomous
+ * `run-once`/`watch` (where it is the authoritative, non-skippable trust
+ * boundary). `verify` itself just runs the gate; callers decide authority.
+ *
+ * It is read-only with respect to `work/`: it runs the declared check and never
+ * moves or commits anything.
+ */
+/**
+ * The per-repo gate, as declared in config. A single shell command, or an
+ * ordered list of commands run in sequence (each must pass for the gate to
+ * pass). `undefined` (unset) ⇒ {@link DEFAULT_VERIFY_COMMAND} is used.
+ */
+export type VerifyConfig = string | string[];
+/**
+ * The sensible default when no `verify` is configured: build, then test, then
+ * check formatting across the workspace. Deterministic, auditable, no model.
+ */
+export declare const DEFAULT_VERIFY_COMMAND = "pnpm -r build && pnpm -r test && pnpm -r format:check";
+/**
+ * Resolve the declared gate into an ordered, non-empty list of shell commands.
+ * Unset ⇒ the default. A string ⇒ a single command. A list ⇒ the list, with
+ * blank/whitespace-only entries dropped (and the default substituted if that
+ * leaves nothing). Each command is run in sequence; all must pass.
+ */
+export declare function resolveVerifyCommands(verify: VerifyConfig | undefined): string[];
+export interface RunVerifyOptions {
+    /** The repo to run the gate in (its working directory). */
+    cwd: string;
+    /** The declared gate (string | list). Unset ⇒ the default command. */
+    verify?: VerifyConfig;
+    /** Environment for the gate's child processes. */
+    env?: NodeJS.ProcessEnv;
+    /** Sink for streamed stdout chunks. Defaults to `process.stdout.write`. */
+    onStdout?: (chunk: string) => void;
+    /** Sink for streamed stderr chunks. Defaults to `process.stderr.write`. */
+    onStderr?: (chunk: string) => void;
+}
+export interface RunVerifyResult {
+    /** The exit code of the gate: 0 iff every command passed. */
+    exitCode: number;
+    /** The ordered commands that were run (resolved from config). */
+    commands: string[];
+    /** Whether the gate passed (exitCode === 0). */
+    passed: boolean;
+}
+/**
+ * Run the resolved gate command(s) in `cwd`, streaming output, and resolve with
+ * the gate's status: exit 0 iff every command passed. Commands run in sequence;
+ * the first non-zero exit short-circuits the rest and becomes the result
+ * (mirroring `&&` semantics). Each command is run through `bash -c` so that
+ * shell operators in the declared gate (`&&`, pipes, etc.) behave as written.
+ */
+export declare function runVerify(options: RunVerifyOptions): Promise<RunVerifyResult>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,0DACqB,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,YAAY,GAAG,SAAS,GAC9B,MAAM,EAAE,CAOV;AAED,MAAM,WAAW,gBAAgB;IAChC,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC/B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gDAAgD;IAChD,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC9B,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,eAAe,CAAC,CAiB1B"}

package/dist/verify.js

@@ -0,0 +1,62 @@
+import { spawn } from 'node:child_process';
+/**
+ * The sensible default when no `verify` is configured: build, then test, then
+ * check formatting across the workspace. Deterministic, auditable, no model.
+ */
+export const DEFAULT_VERIFY_COMMAND = 'pnpm -r build && pnpm -r test && pnpm -r format:check';
+/**
+ * Resolve the declared gate into an ordered, non-empty list of shell commands.
+ * Unset ⇒ the default. A string ⇒ a single command. A list ⇒ the list, with
+ * blank/whitespace-only entries dropped (and the default substituted if that
+ * leaves nothing). Each command is run in sequence; all must pass.
+ */
+export function resolveVerifyCommands(verify) {
+    if (verify === undefined) {
+        return [DEFAULT_VERIFY_COMMAND];
+    }
+    const list = Array.isArray(verify) ? verify : [verify];
+    const commands = list.filter((command) => command.trim() !== '');
+    return commands.length > 0 ? commands : [DEFAULT_VERIFY_COMMAND];
+}
+/**
+ * Run the resolved gate command(s) in `cwd`, streaming output, and resolve with
+ * the gate's status: exit 0 iff every command passed. Commands run in sequence;
+ * the first non-zero exit short-circuits the rest and becomes the result
+ * (mirroring `&&` semantics). Each command is run through `bash -c` so that
+ * shell operators in the declared gate (`&&`, pipes, etc.) behave as written.
+ */
+export async function runVerify(options) {
+    const commands = resolveVerifyCommands(options.verify);
+    const onStdout = options.onStdout ?? ((chunk) => process.stdout.write(chunk));
+    const onStderr = options.onStderr ?? ((chunk) => process.stderr.write(chunk));
+    for (const command of commands) {
+        const exitCode = await runOne(command, options.cwd, options.env, {
+            onStdout,
+            onStderr,
+        });
+        if (exitCode !== 0) {
+            return { exitCode, commands, passed: false };
+        }
+    }
+    return { exitCode: 0, commands, passed: true };
+}
+/** Spawn one command via `bash -c`, streaming its output, resolving its code. */
+function runOne(command, cwd, env, sinks) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn('bash', ['-c', command], {
+            cwd,
+            env: env ?? process.env,
+        });
+        child.stdout.on('data', (chunk) => {
+            sinks.onStdout(chunk.toString('utf8'));
+        });
+        child.stderr.on('data', (chunk) => {
+            sinks.onStderr(chunk.toString('utf8'));
+        });
+        child.on('error', (err) => reject(new Error(`failed to spawn gate command: ${err.message}`)));
+        child.on('close', (code) => {
+            resolvePromise(code ?? -1);
+        });
+    });
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/dist/watch-session.d.ts

@@ -0,0 +1,112 @@
+/** The green `✓ agent finished` line, emitted on PROCESS EXIT (not a log event). */
+export declare function finishedLine(color: boolean): string;
+/**
+ * A one-line VISUAL BOUNDARY banner the caller prints between two tailed agent
+ * streams (e.g. the build stream and the Gate-2 review stream — task
+ * `watch-review-session`), so a watching human knows the first stream ended and
+ * the next began. Reuses this module's colour rule (cyan, the same marker hue as
+ * the `▶ <tool>` lines) so it reads as part of the same live view. Pure: returns
+ * the string; the caller routes it to the watch sink.
+ */
+export declare function boundaryLine(label: string, color: boolean): string;
+/**
+ * Parse ONE pi SESSION-LOG `.jsonl` line and return the high-signal lines to
+ * surface — or `[]` to SKIP it. This is the pure, unit-testable classifier,
+ * mirroring pi-remote's `session-pool.ts` block walk:
+ *
+ *   - a `{type:"message", message:{role:"assistant", content}}` record → for each
+ *     `content[]` part: a `text` part yields its text (parts concatenated into
+ *     ONE line, like the old `jq` `.content[]` select); a `toolCall` part yields
+ *     `▶ <name>` (cyan; `name` OR `toolName`, defaulting to `tool`); a `thinking`
+ *     part (and anything else) is skipped. A plain-string `content` yields one
+ *     text line.
+ *   - everything else (`session`/`model_change`/`thinking_level_change`, user
+ *     messages, tool results, blank/malformed lines) → `[]` (skipped).
+ *
+ * "Finished" is NOT a record here — the session log has no `agent_end`; the
+ * tailer emits {@link finishedLine} on process exit instead.
+ *
+ * Malformed JSON is skipped (not thrown): a partially-written trailing line in a
+ * growing log must not crash the observer.
+ */
+export declare function formatWatchEvent(line: string, color: boolean): string[];
+/**
+ * Extract the **last assistant message's text** from a pi session `.jsonl`
+ * (task `harness-agent-output`) — the agent's final ANSWER, surfaced through
+ * the harness seam as `LaunchResult.output`. It REUSES this module's session-log
+ * shape walk (one parser, not two): it scans the `{type:"message",
+ * message:{role:"assistant", content[]}}` records, takes the LAST one carrying
+ * non-empty `text`, and returns its concatenated text.
+ *
+ * Returns `undefined` when the log has no assistant text at all — an absent log,
+ * a malformed/short log, or a run whose only assistant turn was tool-calls (no
+ * `text` part). A tool-only assistant turn is NOT a final answer, so a LATER
+ * text turn (if any) wins; with no text turn anywhere the result is `undefined`.
+ *
+ * Malformed/blank lines are skipped (never thrown): a partially-written trailing
+ * line in a just-closed log must not crash the reader.
+ */
+export declare function lastAssistantText(jsonl: string): string | undefined;
+export interface SessionTailerOptions {
+    /**
+     * The EXACT pi session `.jsonl` file path to tail. The caller generated this
+     * BEFORE pi launched (`--session <path>`, task `session-path-pi-default`) and
+     * passed the SAME path to the adapter, so the tailer reads the run's own log
+     * — no newest-by-mtime dir guessing, no stale-sibling race. The file does NOT
+     * yet exist when the tailer starts (pi creates it asynchronously after spawn);
+     * the tailer polls until it appears (ENOENT is tolerated as "not yet").
+     */
+    sessionFile: string;
+    /** Emit ANSI colour (the caller's TTY/`NO_COLOR` decision). */
+    color: boolean;
+    /** Where formatted high-signal lines are written (defaults to stderr). */
+    sink?: (line: string) => void;
+    /** How often (ms) to poll for new bytes / the log's appearance. */
+    pollIntervalMs?: number;
+}
+/**
+ * A concurrent, READ-ONLY tail of the pi session `.jsonl`. It polls the KNOWN
+ * session-file path (which the pi adapter creates only once pi starts) until it
+ * appears, then reads newly-appended bytes, splits them into complete lines, and
+ * surfaces each via {@link formatWatchEvent}. A partial trailing line is
+ * buffered until its newline arrives, so an event split across two reads is
+ * never mis-parsed.
+ *
+ * It is a pure observer: nothing it does feeds back into the run. `start()`
+ * begins polling; `stop()` performs one final drain (to catch events written
+ * just before the agent exited), emits the `✓ agent finished` line ONCE (the
+ * session log has no `agent_end` — process exit IS the finish signal), and
+ * releases the file handle. Created and driven by `do --watch` ALONGSIDE the
+ * (async) agent launch; `stop()` runs when that launch returns (i.e. the agent
+ * process exited).
+ */
+export declare class SessionTailer {
+    private readonly sessionFile;
+    private readonly color;
+    private readonly sink;
+    private readonly pollIntervalMs;
+    private handle;
+    private offset;
+    private pending;
+    private timer;
+    private polling;
+    private stopped;
+    private finishedEmitted;
+    constructor(options: SessionTailerOptions);
+    /** Begin polling for the known session file and tailing its new bytes. */
+    start(): void;
+    /**
+     * Stop tailing: one final drain (events written right before the agent exited
+     * must still be surfaced), emit the `✓ agent finished` line ONCE (process exit
+     * is the finish signal — the session log carries no `agent_end`), then release
+     * the handle. Idempotent: a second `stop()` re-emits nothing.
+     */
+    stop(): Promise<void>;
+    /** One poll tick: ensure the handle is open, then drain new bytes. */
+    private poll;
+    /** Open the log if not yet open, read appended bytes, surface whole lines. */
+    private drain;
+    /** Split the buffer on newlines, surfacing each COMPLETE line; keep the rest. */
+    private flushLines;
+}
+//# sourceMappingURL=watch-session.d.ts.map

package/dist/watch-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-session.d.ts","sourceRoot":"","sources":["../src/watch-session.ts"],"names":[],"mappings":"AAuEA,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAElE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAyBvE;AAgED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA8BnE;AAED,MAAM,WAAW,oBAAoB;IACpC;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,KAAK,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAID;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,eAAe,CAAS;gBAEpB,OAAO,EAAE,oBAAoB;IAOzC,0EAA0E;IAC1E,KAAK,IAAI,IAAI;IAWb;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B,sEAAsE;YACxD,IAAI;IAclB,8EAA8E;YAChE,KAAK;IA0BnB,iFAAiF;IACjF,OAAO,CAAC,UAAU;CAalB"}