create-stitchkit 0.3.3 → 0.4.1

package/UPGRADING.md

@@ -0,0 +1,342 @@
+# Upgrading a generated project
+
+How to move a project generated by `create-stitchkit` from one scaffolder
+version to another. It is a different move from upgrading the framework: your
+project is a **copy** of the template, not a dependency on it, so nothing here
+happens by installing anything. What a new scaffolder version brings is a set of
+edits you apply to a tree you already own, plus — and this is the part that bites
+— **operator steps**: things a machine has to be told before the new shape will
+start at all.
+
+The framework's own guide is
+[`docs/guide/upgrading.md`](../../docs/guide/upgrading.md); it covers the
+`stitchkit` dependency. This one covers the generated project.
+
+## The one rule that makes this work
+
+A scaffolder release that changes the generated project in a way an existing
+project must follow leads its [`CHANGELOG.md`](./CHANGELOG.md) entry with a
+**`### ⚠️ Breaking changes`** section (exact heading), each item carrying a
+**before → after** snippet. A version with **no** such section changes nothing
+you are obliged to adopt.
+
+The changelog says *what* changed. This file says what else has to happen —
+including the steps that touch a running machine, which have no place in a
+changelog because the next release overwrites the entry that carried them.
+
+## Flow
+
+1. **Find your project's origin.** The scaffolder version that generated it is
+   not recorded in the tree — check the changelog of the version you scaffolded
+   with, or diff your tree against a fresh scaffold of your current target.
+2. **Read every `### ⚠️ Breaking changes` in range** in
+   [`CHANGELOG.md`](./CHANGELOG.md), from the version above yours up to your
+   target.
+3. **Apply the code edits**, then the **`## Released migration: X.Y.Z`** section
+   below for the same versions — that is where the operator steps live.
+
+   > This channel starts at **0.4.0**. Versions below it have breaking changelog
+   > entries and no migration section here, because the file did not exist yet;
+   > for those, the changelog entry is all there is.
+4. **Verify** with your project's own gates: `bun run check`, `bun run test`,
+   `bun run build`, then a real start.
+
+## Where a migration section goes while the version has no number
+
+Write it here as **`## Unreleased migration: <short slug>`**. The slug matters:
+several may sit side by side, and each belongs to whoever wrote it. Do **not**
+reuse another author's heading — that is how a migration gets overwritten before
+anyone promotes it.
+
+At release, the release commit promotes every `Unreleased migration` heading
+into one `## Released migration: X.Y.Z`, each former heading becoming a `###`
+subsection under it — the same move the changelog makes when `[Unreleased]`
+becomes `## [X.Y.Z]`, in the same commit.
+
+A release carrying `### ⚠️ Breaking changes` and no matching
+`## Released migration: X.Y.Z` is refused by `bun scripts/release-plan.ts`, in
+`pre-push` and again in the publishing workflow. The check starts at `0.4.0` —
+the first scaffolder release with a migration channel of its own.
+
+---
+
+## Released migration: 0.4.1
+
+### a release refuses a stale artifact, and cleanup is bounded
+
+Two changes an existing project should take, both about a shutdown or a start
+that looked safe and was not.
+
+1. **Stamp the build.** Copy `scripts/build-stamp.ts` from a fresh scaffold,
+   append `&& bun scripts/build-stamp.ts` to your root `build` script, add
+   `.build-stamp.json` to `.gitignore`, and call `assertArtifactMatchesSource()`
+   at the end of `assertBuildArtifacts()` in `scripts/release-steps.ts`. Until
+   you do, `bun run pm2:prod` without a build applies your migrations and starts
+   the previous build.
+
+2. **Bound the cleanup, and let it end the process.** Copy
+   `packages/config/src/shutdown.ts` and `packages/backend/src/cleanup.ts`, add
+   the `./shutdown` export to `packages/config/package.json`, and replace the
+   bare `await mcp.close(); await prisma.$disconnect();` in your API role's
+   `onComplete` with `closeWithinBudget([...])` followed by
+   `concludeShutdown(cleanup, result.outcome === 'clean')`. Then have
+   `scripts/declaration.ts` import `FORCE_BUDGET_MS` and `CLEANUP_BUDGET_MS`
+   from the new module instead of declaring its own copies — the number a
+   supervisor is told to allow and the number the role enforces have to be one
+   number. `concludeShutdown` is the half that makes the budget real: setting
+   `process.exitCode` decides the code a process reports *when it exits*, and a
+   step that ran out of time is usually still holding the handle that stops it
+   from exiting at all.
+
+No operator step: nothing about a running machine changes.
+
+### the gate list runs, and never deploys
+
+The `Gates` list in the generated guides presented five commands in a row, two
+of which check a **running** deployment — with nothing in the list that starts
+one. The fix is not to add a deploy command: `bun run pm2:prod` applies your
+declared migrations and reloads the deployment you are running, so a list that
+contains it means "run these before handing work off" quietly says "deploy".
+
+1. **Take `pm2:prod` out of your gate list**, in `README.md` and `AGENTS.md`
+   alike, and delete any advice to run `pm2 delete all` — that empties whichever
+   daemon it is pointed at, including applications with nothing to do with this
+   project.
+
+2. **Add the harness that brings up a deployment of its own.** Copy
+   `scripts/acceptance-local.ts` and `scripts/acceptance-database.ts` from a
+   fresh scaffold and add `"acceptance:local": "bun scripts/acceptance-local.ts"`
+   to your root scripts. It creates and destroys its own deployment — separate
+   `PM2_HOME`, ephemeral ports, its own public-host allowlist — and runs
+   `runtime:smoke` and `e2e` against that.
+
+3. **Give it a database of its own.** Add `ACCEPTANCE_DATABASE_URL` to `.env`
+   and `.env.example`, naming a throwaway database — not the one `DATABASE_URL`
+   names. The runtime gates WRITE (the repository example's smoke posts a
+   refresh, and that upserts), so a harness borrowing `DATABASE_URL` writes rows
+   into whatever your `.env` points at. The harness refuses to start when the
+   variable is unset or names the same database, and prints the line to add.
+
+4. **Wait for readiness before reporting it.** Copy `scripts/readiness.ts` from
+   a fresh scaffold, then in `scripts/dev.ts` and `scripts/release.ts` await
+   `awaitRolesAnswering(declaredRoleReadiness(appDeclaration, environment))`
+   before printing that the roles are running. Until you do, anything you run
+   after `bun run dev` or `bun run pm2:prod` races the roles they started.
+
+5. **Let the smoke read your allowlist.** In `scripts/web-surface-smoke.ts` the
+   portability check named two hosts of its own; take the version that reads
+   `PUBLIC_WEB_HOSTS` and pass it from `scripts/runtime-smoke.ts`. If you kept
+   the old one, your `.env` must claim `alpha.example` and `beta.example:8443`
+   or the check fails on a host your deployment correctly refuses. With the new
+   one, `_env.example` drops those example hosts — the harness supplies its own.
+
+6. **Keep the declaration out of the browser.**
+   `packages/frontend/src/lib/seo/pages.ts` must import `appIdentity` from
+   `@app/config/app-identity` rather than `appDeclaration`: a client component
+   reaches that module, so the whole declaration was going into your browser
+   bundle.
+
+No operator step: nothing about a running machine changes.
+
+### the declaration schema is imported
+
+For a project generated **before** the scaffolder version that drops the schema
+mirror. Nothing in your tree stops working if you skip this — the copy keeps
+parsing. What you lose by skipping is the guarantee: your copy no longer moves
+when the framework's schema does, and nothing tells you.
+
+1. **Point the config package at the framework.** In
+   `packages/config/src/declaration.ts`:
+
+   ```ts
+   // before
+   import { findProjectRole, parseProjectDeclaration } from './project-declaration.generated';
+   // after
+   import { findProjectRole, parseProjectDeclaration } from 'stitchkit/declaration';
+   ```
+
+   Then the same for every `import type { ProjectDeclaration, … }` in
+   `scripts/` — they pointed at the same file.
+
+2. **Declare the dependency.** `packages/config/package.json` gains
+   `"stitchkit": "catalog:"`, and `bun install` refreshes the lockfile.
+
+3. **Delete `packages/config/src/project-declaration.generated.ts`.**
+
+4. **Check your `stitchkit` range.** The entrypoint ships from **0.60.0**. If
+   your catalog targets less than that, raise it first — otherwise the import
+   resolves to nothing.
+
+5. **Read `.env` without the schema.** If your `scripts/local-env.ts` imports
+   `appDeclaration`, switch it to `appIdentity` from
+   `packages/config/src/app-identity.generated`. It needs only the slug, and a
+   project scaffolded with `--no-install` renders `.env` before anything is
+   installed — in that window the framework is not there to import.
+
+No operator step: nothing about a running machine changes.
+
+---
+
+## Released migration: 0.4.0
+
+### the project declares itself
+
+Everything in this section is for a project generated **before** the scaffolder
+version that introduces `project.json`.
+
+#### The declaration replaces `app.config.json`
+
+`app.config.json` said who the project was. `project.json` says what it *is*:
+identity, the roles it runs, what it builds, what it needs before it starts,
+what must happen once on release, and the **names** of the variables a
+deployment supplies. Identity moved under an `identity` key, and the file gained
+a `schemaVersion` so a reader that does not understand the format refuses the
+project instead of interpreting half of it.
+
+```ts
+// before
+import { appIdentity } from '@app/config/identity';
+appIdentity.name;
+
+// after
+import { appDeclaration } from '@app/config/declaration';
+appDeclaration.identity.name;
+```
+
+A **client** component imports the generated identity-only module instead —
+importing the whole declaration from the browser ships role commands, working
+directories, artifact paths and the migration lockfile in the bundle:
+
+```ts
+// before, in a 'use client' file
+import { appIdentity } from '@app/config/identity';
+
+// after
+import { appIdentity } from '@app/config/app-identity';
+```
+
+#### Operator step: delete the old supervisor processes FIRST
+
+PM2 process names now follow the declared role names, so the new supervision
+files start a **new pair beside the old one**. Under `autorestart` both then
+fight for the same ports, and the symptom is an `EADDRINUSE` loop rather than a
+clear error.
+
+Before the first `bun run pm2:prod` on the new files:
+
+```bash
+pm2 delete <slug>-backend <slug>-frontend <slug>-backend-dev <slug>-frontend-dev
+```
+
+`<slug>` is your project's slug — `identity.slug` in `project.json`. Check what
+is actually registered with `pm2 list` first; nothing here is safe to run blind.
+
+#### Operator step: the supervisor's patience must cover the whole shutdown
+
+The generated `ecosystem.config.cjs` is now rendered from the declaration, and
+its `kill_timeout` is computed from each role's drain floor plus the force
+window plus cleanup. If you kept a hand-edited supervision file, compare its
+`kill_timeout` against `drainFloorMs` in `project.json`: a timeout shorter than
+the full budget means the drain never finishes, every time, and the only visible
+trace is a non-zero exit code.
+
+Regenerate rather than hand-edit:
+
+```bash
+bun run gen:declaration
+```
+
+#### Environment: three variables changed meaning
+
+```sh
+# before
+NEXT_PUBLIC_API_URL=https://api.example
+NEXT_PUBLIC_WEB_URL=https://app.example
+
+# after — nothing. Both are gone.
+```
+
+Anything prefixed `NEXT_PUBLIC_` is substituted at **build** time, so declaring
+one froze an address into the artifact: the built `robots.txt` and `sitemap.xml`
+carried one origin in their bytes and one build could not serve a second
+address. The public origin now comes from the request.
+
+A forwarded host must be claimed before it is believed. Set **one** of:
+
+```sh
+PUBLIC_WEB_ORIGIN=https://app.example          # a single address
+PUBLIC_WEB_HOSTS=app.example,www.app.example   # several
+```
+
+A host outside them is refused. Setting `PUBLIC_WEB_ORIGIN` also restores static
+rendering for `/robots.txt`, `/sitemap.xml` and the `[locale]` segment, which
+otherwise become request-rendered.
+
+The check and e2e addresses were renamed so no build can substitute them:
+
+```sh
+# before
+NEXT_PUBLIC_API_URL=http://127.0.0.1:3211
+# after
+SMOKE_API_ORIGIN=http://127.0.0.1:3211
+SMOKE_WEB_ORIGIN=http://127.0.0.1:3210
+```
+
+`CORS_ORIGIN` is now optional: a frontend that reaches the API through its own
+routing layer makes same-origin requests, and requiring an origin there was
+requiring knowledge of the place.
+
+#### The repository example: calls lose their parentheses
+
+Only for a project generated with `--example repository`. The browser now talks
+to its own origin, so the API client is a module constant:
+
+```ts
+// before
+repositoryApi().read();
+repositoryUrls().read();
+
+// after
+repositoryApi.read();
+repositoryUrls.read();
+```
+
+The web role forwards `/api/…` to the API role, which needs `INTERNAL_API_URL`
+(already required).
+
+**The socket's address is now its own variable.** If you use the realtime
+socket and have no routing layer forwarding `/socket.io`, rename it:
+
+```sh
+# before — read only by the socket, despite the name
+PUBLIC_API_ORIGIN=https://api.example
+# after
+PUBLIC_REALTIME_ORIGIN=https://api.example
+```
+
+`PUBLIC_API_ORIGIN` still exists and still means HTTP, but it is inert until you
+switch: the import in `packages/frontend/src/lib/api/queries.ts` decides which
+client the browser uses. Both variables are optional; a deployment behind one
+routing layer sets neither, and `CORS_ORIGIN` with them.
+
+The cross-origin form moved to `packages/frontend/src/lib/api/cross-origin.ts`
+(previously `lib/api/origin.ts`); `requirePublicApiOrigin` lives there, beside
+`optionalRealtimeOrigin` and `setPublicOrigins`.
+
+#### The SEO helpers are async
+
+They read the public origin from the request, so they cannot be constants.
+TypeScript will **not** catch a missing `await` inside an inferred object
+literal — a `Promise` serialises there as `{}`.
+
+```ts
+// before
+const url = absoluteSiteUrl('/en');
+createPageMetadata('home', locale);
+
+// after — and the component becomes async
+const url = await absoluteSiteUrl('/en');
+await createPageMetadata('home', locale);
+```
+
+`siteOrigin` is gone.

