Export Context$ and Scenario$ interfaces for strongly-typed loadContext() in _.context.ts files

[Copilot]

Summary

_.context.ts constructors receive { loadContext, readJson } from the module loader with no type information, making loadContext effectively untyped. This exports a Context$ interface and a Scenario$ interface from the generated types/_.context.ts so users can type their _.context.ts constructor arguments and get the same strongly-typed loadContext overloads — with no runtime overhead and no implementation to inherit.

The generated types/_.context.ts uses a shared LoadContextDefinitions interface to aggregate all loadContext overloads, which is referenced by both Scenario$ and Context$. All Scenario$ members are readonly. The default routes/_.context.ts scaffold is simplified to accept a Context$ argument without implementing any interface or assigning fields.

Original Prompt

_.context.ts constructors receive { loadContext, readJson } from the module loader with no type information, making loadContext effectively untyped. Export a type from the generated types file so users can annotate their constructors and get strongly-typed loadContext overloads.

Manual acceptance tests

• The generated types/_.context.ts contains a LoadContextDefinitions interface with the generated loadContext overloads, export interface Scenario$ with all readonly members and loadContext: LoadContextDefinitions["loadContext"], and export interface Context$ with readonly loadContext: LoadContextDefinitions["loadContext"] and readonly readJson
• The generated export type Scenario = ($: Scenario$) => Promise<void> | void references Scenario$
• The generated routes/_.context.ts imports Context$ and defines export class Context with constructor($: Context$) { void $; } — no implements, no field assignment
• In a _.context.ts that uses Context$ to type its constructor, TypeScript provides typed overloads for loadContext (e.g. loadContext("/pets") resolves to PetsContext when routes/pets/_.context.ts exists)
• Existing _.context.ts files that do not use Context$ continue to work unchanged
• Scenario, Scenario$, Context$, and existing loadContext overloads in types/_.context.ts are unaffected by changes to unrelated routes

Tasks

• generate.ts — Restructured buildApplyContextContent to extract a LoadContextDefinitions interface containing all loadContext overloads (with a /* code generator adds additional signatures here */ comment). Renamed ApplyContext → Scenario$; all its members are readonly and loadContext references LoadContextDefinitions["loadContext"]. The Scenario type alias now uses Scenario$. Added export interface Context$ with readonly loadContext: LoadContextDefinitions["loadContext"] and readonly readJson. Updated the JSDoc on writeApplyContextType to reference Scenario$.

• repository.ts — Simplified the default routes/_.context.ts scaffold to import Context$ and define export class Context with constructor($: Context$) { void $; } — no implements, no field declarations, no field assignment. Updated the doc link to point to the GitHub docs page.

• generate.test.ts — Updated test assertions to verify export interface Context$, export interface Scenario$, LoadContextDefinitions["loadContext"], readonly context, and Scenario = ($: Scenario$) appear in the generated output.

• context-registry.ts — Updated a code comment that referenced the old scenario-context name.

• docs/features/repl.md — Updated prose to reference Scenario$ instead of ApplyContext, and import examples to reference types/_.context.ts / types/_.context.js.

• .changeset/strongly-typed-load-context.md — Minor bump changeset updated to reference the new filename.

[pmcelhaney]

Create a BaseContext type and have the generated Context class extend that.

[pmcelhaney]

@copilot try again

[pmcelhaney]

@copilot try again

[Copilot]

@copilot try again

Done in c259be8. Replaced ContextArgs type with a BaseContext class exported from scenario-context.ts. The generated Context class now extends BaseContext, which initializes protected readonly loadContext and protected readonly readJson via its constructor — no manual constructor typing needed in user files.

[pmcelhaney]

@copilot BaseContext needs to be an interface, not a class. It will not have an implementation. It just needs to define the signature of the constructor.

[Copilot]

@copilot BaseContext needs to be an interface, not a class. It will not have an implementation. It just needs to define the signature of the constructor.

Done in 8579779. BaseContext is now an interface with no implementation — just readonly loadContext and readonly readJson. The scaffold uses implements BaseContext with a constructor that initializes those fields from the args.

[Copilot]

Rename scenario-context.ts to _.context.ts

Done in d6a7. The generated file is now types/_.context.ts and all imports reference "../types/_.context.js" — updated across generate.ts, repository.ts, the test file, docs, and changeset.

[pmcelhaney]

The generated types/_.context.ts file should look like this:

// This file is generated by Counterfact. Do not edit manually.
import type { Context } from "../routes/_.context";

interface LoadContextDefinitions {
  /* code generator adds additional signatures here */
  loadContext(path: "/" | `/${string}`): Context;
  loadContext(path: string): Record<string, unknown>;
}

export interface ApplyContext {
  /** Root context, same as loadContext("/") */
  readonly context: Context;
  readonly loadContext: LoadContextDefinitions["loadContext"];
  /** Named route builders stored in the REPL execution context */
  readonly routes: Record<string, unknown>;
  /** Create a new route builder for a given path */
  readonly route: (path: string) => unknown;
}

/** A scenario function that receives the live REPL environment */
export type Scenario = ($: ApplyContext) => Promise<void> | void;

/** Interface for Context objects defined in _.context.ts files */
export interface Context$ {
  /** Load a context object for a specific path */
  readonly loadContext: LoadContextDefinitions["loadContext"];
  /** Load a JSON file relative to this file's path */
  readonly readJson: (relativePath: string) => Promise<unknown>;
}

The generated routes/_.context.ts file should be exactly this:

import type { Context$ } from "../types/_.context.js";

/**
 * This is the default context for Counterfact.
 *
 * It defines the context object in the REPL
 * and the $.context object in the code.
 *
 * Add properties and methods to suit your needs.
 *
 * See https://github.com/counterfact/api-simulator/blob/main/docs/features/state.md
 */

export class Context {
  constructor($: Context$) {
    void $;
  }
}

[Copilot]

The generated types/_.context.ts file should look like this:

Done in 82d2824. The generated types/_.context.ts now uses LoadContextDefinitions for overloads (shared by both ApplyContext and Context$), ApplyContext members are all readonly, and BaseContext is renamed to Context$. The scaffold is simplified to just constructor($: Context$) { void $; } with no field assignments.

[pmcelhaney]

Rename ApplyContext to Scenario$

[Copilot]

Rename ApplyContext to Scenario$

Done in 036e92f. ApplyContext is renamed to Scenario$ in the generated types/_.context.ts, the Scenario type alias, tests, and docs.