framework/dist/sessions.d.ts

The (AI) Framework: turnkey, zero-config AI orchestration that wraps a coding-agent CLI (Claude Code) as a black box and takes you from an idea to a running app. Vite for AI.

import { SESSIONS_DIR, type StoreFs } from './store/index.js';
import { type GitRunner } from './project.js';
/**
 * Committed session history (#1179): where a project's finished runs are archived so they survive
 * the repo being cleaned.
 *
 * The bug this exists for: run state was written to `.the-framework/runs/`, which the install-time
 * `.gitignore` keeps untracked, so `git clean -fdx` — an ordinary thing to do to a repo — deleted
 * every session a project had ever run. Nothing was recoverable, because nothing had ever been
 * committed.
 *
 * Scoped per user, as `.the-framework/<user>/sessions/`, rather than one shared directory. Two
 * people working the same repo would otherwise write the same paths from different machines and
 * conflict on every merge; under their own directory their histories simply sit side by side. The
 * list being visible to the whole team is the intended outcome, not a leak — see the issue.
 *
 * The identity is the git `user.email` already configured in the repo, so there is nothing new to
 * set up and the directory matches the name on the commits.
 */
/** The directory, under a user's own directory, that holds their archived runs. */
export { SESSIONS_DIR };
/** Where a run's history goes when git has no identity configured. */
export declare const ANONYMOUS_USER_DIR = "anonymous";
/**
 * An email as a directory name: lowercased, with anything outside a conservative set replaced by
 * `-`. The result must start with a letter or digit, which is what rules out `.`, `..` and dotfile
 * names — this value comes from repo configuration and is joined onto a path, so a name that could
 * climb out of the directory is the one thing that must be impossible. Anything that cannot be made
 * to fit falls back to {@link ANONYMOUS_USER_DIR} rather than to a guess.
 */
export declare function userDirName(email: string | undefined): string;
/** The `.the-framework/<user>/sessions` directory under a project root. */
export declare function sessionsDir(cwd: string, user: string): string;
/**
 * The `.the-framework/.gitignore` rules that make every user's sessions tracked. Three lines, not
 * one: the seeded allow-list ignores everything with `*`, and git never descends into an ignored
 * directory, so each directory on the way down has to be re-included before the files under it can
 * be. Same shape as the conversations rules (#908), which this sits beside.
 *
 * User-agnostic on purpose (#1312). Naming each user meant every person who ever ran a session in
 * the repo appended their own three lines to a *tracked* file: their checkout went dirty, the next
 * safety commit swept the edit into a branch, and two machines doing it near each other conflicted.
 * A glob covers everyone, including people who have not run anything yet, so the file is written
 * once and then never again.
 *
 * A star matches one path segment and never a slash, so the sessions rule reaches exactly
 * `<user>/sessions/` and not `worktrees/<run>/sessions/`. The transient siblings stay ignored
 * either way: un-ignoring a directory only lets git descend into it, and the bare `*` still
 * ignores every file it finds there.
 */
export declare function sessionsGitignore(): string;
/**
 * Drop the per-user session rules, keeping every other line.
 *
 * Only users the file actually names a `sessions` rule for are stripped, and only those three
 * exact lines. The conversations rules (#908) are a literal directory name rather than a user, so
 * they never match, and a hand-written rule this does not recognize is left where it is.
 */
export declare function withoutPerUserRules(md: string): string;
/**
 * Make sure `.the-framework/.gitignore` un-ignores archived sessions, returning whether it wrote.
 * Done lazily on archive rather than at install time: the ignore file is seeded once and only when
 * absent, so every repo activated before this feature carries the old allow-list.
 *
 * Writes at most twice in a repo's life, and usually once: a file already on the glob form is left
 * alone, and a file still naming users is upgraded to the glob form in place — the per-user lines
 * come out in the same write that puts the glob in, so the churn (#1312) ends rather than being
 * added to. `user` no longer selects the rules; it stays because the caller has it and a future
 * rule may need it again.
 *
 * Only a file we recognize is touched; anything hand-edited beyond recognition is left alone.
 */
export declare function ensureSessionsIgnored(cwd: string, _user: string, fs?: StoreFs): Promise<boolean>;
export declare function resolveUserDir(cwd: string, git?: GitRunner): Promise<string>;
/** Drop the {@link resolveUserDir} cache. For tests, and for a daemon that outlives a config change. */
export declare function forgetUserDirs(): void;
//# sourceMappingURL=sessions.d.ts.map