@khorsheed/dsh-game 0.0.0-stage → 0.1.0

package/lib/types/store.d.ts

@@ -0,0 +1,325 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import { type BrowserChecker } from './checks.ts';
+import { type TrashMover } from './trash.ts';
+import { type CreateRequest } from './project.ts';
+import { type BundleFile, type CommitResult, type VersionSource, type WorkingChanges, type DeleteProjectResult, type CheckRecord, type GameResult, type PlayBundle, type ProjectCard, type ProjectRow, type ProjectView, type TurnReport, type SessionGameState, type VersionDiff, type VersionRecord } from './types.ts';
+/** Plugin config; every key optional. */
+export interface GameConfig {
+    /** Registry root override (default `$DSH_HOME/state/game`). */
+    stateRoot?: string;
+    /** Chrome executable for the checks (default: `CHROME_PATH`, then common install paths). */
+    chromePath?: string;
+}
+/**
+ * Resolve the registry root: explicit value, then `$DSH_HOME/state/game`,
+ * then `<cwd>/.dsh-game` (the canvas precedent).
+ */
+export declare function resolveGameStateRoot(configured: string | undefined): string;
+/** A project's state when a turn started, for the turn report. */
+export interface TurnBaseline {
+    readonly at: number;
+    readonly projectId: string;
+    readonly files: ReadonlyMap<string, string>;
+    readonly elements: ReadonlyMap<string, {
+        name: string;
+        json: string;
+        look: string;
+        fields: Record<string, string>;
+    }>;
+    readonly params: Readonly<Record<string, number>>;
+    readonly current: number | undefined;
+    readonly candidate: number | undefined;
+}
+/** The writer the store creates the first files with (specs swap in plain node). */
+export type FenceWriter = (path: string, content: string, session: Session) => Promise<void>;
+/** One end-of-turn evaluation's outcome, as the hook acts on it. */
+export type TurnCheckOutcome = {
+    readonly kind: 'skip';
+} | {
+    readonly kind: 'pass';
+    readonly record: CheckRecord;
+    readonly deployed: VersionRecord | null;
+    readonly candidate: VersionRecord | null;
+} | {
+    readonly kind: 'fail';
+    readonly record: CheckRecord;
+};
+/** The game service core. */
+export declare class GameService {
+    private readonly ctx;
+    static inject: string[];
+    readonly stateRoot: string;
+    private readonly sandboxPolicy;
+    private readonly checker;
+    /** Serializes registry read-modify-write cycles. */
+    private registryLock;
+    private readonly listeners;
+    /**
+     * @param ctx - host context (the mounted `ctx.fs`; `sandboxPolicy` probed).
+     * @param config - plugin config.
+     * @param deps - seams the specs replace.
+     */
+    constructor(ctx: Context, config?: GameConfig, deps?: {
+        checker?: BrowserChecker;
+        writer?: FenceWriter;
+        trash?: TrashMover;
+    });
+    /** Where a deleted project folder goes (the system trash; specs swap a fake). */
+    private readonly trash;
+    /** Release the checker's browser. */
+    dispose(): Promise<void>;
+    /** Subscribe to project changes (the Remote face forwards nothing yet; specs and hooks use it). */
+    subscribe(listener: (projectId: string) => void): () => void;
+    private notify;
+    /** Default fenced write: the mounted fs, stamped with the caller's policy. */
+    private writeFenced;
+    /** Whether the session may have the plugin write into its workspace. */
+    private writable;
+    private registryPath;
+    private readRegistry;
+    /** Read-modify-write the registry under the lock. */
+    private updateRegistry;
+    /** Every registered project, most recently updated first. */
+    listProjects(): Promise<ProjectRow[]>;
+    /** Element files parsed per id, for turn diffs. */
+    private elementIndex;
+    /** Snapshot the bound project when a turn starts (undefined when unbound). */
+    turnBaseline(sessionId: string): Promise<TurnBaseline | undefined>;
+    private turnsPath;
+    /**
+     * Compare the project with its turn-start snapshot and store what the turn
+     * changed. Nothing is stored for a turn that changed nothing.
+     */
+    recordTurn(sessionId: string, turn: number, base: TurnBaseline): Promise<TurnReport | undefined>;
+    /** A stored turn report. */
+    turnReport(sessionId: string, turn: number): Promise<TurnReport | null>;
+    /** Every project as a switcher card (manifest summary, live version, last screenshot), most recent first. */
+    projectCards(): Promise<ProjectCard[]>;
+    /** The project a session is bound to, if any. */
+    boundProject(sessionId: string): Promise<ProjectRow | undefined>;
+    /** Bind a session to a project (or unbind with null). */
+    bind(sessionId: string, projectId: string | null): Promise<GameResult>;
+    private touch;
+    /**
+     * Register an existing folder that holds a `game.json` (a project copied
+     * in, or one whose registry row was lost).
+     */
+    adopt(root: string): Promise<GameResult<{
+        readonly ok: true;
+        readonly project: ProjectRow;
+    }>>;
+    /**
+     * Delete a project from the panel. `trash` takes it out of the plugin
+     * (registry row and every session binding) AND moves its folder to the
+     * system trash — complete, yet recoverable; `forget` only takes it out of
+     * the plugin and leaves the folder (re-adopt with `game_open path`).
+     *
+     * Guards, checked before anything changes: the folder must still hold the
+     * project's own `game.json` (never trash an arbitrary directory a registry
+     * row happens to point at), must not be the calling session's workspace
+     * itself, and a read-only session may do neither. A failed move changes
+     * nothing, so the panel can offer `forget` instead.
+     */
+    deleteProject(projectId: string, mode: 'trash' | 'forget', session: Session | undefined): Promise<DeleteProjectResult>;
+    /**
+     * Create a project in the session's workspace behind the light gate, and
+     * bind the session to it.
+     * @param request - the gate's inputs.
+     * @param session - the calling session (its workspace and fence).
+     * @returns the new row, the gate's missing items, or a failure.
+     */
+    create(request: CreateRequest, session: Session): Promise<{
+        ok: true;
+        project: ProjectRow;
+    } | {
+        ok: false;
+        missing: readonly string[];
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    private row;
+    /**
+     * Everything the panel and `game_read` show about one project.
+     * @param projectId - registry id.
+     * @returns the view, or undefined for an unknown id.
+     */
+    view(projectId: string): Promise<ProjectView | undefined>;
+    /** Elements the waiting candidate changed or added against the live version (null without both). */
+    private candidateDiff;
+    /** The tab's state for one session. */
+    sessionState(sessionId: string): Promise<SessionGameState>;
+    /**
+     * One build file as it is in the working folder now (a model the user just
+     * exported, say), for a panel preview ahead of any version. Build files only,
+     * inside the project, 8 MB at most.
+     */
+    workingFile(projectId: string, path: string): Promise<GameResult<{
+        readonly ok: true;
+        readonly file: BundleFile;
+    }>>;
+    /** The files of a deployed (or candidate) version, for the play area. */
+    bundle(projectId: string, which?: 'current' | 'candidate'): Promise<GameResult<{
+        readonly ok: true;
+        readonly bundle: PlayBundle;
+    }>>;
+    /** One specific version's files. */
+    versionBundle(projectId: string, version: number): Promise<GameResult<{
+        readonly ok: true;
+        readonly bundle: PlayBundle;
+    }>>;
+    /** The kit a snapshot was built for: its own `game.json`'s runtime. */
+    private snapshotKit;
+    /** The kit a project runs on now (its working `game.json`). */
+    private kitFor;
+    /** The build and test files as they are on disk now, plus their fingerprint. */
+    private snapshot;
+    /**
+     * The end-of-turn evaluation for a bound session: skip when nothing
+     * playable changed since the last check, else run the checks, persist the
+     * record, and on a pass deploy (auto-confirm) or leave a candidate.
+     * @param session - the session whose turn is closing.
+     * @param attempt - which automatic fix round this is (0 = the turn's own work).
+     * @param cap - the fix-round cap (a failure at the cap is recorded as given up).
+     * @returns what the hook should do.
+     */
+    checkTurn(session: Session, attempt: number, cap: number, by?: VersionSource): Promise<TurnCheckOutcome>;
+    /**
+     * 提交为新版本: the user commits the panel edits sitting in the working
+     * files. Runs the same checks as the end of a turn (no fix cap — nothing
+     * is steered); a pass cuts the version, whose note lists the edits.
+     */
+    commit(projectId: string, session: Session | undefined): Promise<GameResult<CommitResult>>;
+    private checkRow;
+    private nextVersion;
+    private copyVersion;
+    /** Keep the newest versions plus whatever current/candidate point at. */
+    private prune;
+    /** Promote the candidate to current (the user's 确认 when auto-confirm is off). */
+    confirm(projectId: string, session: Session | undefined): Promise<GameResult<{
+        readonly ok: true;
+        readonly version: number;
+    }>>;
+    /**
+     * Turn auto-confirm on or off in `game.json` (the panel's switch). The
+     * manifest is the project's own file, so this goes through node behind the
+     * same writable check.
+     */
+    setAutoConfirm(projectId: string, on: boolean, session: Session | undefined): Promise<GameResult>;
+    /** Throw the candidate away (the user's 退回); the model hears about it on the next send. */
+    reject(projectId: string, reason: string, session: Session | undefined): Promise<GameResult>;
+    /** Put an older version back into the play area. */
+    rollback(projectId: string, version: number, session: Session | undefined): Promise<GameResult>;
+    /** Files that differ between two versions' snapshots. */
+    diff(projectId: string, from: number, to: number): Promise<GameResult<{
+        readonly ok: true;
+        readonly diff: VersionDiff;
+    }>>;
+    private userLayer;
+    private saveUserLayer;
+    /** Add (or replace by key) one pending change; `text: ''` removes it. */
+    private addPending;
+    /** Sessions whose agent turn is running now (the turn hooks keep it). */
+    private readonly activeTurns;
+    /** The turn hooks report a bound session's turn starting and ending. */
+    setTurnActive(sessionId: string, active: boolean): void;
+    /**
+     * What the working files hold that the play area does not: build files
+     * added, changed or removed against the waiting candidate (else the live
+     * version), whoever wrote them — the panel, the agent, a CLI member, the
+     * user's own editor. Modification times pick the suspects; only those are
+     * compared byte for byte, so an unchanged project costs a stat walk.
+     */
+    changes(projectId: string): Promise<GameResult<WorkingChanges & {
+        readonly ok: true;
+    }>>;
+    /** Add (or replace by key) one uncommitted panel edit. */
+    private addEdit;
+    /** The agent has read the pending list (`game_read`): it is no longer news. */
+    clearPending(projectId: string): Promise<void>;
+    /** Drop one pending change by key (the dock's ×). */
+    dropPending(projectId: string, key: string, session: Session | undefined): Promise<GameResult>;
+    /**
+     * The user sent a message carrying the panel's change list (it starts
+     * with {@link PANEL_CHANGES_MARK}): drop exactly the changes it lists.
+     * Changes made after the list was written stay pending.
+     * @param sessionId - the sending session.
+     * @param text - the user message's text.
+     * @returns how many changes were cleared.
+     */
+    clearSent(sessionId: string, text: string): Promise<number>;
+    /** The manifest of a project, or undefined. */
+    private manifestOf;
+    /** Set one slider value (user layer; the play frame gets it live from the panel). */
+    setParam(projectId: string, key: string, value: number, session: Session | undefined): Promise<GameResult>;
+    /** 定稿: write the slider values into game.json as the new defaults. */
+    finalizeParams(projectId: string, session: Session | undefined): Promise<GameResult>;
+    /** 还原: drop every slider override. */
+    resetParams(projectId: string, session: Session | undefined): Promise<GameResult>;
+    /**
+     * Edit one element in the working files — its look, or scalar fields
+     * (`lore`, the 设定 text, included). The play area keeps its version until
+     * the user commits (`commit`); the edit is listed as uncommitted, and as
+     * pending for the agent.
+     */
+    editElement(projectId: string, elementId: string, patch: {
+        look?: unknown;
+        fields?: Record<string, string | number | boolean | null>;
+    }, session: Session | undefined, note?: string): Promise<GameResult<{
+        readonly ok: true;
+        readonly element: Record<string, unknown>;
+    }>>;
+    /** Write one design chapter (the user's direct edit). */
+    writeChapter(projectId: string, chapterId: string, text: string, session: Session | undefined): Promise<GameResult>;
+    /** Edit the one-pager in game.json (pitch, element types, pillars) — the user's direct edit. */
+    setOnePager(projectId: string, patch: {
+        pitch?: string;
+        elementTypes?: string;
+        pillars?: string;
+    }, session: Session | undefined): Promise<GameResult>;
+    /** Ask for a restyle: the next passing version becomes a candidate. The panel puts the request into the composer. */
+    requestRestyle(projectId: string, styleId: string, session: Session | undefined): Promise<GameResult>;
+    private proposals;
+    /**
+     * Store up to 3 appearance variants for an element (the `game_propose`
+     * tool); the user picks one in the panel.
+     */
+    proposeLooks(sessionId: string, elementId: string, request: string, variants: readonly {
+        label?: string;
+        note?: string;
+        look: unknown;
+    }[]): Promise<{
+        ok: true;
+        count: number;
+        name: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** The user picks a variant: it replaces the element's look at once; the others stay in the history. */
+    pickProposal(projectId: string, elementId: string, at: string, index: number, session: Session | undefined): Promise<GameResult>;
+    private readVersions;
+    private updateVersions;
+    private appendVersion;
+    /** The 版本 view's rows, newest first: only versions whose snapshot still exists. */
+    private versionRows;
+    /** The last check's screenshot (webp, base64), if any. */
+    checkShot(projectId: string, version?: number): Promise<GameResult<{
+        readonly ok: true;
+        readonly webp: string;
+    }>>;
+    /** Append one line to the project's playtest log (`.game/playtest-log.jsonl`). */
+    private log;
+    /** Record what the panel saw during one play session (errors, length). */
+    logPlay(projectId: string, entry: {
+        version: number;
+        seconds: number;
+        errors: readonly string[];
+    }, session: Session | undefined): Promise<GameResult>;
+    /** The playtest log, newest first (last 60). */
+    private logEntries;
+    /** The generated 试玩记录 chapter, newest first. */
+    private playtestText;
+}
+//# sourceMappingURL=store.d.ts.map