@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/module-types/src/project-hooks.d.ts

@@ -0,0 +1,129 @@
+/**
+ * A project's hooks (#1774): the shell lines a project's own `.the-framework/hooks.yml` names to
+ * run when the dashboard opens and when it closes, the two lines that start a run and continue
+ * one, and the line that says whether a run can start here at all. The daemon calls no tool by
+ * name: it runs whatever the file says, in the project, with the project's installed tools and
+ * then the built-in packages' on the PATH, so a line reaches its tool with nothing fetched from npm. Per
+ * user, since `.the-framework/` is ignored: a hook is this machine's, and a teammate's pull
+ * changes nothing.
+ *
+ * Optional, best-effort and bounded: no file means nothing runs, a broken file is a warning, an
+ * `open` or `close` line that fails or hangs is logged and the next line still runs, and nothing
+ * here ever throws to the daemon.
+ */
+/** The hooks file, under the project's ignored `.the-framework/`. */
+export declare const PROJECT_HOOKS_FILE = ".the-framework/hooks.yml";
+/** How long one line may run before it is killed and logged as timed out. */
+export declare const HOOK_TIMEOUT_MS = 60000;
+/** When a project's hooks run: `open` when the dashboard starts (and when the project is added while it runs), `close` when it stops. */
+export type HookKind = 'open' | 'close';
+/**
+ * The two lines a person's click runs to start or continue a run: `start` begins a run from a
+ * prompt, `resume` continues an ended one with a text or an answer. One line each, since each
+ * answers one document on stdout.
+ */
+export type RunHookKind = 'start' | 'resume';
+export interface ProjectHooks {
+    open: string[];
+    close: string[];
+    start?: string;
+    resume?: string;
+    check?: string;
+}
+/**
+ * Read a project's hooks. A missing file is no hooks. A file that cannot be parsed or has the
+ * wrong shape is reported through `onWarn`, prefixed "ignoring", and counts as no hooks.
+ */
+export declare function readProjectHooks(cwd: string, onWarn?: (message: string) => void): Promise<ProjectHooks>;
+/**
+ * Parse the hooks file: a YAML map whose keys are `open` and `close`, each a list of shell lines,
+ * and `start`, `resume` and `check`, each one shell line. An empty document is no hooks. Anything else throws, so the reader can warn: a wrong key is
+ * refused rather than ignored, because a misspelled `open` would otherwise be a hook that
+ * silently never runs.
+ */
+export declare function parseProjectHooks(raw: string, source?: string): ProjectHooks;
+export interface RunHooksOptions {
+    /** Where each line's outcome and the tool's stderr go; default nowhere. */
+    log?: (line: string) => void;
+    /** How long one line may run; default {@link HOOK_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** The environment the lines run with; default the daemon's own. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Run a project's `open` or `close` lines, in order, each through `sh -c` with the project's
+ * root as working directory. A line that exits non-zero, times out or cannot start is logged and
+ * the next line still runs; the lines' stderr is logged too, since a tool's one line for a person
+ * goes there. Never throws.
+ */
+export declare function runProjectHooks(cwd: string, kind: HookKind, opts?: RunHooksOptions): Promise<void>;
+/** What a `start` line is given: the prompt, the coding agent, model, publish level and branch to start from when the person picked them, and the follow-up when there is one. */
+export interface StartHookInput {
+    prompt: string;
+    driver?: string;
+    model?: string;
+    /** A fresh agent's prompt once the run ends done with a pull request; the merge waits for it. */
+    then?: string;
+    /** How far the run takes its work when its agent finishes: `commit`, `branch`, `pr` or `merge`. */
+    publish?: string;
+    /** The branch the run's own branch starts from; origin's default branch when absent. */
+    base?: string;
+}
+/**
+ * Whether a `start` line passes the branch to start from on: it mentions `$BASE` or `${BASE`. A
+ * line is written once and kept, so one written before the pick existed, or a person's own, may
+ * not; the launcher then offers no pick, rather than one the line would drop.
+ */
+export declare function startLineTakesBase(line: string): boolean;
+/** What a `resume` line is given: the run, and the person's text or their answer to the question it ended on. */
+export type ResumeHookInput = {
+    runId: string;
+} & ({
+    text: string;
+} | {
+    answer: string;
+});
+export type RunHookResult = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Run the project's `start` line: the prompt in `PROMPT`, the picks in `DRIVER`, `MODEL`,
+ * `PUBLISH` and `BASE` when made, the follow-up in `THEN` when there is one. The line answers one JSON
+ * document on stdout whose `id` names the run it started.
+ */
+export declare function runStartHook(cwd: string, input: StartHookInput, opts?: Omit<RunHooksOptions, 'log'>): Promise<RunHookResult>;
+/**
+ * Run the project's `resume` line: the run in `RUN_ID`, and the person's words in `TEXT` or their
+ * answer in `ANSWER`. The line answers like a `start` line, naming the run it continued.
+ */
+export declare function runResumeHook(cwd: string, input: ResumeHookInput, opts?: Omit<RunHooksOptions, 'log'>): Promise<RunHookResult>;
+/** What stands in the way of a run: problems stop it, warnings do not. One line each, each naming its fix. */
+export interface StartReadiness {
+    problems: string[];
+    warnings: string[];
+}
+/** How a `check` line went; `noHook` when the project's file names no such line. */
+export type CheckHookResult = ({
+    ok: true;
+} & StartReadiness) | {
+    ok: false;
+    error: string;
+    noHook?: true;
+};
+/**
+ * Run the project's `check` line: the coding agent the person picked in `DRIVER`, when picked.
+ * The line answers one JSON document on stdout with `problems` and `warnings`, lists of lines.
+ */
+export declare function runCheckHook(cwd: string, input: {
+    driver?: string;
+}, opts?: Omit<RunHooksOptions, 'log'>): Promise<CheckHookResult>;
+/**
+ * The environment a line runs with: the PATH led by the project's installed tools, then the
+ * built-in packages' own commands, so a tool named in a line is the project's copy when it
+ * installed one and the dashboard's otherwise, and never a package fetched by name.
+ */
+export declare function hookEnv(cwd: string, env: NodeJS.ProcessEnv): Promise<NodeJS.ProcessEnv>;

package/dist/module-types/src/project-modules.d.ts

@@ -0,0 +1,49 @@
+import { type PackageCommandResult } from '@openagt/agent-data';
+/**
+ * A package that adds to the dashboard (#1774): its browser part, named by its
+ * `exports["./dashboard"]`, and optionally its server part, named by `exports["./server"]`. The
+ * framework names no package: any dependency of the project that exports `./dashboard` is a
+ * module, whoever wrote it, and the framework's own built-in modules come the same way.
+ */
+export interface ProjectModule {
+    /** The package's name, as the project's package.json lists it. */
+    package: string;
+    /** The package's version, when its package.json says one. */
+    version?: string;
+    /** The directory the module's browser part sits in, symlinks resolved: the only directory served for it. */
+    dir: string;
+    /** The module's browser part's file name inside {@link dir}. */
+    entry: string;
+    /** The package's commands, by name, as absolute paths: what the module may run in this project. */
+    bins: Record<string, string>;
+    /** The module's server part, an absolute path inside the package, when it has one. */
+    server?: string;
+}
+/**
+ * The modules a project has: each of its dependencies whose package.json exports `./dashboard` to
+ * a file that exists inside the package, plus the modules among the framework's built-in packages (`built-in.ts`). A project that
+ * depends on a built-in module's package itself gets its own copy. Sorted by name.
+ */
+export declare function readProjectModules(root: string): Promise<ProjectModule[]>;
+/** The one module of this project that `name` names, or undefined. */
+export declare function findProjectModule(root: string, name: string): Promise<ProjectModule | undefined>;
+/**
+ * The file a module serves at `rel`, a path relative to its module's directory: its module, its
+ * stylesheet, a chunk. `undefined` for a path that leaves that directory (symlinks resolved) or
+ * names no file, so nothing else of the package, and nothing of the project, is ever served.
+ */
+export declare function moduleFile(module: ProjectModule, rel: string): Promise<string | undefined>;
+/** What a module's command answered: its JSON output, or why there is none. */
+export type ModuleCommandResult = PackageCommandResult;
+/**
+ * Run one of a module package's own commands in the project, with the given arguments, and read
+ * its standard output as JSON. This is how a module reads its data: the same command an agent runs
+ * (`npx logs`), so the module and the agent see the same thing and the framework knows neither.
+ *
+ * `command` picks one of the package's commands; a package with exactly one needs none. The
+ * command runs with Node (a package's commands are Node scripts), in the project root, never
+ * through a shell, bounded in time and output. Refused: a command the package does not have, too
+ * many or too long arguments. A command that exits non-zero answers its last stderr line; one that
+ * prints no JSON says so.
+ */
+export declare function runModuleCommand(root: string, module: ProjectModule, args: readonly string[], command?: string): Promise<ModuleCommandResult>;

package/dist/module-types/src/project-presets.d.ts

@@ -0,0 +1,29 @@
+import { type CustomPreset } from './registry.js';
+import { type StoreFs } from './store/index.js';
+/**
+ * Project-scoped custom presets (#1025).
+ *
+ * The user tier (#626) saves a custom preset to the user's home file, so it follows the person
+ * across every project and stays private. The project tier saves it into the repo instead, so it
+ * travels with the code and everyone who clones the repo gets it — the "share your presets" half
+ * of the issue.
+ *
+ * The store is a plain JSON array of {@link CustomPreset}, the exact shape the user tier uses, so
+ * the dashboard renders both from one type and the same sanitizer guards both files.
+ */
+/** The committed file holding a project's shared custom presets, under `.the-framework/`. */
+export declare const PROJECT_PRESETS_FILE = ".the-framework/custom-presets.json";
+/**
+ * Read a project's shared custom presets. Forgiving like every other read here: a missing,
+ * unreadable or malformed file yields `[]`, never throws, and the same sanitizer that guards
+ * the home file drops any hand-edited or hostile entry.
+ */
+export declare function readProjectPresets(cwd: string, fs?: StoreFs): Promise<CustomPreset[]>;
+/**
+ * Write a project's shared custom presets, sanitizing first so the committed file is always
+ * well-formed. Also ensures `.the-framework/.gitignore` un-ignores the file: the dir's ignore is
+ * `*` + `!.gitignore` (nothing else is tracked by default), so without a negation git would
+ * never see the presets and they could not be shared. Removing every preset writes an empty array
+ * rather than deleting the file, so the negation stays in place for the next save.
+ */
+export declare function writeProjectPresets(cwd: string, presets: CustomPreset[], fs?: StoreFs): Promise<void>;

package/dist/module-types/src/project.d.ts

@@ -0,0 +1,28 @@
+import { type GitRunner } from '@openagt/agent-data';
+/**
+ * Project-level repo helpers (#380): the activation marker check and a
+ * `git ls-files` crawl. Read-only
+ * building blocks for the sidebars (#314); activation/install (writing the
+ * marker, the install commit) is a separate, deferred concern.
+ */
+/** Minimal fs seam so activation is unit-testable without touching disk. */
+export interface ProjectFs {
+    /** True when `path` exists AND is a file. */
+    exists(path: string): Promise<boolean>;
+}
+/**
+ * A repo is "activated"/installed for The Framework when it has the
+ * `.the-framework/.gitignore` install writes — the same marker install's own
+ * no-op check reads (#1600), so a `.the-framework/` directory something else
+ * created can never read as activated while the repo still lacks the ignore
+ * file that keeps framework state off its branches. Read-only check; writing
+ * the marker + the install commit is a separate, deferred concern.
+ */
+export declare function isActivated(cwd: string, fs?: ProjectFs): Promise<boolean>;
+/**
+ * List every file git sees in the repo at `cwd`: tracked + untracked, honoring
+ * .gitignore. Uses `git ls-files -z --cached --others --exclude-standard` (the
+ * same approach Vike uses). Returns repo-relative paths, deduped and sorted.
+ * Forgiving: a non-repo / missing git / any failure yields `[]`, never throws.
+ */
+export declare function crawlRepoFiles(cwd: string, agent?: GitRunner): Promise<string[]>;

package/dist/module-types/src/publish-levels.d.ts

@@ -0,0 +1,32 @@
+/**
+ * How far a run takes its work when its agent finishes, node-free so every surface shares
+ * one copy: the registry's preference sanitizer, the daemon's Start and the dashboard bundle.
+ * The levels are the words a project's start hook is handed as `PUBLISH`, the ones
+ * `agent-runner run --publish` takes. The launcher's menu offers them after "Nothing", the pick
+ * that hands the hook no level: the run then commits and publishes nothing unless its prompt asks.
+ * Until a person picks, a run goes as far as it can without a pull request: its branch pushed, or
+ * its work committed where the project has no remote.
+ */
+/** The levels a run can be started at, each going further than the one before. */
+export declare const PUBLISH_LEVELS: readonly ['commit', 'branch', 'pr', 'merge'];
+/** A level: commit the work, and from there push the branch, open its pull request, or open it set to merge once its checks pass. */
+export type PublishLevel = (typeof PUBLISH_LEVELS)[number];
+/** What the launcher's menu lists, in its order: nothing, then each level. */
+export declare const PUBLISH_PICKS: readonly ["nothing", "commit", "branch", "pr", "merge"];
+/** A pick of the launcher's menu. */
+export type PublishPick = (typeof PUBLISH_PICKS)[number];
+export declare const PUBLISH_LABELS: Readonly<Record<PublishPick, string>>;
+export declare function isPublishPick(value: unknown): value is PublishPick;
+/**
+ * The picks a project is offered: every one where it has a git host; without a git host no pull
+ * request can be opened, so the picks stop at the branch; without a remote nothing can be
+ * published at all, so they stop at the commit.
+ */
+export declare function offeredPublishPicks(gitHost: boolean, remote?: boolean): readonly PublishPick[];
+/**
+ * The saved pick as this project can hold it: a pick it is not offered falls back to the furthest
+ * it goes with no pull request, which is also the pick in force until a person saves one.
+ */
+export declare function publishPickIn(saved: PublishPick | undefined, gitHost: boolean, remote?: boolean): PublishPick;
+/** The level a pick hands the start hook; none for Nothing. */
+export declare function publishLevelOf(pick: PublishPick): PublishLevel | undefined;

package/dist/module-types/src/quota-boundary.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The quota boundary (#879): how much of the account's week The Framework may
+ * have spent by now.
+ *
+ * The whole policy is one line — the boundary is the pro-rated share of the week's allowance that
+ * has elapsed, rising continuously with the clock rather than once a day (#960 Edit) — and it
+ * replaces the configurable limits of #519. There is nothing to configure: the boundary is derived
+ * from the account's own week, which the agent reports.
+ *
+ * Nothing is left on the floor: the boundary rises on its own and reaches the full allowance
+ * exactly as the week resets, so a quiet week still gets spent rather than expiring.
+ *
+ * The Framework only draws it. Whether work stops at it, or how far past it, is the business of
+ * whatever starts unattended work, which puts its own stop line on the usage bar.
+ */
+import type { DriverQuotaWindow } from '@openagt/agent-driver';
+/** The quota week, in ms. */
+export declare const QUOTA_WEEK_MS: number;
+/** Where the boundary sits, and the week it is derived from. */
+export interface QuotaBoundary {
+    /** When the current quota week began, epoch ms. */
+    startsAt: number;
+    /** When it resets, epoch ms. */
+    resetsAt: number;
+    /** Which day of the week we are on, 1-7. */
+    day: number;
+    /** The share of the week's allowance that may be spent by now, 0-100. */
+    percent: number;
+}
+/**
+ * Parse the agent's reset prose into an epoch.
+ *
+ * The agent prints no year (`Jul 25 at 7am (Asia/Jerusalem)`), which is why the
+ * driver keeps this as text. It is recoverable here because we know something
+ * the driver does not: a *weekly* window resets within seven days, so of the
+ * candidate years exactly one lands anywhere near now.
+ *
+ * `undefined` for anything that does not parse, which the callers treat as "we
+ * do not know where the week is" rather than as a boundary of zero.
+ */
+export declare function parseResetsAt(text: string, now: number): number | undefined;
+/**
+ * Where the boundary sits, given when the week resets.
+ *
+ * `percent` is continuous — the plain elapsed share of the week (#960 Edit) — rather than a value
+ * that jumps once a day, so it always names the actual instant `now` falls on, on any axis that
+ * measures the week the same way. A stepped version once unlocked a whole day's allowance the
+ * moment a new day began (including the entire week's worth on the last day), which read as
+ * generous on paper but let a burst of spending land the instant the clock ticked over rather than
+ * pacing with it; continuous keeps the line honest about what has actually elapsed at the cost of
+ * that burst.
+ *
+ * `day` is 1-based and still names which day of the week `now` falls on — for callers that want to
+ * say "day 4 of 7" rather than a percentage — and steps at the exact second the week's own day
+ * rolls over, independently of `percent`.
+ */
+export declare function boundaryFromResetsAt(resetsAt: number, now: number): QuotaBoundary;
+/**
+ * Where the boundary sits for the account's own week, as the agent reported it (#879).
+ *
+ * `undefined` when there is no reading of the week, or when its reset cannot be placed. That is
+ * "we do not know", never a boundary of zero.
+ */
+export declare function weekBoundary(windows: readonly DriverQuotaWindow[], now: number): QuotaBoundary | undefined;

package/dist/module-types/src/quota-poller.d.ts

@@ -0,0 +1,82 @@
+import { type DriverQuota } from '@openagt/agent-driver';
+/**
+ * How often to read the quota when everything is healthy. A read spawns the
+ * whole agent CLI (~5s), and the agent's own usage fetch is refused upstream if
+ * asked too often, so this is deliberately slow: the boundary moves over days,
+ * which a 5-minute sample rate resolves comfortably.
+ */
+export declare const DEFAULT_POLL_MS: number;
+/** Longest gap between reads once backoff has stretched it. */
+export declare const MAX_POLL_MS: number;
+/**
+ * What the poller currently believes about the account's quota.
+ *
+ * `latest` is the last attempt as it came back; `lastGood` is the last real
+ * reading. The two are separate so a transient blip doesn't blank a number that
+ * was accurate a minute ago — a bar going empty reads as "nothing used", which
+ * is the one thing this feature must never imply.
+ */
+export interface QuotaEnvelope {
+    /** The most recent attempt, exactly as it came back. `undefined` before the first. */
+    latest: DriverQuota | undefined;
+    /** The most recent successful reading, retained across transient failures. */
+    lastGood: (DriverQuota & {
+        available: true;
+    }) | undefined;
+    /** When {@link lastGood} was read, epoch ms. */
+    lastGoodAt: number | undefined;
+    /** When the last failure happened, epoch ms. */
+    lastFailureAt: number | undefined;
+}
+/** Options for {@link QuotaPoller}. */
+export interface QuotaPollerOptions {
+    /** Read the quota once. Normally `driver.readQuota`. */
+    read: () => Promise<DriverQuota>;
+    /** Healthy interval. Default {@link DEFAULT_POLL_MS}. */
+    intervalMs?: number;
+    /** Ceiling for the backed-off interval. Default {@link MAX_POLL_MS}. */
+    maxIntervalMs?: number;
+    /** Clock, injectable for tests. */
+    now?: () => number;
+}
+/**
+ * Keeps a recent quota reading on hand (#525).
+ *
+ * Polling is slow by design and backs *off* on failure rather than retrying
+ * into it: the agent's usage fetch is refused upstream when asked too often,
+ * and the penalty window is minutes long, so an eager retry loop would keep the
+ * number permanently unavailable — the opposite of the goal.
+ */
+export declare class QuotaPoller {
+    private readonly opts;
+    private envelope;
+    private timer;
+    private running;
+    private currentIntervalMs;
+    private stopped;
+    private readonly now;
+    constructor(opts: QuotaPollerOptions);
+    /** What we currently believe. */
+    current(): QuotaEnvelope;
+    /** The gap before the next read, which grows while the fetch keeps being refused. */
+    get intervalMs(): number;
+    /** Whether the poller has given up (an authoritative failure, or {@link stop}). */
+    get isStopped(): boolean;
+    /**
+     * Read once, now, and fold the result in. Safe to call on demand (e.g. right
+     * after a turn settles) alongside the timer.
+     */
+    poll(): Promise<DriverQuota>;
+    /**
+     * Begin polling, starting with a read right now rather than one interval from
+     * now: a poller whose first reading lands five minutes in is no use to an agent
+     * that just started, and the session's own measurement needs a baseline. Not
+     * awaited — the read takes ~5s and nothing should wait on it. Idempotent.
+     */
+    start(): void;
+    /** Stop polling. Idempotent. */
+    stop(): void;
+    private onGood;
+    private onBad;
+    private schedule;
+}

package/dist/module-types/src/registry.d.ts

@@ -0,0 +1,220 @@
+import { type PublishPick } from './publish-levels.js';
+/**
+ * The multi-project registry (#390): the list of projects the user has
+ * installed The Framework into, kept as a single JSON file `.bashrc`-style —
+ * `$HOME/.the-framework.json` — so it is the user's responsibility to re-create
+ * per machine. The same file also holds the user's dashboard preferences (#410),
+ * so the daemon owns one user file and the UI never needs localStorage.
+ */
+/** One registered project. */
+export interface ProjectRecord {
+    /** Stable, URL-safe id derived from the path. */
+    id: string;
+    /** Absolute repo path. */
+    path: string;
+    /** ISO timestamp the project was added. */
+    addedAt: string;
+}
+/**
+ * The dashboard's Global options (#410), persisted next to the project list so they
+ * survive restarts without localStorage — the daemon reads/writes them, the SPA reads
+ * them over `POST /_rpc/onPreferences`. Mostly flat booleans mirroring the Start form's
+ * toggles; every field is optional and absent means off, except where a field documents its
+ * own default below.
+ */
+/**
+ * A user-defined preset (#626): a named prompt the user saved to re-run their own high-signal
+ * prompts, listed as a saved prompt in the launcher's Commands menu beside the project's commands.
+ * Just data — the label is the menu item, the prompt is loaded verbatim into the editor. `id` is
+ * stable so edits/deletes address one.
+ */
+export interface CustomPreset {
+    id: string;
+    label: string;
+    prompt: string;
+}
+export interface Preferences {
+    /** Fire a browser notification when a new item lands on the "needs you" queue (#627). Absent = on. */
+    notifyBrowser?: boolean;
+    /**
+     * Also notify on plain agent activity — an agent started, an agent finished (#627). The default-off
+     * counterpart to the always-on "needs you" notifications: it keeps you loosely informed of the
+     * pipeline moving even when nothing needs you. A *category* toggle: it composes with the method
+     * toggle {@link notifyBrowser}.
+     */
+    notifyNewActivity?: boolean;
+    /**
+     * The "needs you" category (#627): notify when an agent is awaiting your answer or a PR is ready
+     * to review. A *category* toggle, like {@link notifyNewActivity}, composing with the method
+     * toggle {@link notifyBrowser}. **Absent = on**: unlike the other
+     * flat opt-in booleans, human-intervention pings are the baseline The Framework leans on, so an
+     * unset preference keeps them firing; a user turns them off explicitly.
+     */
+    notifyHumanIntervention?: boolean;
+    /** The model to run on (#628), e.g. `opus` / `sonnet`, handed to the project's start hook. Absent = the hook's own default. */
+    model?: string;
+    /** Which coding agent a run starts on (#650): `claude-code` or `codex`, handed to the project's start hook. Absent = the hook's own default. */
+    driver?: string;
+    /** How far a run started from the dashboard publishes its work: `nothing`, or the level handed to the project's start hook, `commit`, `branch`, `pr` or `merge`. The launcher's menu shows it and writes it. Absent = none saved: the daemon decides where a Start goes. */
+    publish?: PublishPick;
+    /**
+     * Where an agent started from the launcher starts, per project: the projects, by id, whose
+     * launcher is set to "My local branch" (the branch the project's folder is on, as this machine
+     * has it). The launcher's "start from" chip shows it and writes it. **A project not listed
+     * starts from its main branch**, so the default stores nothing.
+     */
+    startFrom?: Record<string, 'local'>;
+    /**
+     * Post-merge cleanup: a run started from the launcher, in a project that has the
+     * `post-merge-cleanup` command, is followed by a fresh agent running it on the run's branch
+     * before the run's pull request merges. The default of the launcher's box, which writes it
+     * too. **Absent = off.**
+     */
+    postMergeCleanup?: boolean;
+    /** Preferred editor for "Open in editor" (#727): an editor CLI (e.g. `code`, `cursor`, `zed`).
+     * Absent falls back to `$FRAMEWORK_EDITOR`, then `code`. */
+    editor?: string;
+    /** Dashboard color theme (#725): `system` (follow the OS, the default), `light`, or `dark`. Absent = system. */
+    theme?: 'system' | 'light' | 'dark';
+    /**
+     * The browser bridge (#1237): let an extension running in the user's own Claude session report
+     * the question a Claude web agent is parked on, so it shows in the dashboard rather than only on
+     * claude.ai. **Absent = off.** It opens the daemon's one route reachable from another origin,
+     * so it is opt-in rather than a baseline, and turning it on is what mints the bridge token.
+     */
+    bridge?: boolean;
+    /**
+     * The bridge browser (#1332): let the daemon run its own Chrome for Testing with the bridge
+     * extension installed, signed in once and kept minimized, so web runs stop depending on the
+     * user's own Chrome being open. **Absent = off**: it downloads a browser and keeps a signed-in
+     * claude.ai session on disk, neither of which should happen unasked. Needs {@link bridge}.
+     */
+    bridgeBrowser?: boolean;
+    /** User-defined presets (#626): the user's own saved prompts, shown in the Commands menu beside the project's commands. */
+    customPresets?: CustomPreset[];
+    /**
+     * Whether the Overview's Onboarding checklist has been dismissed (#958). Absent = show it,
+     * so a fresh install is walked through setup; dismissing only hides it on the Overview, and
+     * the same checklist stays available on the settings page.
+     */
+    onboardingDismissed?: boolean;
+}
+/** The persisted registry file shape (#410): the project list plus the user preferences. */
+export interface Registry {
+    projects: ProjectRecord[];
+    preferences: Preferences;
+    /**
+     * The shared daemon token (#1051): generated on the first non-loopback bind and reused after.
+     * A top-level field, deliberately not a {@link Preferences} one, so it is never shipped to the
+     * browser bundle. Absent on a loopback-only machine.
+     */
+    daemonToken?: string;
+}
+/** A read/write handle for the user preferences, wired into the dashboard's context by the daemon. */
+export interface PreferencesStore {
+    read(): Promise<Preferences>;
+    save(preferences: Preferences): Promise<void>;
+    /**
+     * Merge only the keys the caller changed (#1148) and hand back the stored result. Preferred over
+     * {@link save}, which replaces the whole block from a snapshot that may already be stale.
+     */
+    patch(patch: Preferences): Promise<Preferences>;
+}
+/** The registry file name: a single file under `$XDG_CONFIG_HOME` (dotted under `$HOME`). */
+export declare const REGISTRY_FILE = "the-framework.json";
+/** Owner read/write only: the file holds the daemon token (#1051). */
+export declare const REGISTRY_FILE_MODE = 384;
+/**
+ * Deterministic, URL-safe id for a project path: the sanitized basename plus a
+ * short hash of the full path, so two repos named alike still get distinct ids.
+ * Pure; same path always yields the same id.
+ */
+export declare function projectId(path: string): string;
+/**
+ * The registry file path, resolved from `env` (injectable so tests never touch
+ * the real home): `$XDG_CONFIG_HOME/the-framework.json` when set, else the
+ * dotted `$HOME/.the-framework.json`. A single file, not a directory (#390).
+ */
+export declare function registryPath(env: NodeJS.ProcessEnv): string;
+/** Minimal fs seam so the registry is unit-testable without touching disk. */
+export interface RegistryFs {
+    /** Rejects when the file is absent. */
+    read(path: string): Promise<string>;
+    write(path: string, contents: string): Promise<void>;
+    /** Recursive; used on the registry file's parent dir. */
+    mkdir(path: string): Promise<void>;
+    /**
+     * Replace `to` with `from`, atomically. Optional only so an existing implementation of this
+     * seam keeps compiling; without it {@link writeRegistry} falls back to the truncate-then-write
+     * this method exists to avoid (#991).
+     */
+    rename?(from: string, to: string): Promise<void>;
+    /**
+     * Narrow a file's permissions. Optional, and best-effort at the call site: this file holds the
+     * daemon token (#1051), so it is written owner-only — but a
+     * filesystem that cannot express that (Windows, a FAT volume) must not fail the write.
+     */
+    chmod?(path: string, mode: number): Promise<void>;
+}
+/** A {@link RegistryFs} backed by `node:fs/promises`. See {@link nodeFs}. */
+export declare function nodeRegistryFs(): RegistryFs;
+/**
+ * Keep only well-formed custom presets (#626): each needs a non-empty id, label, and prompt;
+ * label/prompt are trimmed and length-capped, the list capped at {@link CUSTOM_PRESET_LIMITS.count},
+ * and duplicate ids dropped. A malformed entry is skipped, not thrown — a bad registry never breaks the read.
+ */
+export declare function sanitizeCustomPresets(value: unknown): CustomPreset[];
+/**
+ * Read the whole registry. Forgiving: a missing / unreadable / malformed file — or one in a shape
+ * this no longer writes — yields an empty registry, never throws. Projects are deduped by resolved
+ * path and unknown preference fields are dropped.
+ */
+export declare function readRegistry(fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<Registry>;
+/**
+ * Read the registry's project list. Forgiving: a missing / unreadable / malformed
+ * file yields `[]`, never throws. Deduped by resolved path, first wins.
+ */
+export declare function listProjects(fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<ProjectRecord[]>;
+/**
+ * Register a project. Idempotent by resolved path: when the path is already
+ * registered, the existing record is returned untouched (addedAt survives);
+ * otherwise the new record is appended and the file written back (preferences preserved).
+ */
+export declare function addProject(path: string, addedAt: string, fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<ProjectRecord>;
+/** The user's dashboard preferences (#410), or `{}` when none are stored. */
+export declare function readPreferences(fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<Preferences>;
+/** Persist the dashboard preferences (#410), sanitized, preserving the project list. */
+export declare function writePreferences(preferences: Preferences, fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<void>;
+/**
+ * Merge `patch` over the stored preferences (#1148) and return the result.
+ *
+ * The counterpart to {@link writePreferences}, which replaces the whole block: a client that
+ * sends its entire snapshot replays every value it happens to hold, so a dashboard tab opened
+ * before someone else's change silently reverted it on the tab's next write, whatever key that
+ * write was actually about. Sending only the changed keys makes a write touch only what it names.
+ *
+ * Clearing needs no sentinel: {@link sanitizePreferences} already drops blank strings and empty
+ * lists, so `{ editor: '' }` merges in as blank and comes out absent, which is how the dashboard
+ * clears the editor today.
+ */
+export declare function patchPreferences(patch: Preferences, fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<Preferences>;
+/**
+ * The shared daemon token (#1051): read the persisted one, or generate + persist it now. Called
+ * only on a non-loopback bind, so a loopback-only machine never grows one. Serialized with the
+ * other mutators so two concurrent binds can't each write a different token. `base64url` of 32
+ * random bytes: URL-safe, so it drops straight into a `?token=` without encoding.
+ */
+export declare function ensureDaemonToken(fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<string>;
+/** The persisted daemon token (#1051), or `undefined` when none exists. A pure read, so a process
+ * that only prints the reachable URL never generates one. */
+export declare function readDaemonToken(fs?: RegistryFs, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+/** A {@link PreferencesStore} bound to the real registry file, wired by the daemon so the
+ * dashboard's preferences RPCs read/write the user's home file.
+ *
+ * `onChange` is handed **the keys the caller wrote**, not the merged result, so a listener can
+ * tell "this write switched the setting on" from "it was already on and something else changed"
+ * (#1161). It runs after the write has landed, and its failure is swallowed: the save succeeded,
+ * and a listener must not be able to report otherwise: a setting saved in the browser has to
+ * reach the daemon's own services without a restart.
+ */
+export declare function registryPreferencesStore(fs?: RegistryFs, env?: NodeJS.ProcessEnv, onChange?: (written: Preferences) => void): PreferencesStore;