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/scenario-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.

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

Tasks

• src/app.ts: Exported runStartupScenario(scenarioRegistry, contextRegistry, config, openApiDocument?) — looks up startup in the index module, builds an ApplyContext ({ 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.
• 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.
• docs/features/repl.md: Added "Startup scenario" section with basic and delegation examples; updated cross-link to point to the new Scenario Scripts pattern.
• 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.
• docs/patterns/index.md: Replaced the narrow "Seed Data on Startup" entry with "Scenario Scripts" in both the prose and the pattern table.

[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.