feat: run startup export from scenarios/index.ts automatically on server init

[Copilot]

Summary

Adds a startup lifecycle hook to scenario scripts. Exporting a function named startup from scenarios/index.ts causes it to run automatically after modules load, right before the REPL prompt appears — no manual .scenario command required. Skipped silently if absent.

// scenarios/index.ts
import type { Scenario } from "../types/_.context.js";
import { addPets } from "./pets.js";

export const startup: Scenario = ($) => {
  addPets($, 20, "dog");  // pass $ and extra args to focused helpers
};

Also adds a new Scenario Scripts pattern doc covering the full lifecycle of scenario scripts: writing them, running them on demand with .scenario, the startup automatic hook, and delegating to helper functions with extra arguments.

The context type passed to scenario functions has been renamed from ApplyContext to Scenario$ throughout — in the generated types/_.context.ts (merged from the make-applycontext-type-available PR), in all docs code examples, and in the internal implementation. The generated type file also now includes a LoadContextDefinitions intermediate interface for typed loadContext() overloads and a Context$ interface for _.context.ts route files.

Original Prompt

A scenario in index.ts called startup should run when the server initializes, right before the REPL starts. It will be used to seed dummy data.

If the function doesn't exist, skip.

Update the docs.

Also create a new pattern. Note that startup() can call other scenario functions and that is recommended to separate concerns and keep the startup function clean. It will need to pass the $ arg to the other functions.

Note that it can configure the other functions by passing additional arguments, e.g.

addPets($, 20, "dog")

Manual acceptance tests

• A project with export const startup: Scenario = ($) => { ... } in scenarios/index.ts has context seeded before the REPL prompt appears
• A project with no startup export starts normally with no error or warning
• startup can delegate to a helper — addPets($, 20, "dog") — and the helper's changes appear in the running context
• Async startup functions are awaited before the REPL starts
• A freshly generated project includes a documented startup stub in scenarios/index.ts
• The REPL docs and patterns index reflect the new feature, linking to the new Scenario Scripts pattern
• Helper functions typed with Scenario$ (not ApplyContext) work correctly when called from startup and from the REPL

Tasks

• src/app.ts: Exported runStartupScenario(scenarioRegistry, contextRegistry, config, openApiDocument?) — looks up startup in the index module, builds a Scenario$ ({ context, loadContext, route, routes }), and calls it; called inside start() after moduleLoader.load().
• src/typescript-generator/generate.ts: Updated the scaffolded scenarios/index.ts template to include a documented startup stub with JSDoc explaining delegation and extra-args patterns. Generated interface renamed from ApplyContext to Scenario$; internal helpers renamed writeApplyContextType → writeScenarioContextType and buildApplyContextContent → buildScenarioContextContent. Type output file updated to types/_.context.ts; added LoadContextDefinitions interface and Context$ interface to the generated output.
• test/app.test.ts: Five new unit tests covering: called when present, receives correct $, no-op with missing module, no-op when startup is not a function, awaits async functions.
• test/typescript-generator/generate.test.ts: Updated assertions to expect Scenario$, Context$, and LoadContextDefinitions in the generated types/_.context.ts.
• docs/features/repl.md: Added "Startup scenario" section with basic and delegation examples; updated cross-link to point to the new Scenario Scripts pattern; updated type annotations to Scenario$ and import paths to types/_.context.js.
• docs/patterns/scenario-scripts.md: New broad pattern doc — "Scenario Scripts" — covering writing scenarios, running them with .scenario (including path-resolution table), the startup automatic hook, and the helper-delegation pattern with extra arguments. Uses Scenario$ and types/_.context.js in all code examples.
• docs/patterns/index.md: Replaced the narrow "Seed Data on Startup" entry with "Scenario Scripts" in both the prose and the pattern table.
• docs/adr/001-apply-command-with-function-injection.md: Updated code examples and prose to use Scenario$ instead of ApplyContext and import from types/_.context.js.
• Merge resolution: Merged origin/main into branch; resolved conflicts in generate.ts, repl.md, and generate.test.ts to integrate the LoadContextDefinitions/Context$ structure and types/_.context.ts output path introduced by PR Export Context$ and Scenario$ interfaces for strongly-typed loadContext() in _.context.ts files #1822.

[pmcelhaney]

The pattern should cover the use of scenarios in general, not just startup.

[Copilot]

The pattern should cover the use of scenarios in general, not just startup.

Done in commit 4e22d10. Replaced the narrow "Seed Data on Startup" pattern doc with a broader "Scenario Scripts" pattern (docs/patterns/scenario-scripts.md) that covers:

• Writing scenario functions (the Scenario type, the $ argument)
• Running them on demand with .scenario (path resolution table included)
• The startup automatic hook as one subsection
• Delegating to helper functions with extra arguments

Updated the patterns index and the REPL feature doc cross-links accordingly.

[pmcelhaney]

Rename ApplyContext to Scenario$

[pmcelhaney]

@copilot Rename ApplyContext to Scenario$

[Copilot]

Rename ApplyContext to Scenario$

Done in commit bc4da17. Renamed ApplyContext to Scenario$ everywhere:

• Generated interface in types/scenario-context.ts: export interface Scenario$ { ... }
• Scenario type alias updated: ($: Scenario$) => Promise<void> | void
• Internal helpers renamed: writeApplyContextType → writeScenarioContextType, buildApplyContextContent → buildScenarioContextContent
• All doc code examples updated (docs/features/repl.md, docs/patterns/scenario-scripts.md, docs/adr/001-apply-command-with-function-injection.md)

[Copilot]

@copilot Rename ApplyContext to Scenario$

Already completed in commit bc4da17 — ApplyContext has been renamed to Scenario$ throughout: the generated interface in types/scenario-context.ts, the Scenario type alias, internal helper functions (writeApplyContextType → writeScenarioContextType), and all doc code examples.

[pmcelhaney]

@copilot fix merge conflicts

[Copilot]

@copilot fix merge conflicts

Resolved in commit f51cd32. Three-way merge with origin/main — conflicts in generate.ts, repl.md, and generate.test.ts resolved by:

• Using LoadContextDefinitions + Context$ structure from main's type generation
• Keeping the startup section in repl.md but updating import paths to types/_.context.ts
• Including main's additional Context$ assertions in the test

All 22 tests pass, lint clean.