package/dist/cli.js

@@ -2,9 +2,207 @@
 // @bun
 
 // src/cli.ts
-import { basename as basename3, resolve as resolve2 } from "path";
+import { readFile as readFile2 } from "fs/promises";
+import { basename as basename3, join as join2, resolve as resolve2 } from "path";
 var {spawn } = globalThis.Bun;
 
+// src/identity.ts
+import { basename } from "path";
+
+// ../core/src/declaration.ts
+import { z } from "zod";
+var PROJECT_DECLARATION_SCHEMA_VERSION = 1;
+var MACHINE_PATTERNS = [
+  [/:\/\//, "an absolute address"],
+  [/^\/\//, "a protocol-relative host"],
+  [/^[~]/, "a home-relative path"],
+  [/^[A-Za-z]:[\\/]/, "a Windows drive path"],
+  [/\\/, "a Windows path separator"],
+  [/(?:^|[\s=:])\d{1,3}(?:\.\d{1,3}){3}(?![\d.])/, "an IP address"],
+  [/(?:^|[\s=])[A-Za-z][\w.-]*:\d{2,5}(?![\w.])/, "a host and port"]
+];
+function namesAMachine(value) {
+  for (const [pattern, reason] of MACHINE_PATTERNS) {
+    if (pattern.test(value))
+      return reason;
+  }
+  return;
+}
+function refuseMachineNames(label) {
+  return (schema) => schema.refine((value) => namesAMachine(value) === undefined, {
+    error: (issue) => `${label} names a machine \u2014 ${namesAMachine(String(issue.input)) ?? "a value of the deployment"} is supplied by the deployment, not written in the code`
+  });
+}
+var ProjectSlugSchema = z.string().min(1).max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Use lowercase letters, numbers and single hyphens (for example: talk-control)");
+var ProjectDescriptionSchema = z.record(refuseMachineNames("A locale tag")(z.string().min(1)), refuseMachineNames("A description")(z.string().trim().min(1))).refine((value) => Object.keys(value).length > 0, "Describe the project in at least one locale");
+var ProjectIdentitySchema = z.object({
+  slug: ProjectSlugSchema,
+  name: refuseMachineNames("A project name")(z.string().trim().min(1).max(80)),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/, "Use a semantic version such as 0.1.0"),
+  description: ProjectDescriptionSchema
+}).strict();
+var RepositoryPathSchema = z.string().min(1).refine((value) => !value.startsWith("/"), "Use a path relative to the repository root").refine((value) => namesAMachine(value) === undefined, {
+  error: (issue) => `A path may not contain ${namesAMachine(String(issue.input)) ?? "a machine name"}`
+}).refine((value) => !value.split("/").includes(".."), "A path may not climb out of the repository");
+var BindingVariableSchema = z.string().regex(/^[A-Z][A-Z0-9_]*$/, "Name an environment variable, for example API_PORT");
+var ProjectListenerSchema = z.object({
+  portVariable: BindingVariableSchema,
+  bindVariable: BindingVariableSchema,
+  readinessPath: refuseMachineNames("A readiness path")(z.string().startsWith("/", "Readiness is a path, for example /health"))
+}).strict();
+var ProjectRunModeSchema = z.enum(["development", "production"]);
+var PROJECT_SCRIPT_LAUNCHERS = [
+  [/^(?:bun|npm|pnpm|yarn)$/, /^run$/],
+  [/^deno$/, /^task$/],
+  [/^(?:npx|bunx|pnpx)$/, null]
+];
+function launchesAScript(executable, firstArgument) {
+  for (const [runner, verb] of PROJECT_SCRIPT_LAUNCHERS) {
+    if (!runner.test(executable))
+      continue;
+    if (verb === null)
+      return true;
+    if (firstArgument !== undefined && verb.test(firstArgument))
+      return true;
+  }
+  return false;
+}
+var PORT_FLAG = /^(?:-p|-{1,2}(?:port|listen))$/i;
+var CommandPartSchema = refuseMachineNames("A command part")(z.string().min(1)).refine((value) => !value.startsWith("/"), "A command part may not be an absolute path \u2014 paths are relative to the source").refine((value) => !/^[^=\s]+=/.test(value), "A command part may not carry an inline value \u2014 write the flag and its value as separate arguments, so the value is checked like every other one");
+var CommandArgumentsSchema = z.array(CommandPartSchema).refine((args) => args.every((value, index) => !(/^\d{1,5}$/.test(value) && PORT_FLAG.test(args[index - 1] ?? ""))), "A number after a port flag is a port \u2014 name the variable that carries it and let the role read it");
+var ProjectCommandSchema = z.object({
+  executable: CommandPartSchema,
+  args: CommandArgumentsSchema
+}).strict();
+var ProjectRoleCommandSchema = ProjectCommandSchema.refine((value) => !launchesAScript(value.executable, value.args[0]), "Start the role process itself, not a script runner: a launcher between the supervisor and the role duplicates the shutdown signal and forces the drain").refine((value) => !value.args.includes("--filter"), "A workspace filter puts a launcher between the supervisor and the role, and the shutdown signal never reaches it");
+var ProjectRoleSchema = z.object({
+  name: ProjectSlugSchema,
+  workingDirectory: RepositoryPathSchema.optional(),
+  commands: z.record(ProjectRunModeSchema, ProjectRoleCommandSchema),
+  listener: ProjectListenerSchema.optional(),
+  drainFloorMs: z.number().int().nonnegative()
+}).strict();
+var ProjectBuildInputSchema = z.object({
+  name: ProjectSlugSchema,
+  path: RepositoryPathSchema,
+  digest: z.string().regex(/^sha256:[0-9a-f]{64}$/, 'Use a lowercase sha256 digest, as "sha256:<64 hex>"')
+}).strict();
+var ProjectBuildSchema = z.object({
+  command: ProjectCommandSchema,
+  artifacts: z.array(RepositoryPathSchema).min(1),
+  inputs: z.array(ProjectBuildInputSchema).optional()
+}).strict().refine((build) => {
+  const names = (build.inputs ?? []).map((input) => input.name);
+  return new Set(names).size === names.length;
+}, "Two build inputs share a name \u2014 a failure could then name either of them");
+var ProjectRequirementPhaseSchema = z.enum(["release", "start"]);
+var ProjectRequirementSchema = z.object({
+  name: ProjectSlugSchema,
+  phases: z.array(ProjectRequirementPhaseSchema).min(1)
+}).strict();
+var ProjectMigrationsSchema = z.object({
+  engine: refuseMachineNames("A migration engine name")(z.string().min(1).max(64)),
+  root: RepositoryPathSchema,
+  lockfile: RepositoryPathSchema
+}).strict();
+var ProjectReleaseSchema = z.object({ migrations: ProjectMigrationsSchema.optional() }).strict();
+var ProjectEnvShapeSchema = z.enum(["string", "integer", "boolean", "url", "enum"]);
+var ProjectEnvVariableSchema = z.object({
+  name: BindingVariableSchema,
+  shape: ProjectEnvShapeSchema,
+  required: z.boolean(),
+  members: z.array(refuseMachineNames("An enum member")(z.string().min(1))).min(1).optional()
+}).strict().refine((value) => value.shape === "enum" === (value.members !== undefined), "An enum variable lists its members; every other shape has none");
+var ProjectDeclarationSchema = z.object({
+  schemaVersion: z.literal(PROJECT_DECLARATION_SCHEMA_VERSION),
+  kind: z.enum(["library", "application"]),
+  identity: ProjectIdentitySchema,
+  roles: z.array(ProjectRoleSchema),
+  build: ProjectBuildSchema.optional(),
+  requires: z.array(ProjectRequirementSchema),
+  release: ProjectReleaseSchema,
+  env: z.object({ variables: z.array(ProjectEnvVariableSchema) }).strict()
+}).strict().refine((value) => value.kind === "application" ? value.roles.length > 0 : value.roles.length === 0, "An application declares at least one role; a library declares none").refine((value) => new Set(value.roles.map((role) => role.name)).size === value.roles.length, "Role names must be unique").refine((value) => new Set(value.requires.map((entry) => entry.name)).size === value.requires.length, "Name each requirement once and list its phases").refine((value) => value.requires.every((entry) => new Set(entry.phases).size === entry.phases.length), "List each phase of a requirement once").refine((value) => new Set(value.env.variables.map((entry) => entry.name)).size === value.env.variables.length, "Declare each environment variable once").refine((value) => listenerBindingProblem(value) === undefined, {
+  error: (issue) => listenerBindingProblem(issue.input) ?? "Listener bindings are inconsistent"
+});
+function isListenerBindingSubject(value) {
+  return typeof value === "object" && value !== null && "roles" in value && "env" in value;
+}
+function listenerBindingProblem(value) {
+  if (!isListenerBindingSubject(value))
+    return;
+  const shapes = new Map(value.env.variables.map((entry) => [entry.name, entry.shape]));
+  for (const role of value.roles) {
+    const listener = role.listener;
+    if (!listener)
+      continue;
+    if (listener.portVariable === listener.bindVariable) {
+      return `Role "${role.name}" points its port and its bind address at the same variable "${listener.portVariable}"`;
+    }
+    const expected = [
+      [listener.portVariable, "integer"],
+      [listener.bindVariable, "string"]
+    ];
+    for (const [name, shape] of expected) {
+      const declared = shapes.get(name);
+      if (declared === undefined) {
+        return `Role "${role.name}" listens on "${name}", which env.variables does not declare \u2014 a deployment reading this cannot know it has to supply it`;
+      }
+      if (declared !== shape) {
+        return `Role "${role.name}" listens on "${name}", declared as "${declared}" where a ${shape} is needed`;
+      }
+    }
+  }
+  return;
+}
+var VersionProbeSchema = z.object({ schemaVersion: z.unknown() }).loose();
+function parseProjectDeclaration(source) {
+  const probe = VersionProbeSchema.safeParse(source);
+  const declared = probe.success ? probe.data.schemaVersion : undefined;
+  if (declared !== undefined && declared !== PROJECT_DECLARATION_SCHEMA_VERSION) {
+    throw new Error(`Project declaration schema version ${JSON.stringify(declared)} is not supported \u2014 ` + `this build understands version ${PROJECT_DECLARATION_SCHEMA_VERSION}.`);
+  }
+  return ProjectDeclarationSchema.parse(source);
+}
+
+// src/identity.ts
+var APP_IDENTITY_PATH = "packages/config/src/app-identity.generated.ts";
+function renderAppIdentityModule(identity) {
+  return `// GENERATED FILE \u2014 do not edit.
+//
+// Rendered from \`project.json\` by \`scripts/declaration.ts\`.
+//
+// Identity ONLY, inlined rather than imported, because this is the part of the
+// declaration a browser may know. Importing the whole declaration from a client
+// component would put role commands, working directories, build artifact paths,
+// the migration lockfile and every environment variable name into the browser
+// bundle \u2014 the same mistake as publishing internal topology from a status
+// endpoint, made from the other side.
+
+export const appIdentity = ${JSON.stringify(identity, undefined, 2)};
+`;
+}
+function displayNameFromSlug(slug) {
+  return slug.split("-").map((part) => `${part[0]?.toUpperCase()}${part.slice(1)}`).join(" ");
+}
+function createApplicationIdentity(destination, displayName) {
+  const slug = ProjectSlugSchema.parse(basename(destination));
+  const name = displayName?.trim() || displayNameFromSlug(slug);
+  return ProjectIdentitySchema.parse({
+    slug,
+    name,
+    version: "0.1.0",
+    description: {
+      en: `${name} is a production application built with Stitchkit.`,
+      ru: `${name} \u2014 production-\u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u0435 \u043D\u0430 Stitchkit.`
+    }
+  });
+}
+function withIdentity(declaration, identity) {
+  const copied = parseProjectDeclaration(declaration);
+  return parseProjectDeclaration({ ...copied, identity });
+}
+
 // src/options.ts
 var HELP = `Create a production-shaped Stitchkit application.
 
@@ -62,38 +260,6 @@ import { lstat, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
 import { homedir } from "os";
 import { basename as basename2, dirname, extname, join, parse, relative, resolve, sep } from "path";
 import { z as z2 } from "zod";
-
-// src/identity.ts
-import { basename } from "path";
-import { z } from "zod";
-var ApplicationSlugSchema = z.string().min(1).max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Use lowercase letters, numbers and single hyphens (for example: talk-control)");
-var ApplicationIdentitySchema = z.object({
-  slug: ApplicationSlugSchema,
-  name: z.string().trim().min(1).max(80),
-  version: z.string().regex(/^\d+\.\d+\.\d+$/, "Use a semantic version such as 0.1.0"),
-  description: z.object({
-    en: z.string().trim().min(1),
-    ru: z.string().trim().min(1)
-  })
-});
-function displayNameFromSlug(slug) {
-  return slug.split("-").map((part) => `${part[0]?.toUpperCase()}${part.slice(1)}`).join(" ");
-}
-function createApplicationIdentity(destination, displayName) {
-  const slug = ApplicationSlugSchema.parse(basename(destination));
-  const name = displayName?.trim() || displayNameFromSlug(slug);
-  return ApplicationIdentitySchema.parse({
-    slug,
-    name,
-    version: "0.1.0",
-    description: {
-      en: `${name} is a production application built with Stitchkit.`,
-      ru: `${name} \u2014 production-\u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u0435 \u043D\u0430 Stitchkit.`
-    }
-  });
-}
-
-// src/scaffold.ts
 var TEXT_EXTENSIONS = new Set([
   ".cjs",
   ".css",
@@ -126,6 +292,8 @@ var IGNORED_DIRECTORIES = new Set([
   "playwright-report",
   "test-results"
 ]);
+var IGNORED_FILE_NAMES = new Set([".env", ".build-stamp.json", "next-env.d.ts"]);
+var IGNORED_FILE_SUFFIXES = [".log", ".tsbuildinfo"];
 function isTemplateSourcePathIncluded(sourcePath) {
   const normalized = sourcePath.replaceAll("\\", "/").replace(/^\.\//, "");
   if (!normalized)
@@ -136,7 +304,9 @@ function isTemplateSourcePathIncluded(sourcePath) {
   if (normalized === "packages/db/src/generated" || normalized.startsWith("packages/db/src/generated/"))
     return false;
   const name = basename2(normalized);
-  return name !== ".env" && name !== "next-env.d.ts" && !name.endsWith(".log") && !name.endsWith(".tsbuildinfo");
+  if (IGNORED_FILE_NAMES.has(name))
+    return false;
+  return !IGNORED_FILE_SUFFIXES.some((suffix) => name.endsWith(suffix));
 }
 function shouldIncludeTemplatePath(templateDirectory, sourcePath) {
   return isTemplateSourcePathIncluded(relative(templateDirectory, sourcePath));
@@ -231,8 +401,13 @@ async function scaffoldProject(templateDirectory, destination, options = {}) {
     if (options.overlayDirectory) {
       await writeMaterialisedFiles(resolvedDestination, await materialiseTemplateFiles(options.overlayDirectory));
     }
-    await writeFile(join(resolvedDestination, "app.config.json"), `${JSON.stringify(identity, undefined, 2)}
+    const declarationPath = join(resolvedDestination, "project.json");
+    const declaration = withIdentity(JSON.parse(await readFile(declarationPath, "utf8")), identity);
+    await writeFile(declarationPath, `${JSON.stringify(declaration, undefined, 2)}
 `);
+    const identityPath = join(resolvedDestination, APP_IDENTITY_PATH);
+    await mkdir(dirname(identityPath), { recursive: true });
+    await writeFile(identityPath, renderAppIdentityModule(declaration.identity));
     const manifestPath = join(resolvedDestination, "package.json");
     const manifest = RootManifestSchema.parse(JSON.parse(await readFile(manifestPath, "utf8")));
     await writeFile(manifestPath, `${JSON.stringify({ ...manifest, name: identity.slug }, undefined, 2)}
@@ -284,14 +459,10 @@ Created ${options.displayName ?? basename3(destination)}${mode}
     process.stdout.write(`  bun run dev
 
 `);
-    process.stdout.write(`Web: http://localhost:3210
-`);
-    process.stdout.write(`API: http://localhost:3211
-`);
-    process.stdout.write(`MCP: http://localhost:3211/mcp
-`);
-    process.stdout.write(`OpenAPI: http://localhost:3211/openapi.json
+    for (const line of await roleAddresses(destination)) {
+      process.stdout.write(`${line}
 `);
+    }
     return 0;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -303,6 +474,31 @@ Created ${options.displayName ?? basename3(destination)}${mode}
 if (import.meta.main) {
   process.exitCode = await run(Bun.argv.slice(2));
 }
+async function roleAddresses(destination) {
+  try {
+    const declaration = parseProjectDeclaration(JSON.parse(await readFile2(join2(destination, "project.json"), "utf8")));
+    const environment = readEnvironmentExample(await readFile2(join2(destination, ".env.example"), "utf8"));
+    const host = environment.BIND_HOST ?? "127.0.0.1";
+    return declaration.roles.flatMap((role) => {
+      const port = role.listener && environment[role.listener.portVariable];
+      if (!role.listener || !port)
+        return [];
+      return [`${role.name}: http://${host}:${port}${role.listener.readinessPath}`];
+    });
+  } catch {
+    return [];
+  }
+}
+function readEnvironmentExample(source) {
+  const values = {};
+  for (const line of source.split(`
+`)) {
+    const match = /^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line.trim());
+    if (match?.[1])
+      values[match[1]] = match[2] ?? "";
+  }
+  return values;
+}
 export {
   run
 };