feat(cli): add init, the compute config formalizer (#108)

`prisma-cli init` writes a committed `prisma.compute.ts` for the app in
the current directory. Deploy stays zero-config; init pins what deploy
would infer so the setup is reviewable and stable for teammates and CI.
It never overwrites an existing config, never scaffolds code (that's
create-prisma's job), and needs no auth except for the optional link
step.

```
$ prisma-cli init
  app        acme-web  package.json
  framework  Next.js   detected from package.json
  http port  3000      framework default

✔ Wrote prisma.compute.ts
? Link this directory to a Prisma Project now? (Y/n)

Next steps:
- prisma-cli app deploy
```

```ts
// generated prisma.compute.ts
import { defineComputeConfig } from "@prisma/compute-sdk/config";

export default defineComputeConfig({
  app: {
    name: "acme-web",
    framework: "nextjs",
    httpPort: 3000,
  },
});
```

More examples:

```bash
prisma-cli init --framework hono --entry src/index.ts   # explicit framework
prisma-cli init --project proj_123                      # write + link, no prompts
prisma-cli init --no-link --json                        # pure file generator (CI/agents)
```

Design notes
- Pins identity only (`name`, `framework`, `httpPort`, `entry` for
entrypoint frameworks, `region` only when passed). No `build` block, so
build-command inference stays live until a user opts into owning it.
`--framework custom` appends a commented `build` stub since custom
artifacts require it.
- `INIT_CONFIG_EXISTS` when any config exists up to the repo root
(nested configs refused, steering monorepos to one root config);
`INIT_DETECTION_FAILED` with the framework list in `--json`, an
interactive picker otherwise.
- Link failures after the write downgrade to warnings; the config stands
and init exits 0.
- `app deploy` success output now hints `Config prisma-cli init` when
the deploy ran on inferred settings.

Testing: 10 new integration tests (572 total green),
lint/typecheck/build clean, plus a live run shown above.

Author: AmanVarshney01

docs/product/command-spec.md

@@ -19,26 +19,32 @@ The beta package includes these command groups:
 - `app`
 - `build` (includes `build logs`)
 
-The beta package also includes one top-level utility command:
+The beta package also includes two top-level commands:
 
 - `version`
+- `init`
 
 `version` is intentionally outside the workflow groups: it reports CLI build and environment state, requires no auth, no project context, and no network, and is the canonical answer to "is this CLI installed and on the build I expect?"
 
+`init` is a top-level workflow verb: it acts on the local project directory
+(writing the committed compute config) rather than managing a remote resource,
+so it sits beside the ORM's verb register (`generate`, `migrate`, `validate`)
+that the unified CLI will absorb. `init` never scaffolds application code;
+creating new apps is `create-prisma`'s job.
+
 The Git repository connection slice uses the `git` group. It does not add a
 provider-specific `GitHub` group.
 
 Out of scope for the current beta:
 
-- `init`
 - `schema`
 - `migrate`
 - product-specific namespaces such as `compute`
 
 ## Global Rules
 
 - Canonical shape is `prisma <group> <action>`.
-- `version` is the one top-level command outside that shape (see Scope above).
+- `version` and `init` are the top-level commands outside that shape (see Scope above).
 - Every command supports `--json`.
 - Shared global flags are:
   - `--json`
@@ -378,6 +384,49 @@ prisma-cli --version --json
 
 `prisma-cli version` is the richer environment report; `prisma-cli --version` is the terse one-liner. Both report the same `cli.version`. Use the flag for quick checks, the subcommand for support tickets and bug reports.
 
+## `prisma-cli init --framework <nextjs|nuxt|astro|hono|nestjs|tanstack-start|bun|custom> --entry <path> --http-port <port> --region <region> --name <app-name> --link --no-link --project <id-or-name> --install --no-install`
+
+Purpose:
+
+- write a committed `prisma.compute.ts` for the app in this directory
+
+Behavior:
+
+- init is the config formalizer: `app deploy` works with zero config, and init writes down what deploy would infer so the setup is committed, reviewable, and stable for teammates and CI
+- writing the config requires no auth and no network; linking is the only remote step
+- fails with `INIT_CONFIG_EXISTS` when a compute config already exists in the invocation directory or any ancestor up to the repository or workspace root; the error names the existing file, and init never overwrites or merges — editing a committed config is the user's editor's job
+- detects the framework from the same registry and signals `app deploy` uses; explicit `--framework` wins over detection
+- `--entry` sets the source entrypoint for entrypoint frameworks (Bun, Hono); `--http-port` overrides the framework default port; `--name` overrides the app name inferred from `package.json#name` or the directory name
+- previews the resolved values with per-value source annotations (`detected`, `framework default`, `package.json`, `flag`) before writing; in interactive mode the preview is followed by an optional adjust step for framework and HTTP port, and `--yes` accepts the preview as shown
+- the generated config pins the app's identity: `name`, `framework`, and `httpPort` always; `entry` when the framework consumes a source entrypoint; `region` only when `--region` is passed, because pinning a region the user did not choose would silently place new apps
+- the generated config does not include a `build` block: build settings stay inferred (and shown with their sources by deploy) until the user adds one, which keeps package-manager and build-script inference live
+- init never scaffolds application code, never creates schema or database resources, and never deploys
+- with `--framework custom`, the config includes a commented `build` stub, since custom artifacts require `build.outputDirectory` and `build.entrypoint` before deploy can use them
+- when detection fails and no `--framework` is passed: interactive mode prompts for the framework from the supported list; non-interactive and `--json` mode fail with `INIT_DETECTION_FAILED`, with `nextActions` enumerating the `--framework` choices
+- types step, after the config is written: the generated config's typed import (`@prisma/compute-sdk/config`) is resolved by the CLI at deploy time without a local install, so a local `@prisma/compute-sdk` devDependency exists purely for editor types
+  - when the package is already a dependency or devDependency, the step is a no-op
+  - interactive mode asks `Install @prisma/compute-sdk for config types?` (default yes) and runs the detected package manager's add command (`pnpm add -D`, `bun add -d`, `yarn add -D`, `npm install -D`)
+  - `--install` runs the install without prompting; `--no-install` skips the step; non-interactive and `--json` mode skip by default
+  - a skipped, declined, or failed install downgrades to a hint or warning with the exact add command in `nextSteps`; the config write stands and init exits 0
+  - a directory without a `package.json` skips the step with the hint
+- link step, after the config is written:
+  - interactive mode asks `Link this directory to a Prisma Project now? (Y/n)` when the directory has no project binding; accepting enters the same picker `project link` uses
+  - `--no-link` suppresses the question; `--link` requires the step; `--project <id-or-name>` links to that project without prompting
+  - link failures and cancellations after the config is written downgrade to warnings and `nextSteps`; the config write stands and init exits 0
+- `nextSteps` includes the deploy command, plus the project link command when the directory is still unlinked
+- user-facing command hints in init output (next steps, link hints, error recovery commands) use the package runner detected from the project, such as `pnpm dlx @prisma/cli@latest project link` or `npx -y @prisma/cli@latest app deploy`, matching the `agent` group's convention
+- in `--json`, `result` includes `configPath`, the written `app` values, per-value `settings` sources, and `link` state; `--json` never prompts
+
+Examples:
+
+```bash
+prisma-cli init
+prisma-cli init --framework hono --entry src/index.ts
+prisma-cli init --name api --http-port 8080 --no-link
+prisma-cli init --project proj_123
+prisma-cli init --json
+```
+
 ## `<runner> @prisma/cli@latest agent install --agent <agent> --all-agents --skill <skill> --global --copy`
 
 Purpose:
@@ -1333,6 +1382,7 @@ Behavior:
 - after setup, deploy prints `Deploying to <Project> / <Branch> / <App>`; later deploys print a compact target header such as `Deploying ./j1 to j1 / main / j1`
 - deploy progress uses short stage copy (`Building locally...`, `Built <size>`, `Uploading...`, `Uploaded`, `Deploying...`, `Deployed`) and never prints `Status: running` or `Deployment is running at ...`
 - success human output prints `Live in <duration>`, the URL on its own line, and `Logs   prisma-cli app logs`
+- when the deploy resolved its settings without a compute config, success human output adds a `Config` hint line with the runner-formatted init command (such as `pnpm dlx @prisma/cli@latest init`), pointing at the command that pins the inferred settings; the hint is omitted once a config file is discovered
 - with `--no-promote`, success human output instead prints `Built <deployment-id> in <duration> (not promoted)`, the candidate URL on its own line, a note that the live deployment is unchanged, and a `Promote   prisma-cli app promote <deployment-id>` next step
 - accepts repeated `--env NAME=VALUE` flags and dotenv file paths such as `--env .env`
 - supports `--db` to create a new empty Prisma Postgres database and write `DATABASE_URL` and `DIRECT_URL` through the existing `project env` storage; the CLI never runs schema or migration commands — applying the schema stays with the user's own tooling
@@ -1728,6 +1778,62 @@ prisma-cli app logs
 prisma-cli app logs --deployment dep_123
 ```
 
+## `prisma-cli build list [app] --app <name> --project <id-or-name> --branch <name> --limit <n>`
+
+Status: blocked on Management API rollout. The `GET /v1/apps/{appId}/builds`
+endpoint exists in the control plane but is not yet deployed or published in
+`@prisma/management-api-sdk`. This section is normative for the implementation
+that lands once the SDK exposes the endpoint.
+
+Purpose:
+
+- list the git build jobs for an app, so build ids are discoverable without the Console
+
+Behavior:
+
+- requires auth and project context
+- resolves the selected app exactly like the other app management commands: `[app]` target argument, `--app`, compute config target, locally selected app, inferred name; never creates apps or branches
+- resolves the branch it reads like management commands: explicit `--branch`, active Git branch when it exists in the project, then the project's default branch
+- lists builds newest first: build id, state (`pending`, `running`, `succeeded`, `failed`, `cancelled`), source (`webhook`, `setup`, `manual`), Git branch, short commit sha, created and finished timestamps, and the produced deployment id when the build reached that stage
+- build ids are the ids `build logs <build-id>` accepts
+- `--limit <n>` caps the number of returned builds; JSON output includes `pagination.nextCursor` and `pagination.hasMore` so agents can page
+- read-only; never prints secret values
+- `nextSteps` includes `prisma-cli build logs <build-id>` for the newest build
+- fails with the standard app selection errors (`APP_AMBIGUOUS`, app not found) when the target cannot be resolved safely
+
+Examples:
+
+```bash
+prisma-cli build list
+prisma-cli build list --app my-app --limit 50
+prisma-cli build list --json
+```
+
+## `prisma-cli build show <build-id>`
+
+Status: blocked on Management API rollout, same as `build list`; the backing
+endpoint is `GET /v1/builds/{buildId}`.
+
+Purpose:
+
+- show one build in detail
+
+Behavior:
+
+- requires auth
+- takes a build id, as shown by `build list`, the Console build view, and git-push output
+- authorization matches `build logs`: access stays with the workspace that owned the build when it ran, and an unknown or foreign build id fails with an indistinguishable `BUILD_NOT_FOUND`
+- shows state, source, Git branch, commit sha, created/started/finished timestamps, the error message when the build failed, and the produced deployment id and deployed URL when present
+- read-only; never prints secret values
+- `nextSteps` includes `prisma-cli build logs <build-id>`
+
+Examples:
+
+```bash
+prisma-cli build show cmcz3v6ft0a1b2c3d
+prisma-cli build show cmcz3v6ft0a1b2c3d --json
+```
+
 ## `prisma-cli build logs <build-id> --follow --cursor <cursor>`
 
 Purpose:

docs/product/error-conventions.md

@@ -187,6 +187,8 @@ These codes are the minimum stable set for the MVP:
 - `BUILD_SETTINGS_MIGRATION_REQUIRED`
 - `BUILD_SETTINGS_UNSUPPORTED`
 - `FRAMEWORK_NOT_DETECTED`
+- `INIT_CONFIG_EXISTS`
+- `INIT_DETECTION_FAILED`
 - `DEPLOYMENT_NOT_FOUND`
 - `NO_DEPLOYMENTS`
 - `NO_PREVIOUS_DEPLOYMENT`
@@ -258,6 +260,8 @@ Recommended meanings:
 - `BUILD_SETTINGS_MIGRATION_REQUIRED`: a legacy `prisma.app.json` contains custom build settings that must move into the `build` block of `prisma.compute.ts`
 - `BUILD_SETTINGS_UNSUPPORTED`: a compute config `build` block targets a framework whose SDK strategy does not consume committed build settings
 - `FRAMEWORK_NOT_DETECTED`: app deploy could not detect a supported Beta framework and no explicit framework/build type was provided
+- `INIT_CONFIG_EXISTS`: a compute config already exists in this directory or an ancestor; init never overwrites or merges
+- `INIT_DETECTION_FAILED`: no supported framework detected and no --framework passed; `meta.frameworks` lists the valid values
 - `DEPLOYMENT_NOT_FOUND`: requested deployment id does not exist
 - `NO_DEPLOYMENTS`: command resolved a branch or app but found no deployments
 - `NO_PREVIOUS_DEPLOYMENT`: rollback could not find an earlier deployment for the selected app

docs/product/resource-model.md

@@ -39,6 +39,7 @@ Rules:
 - Public Beta does not read or write committed config files such as `prisma.config.ts` or `.prisma/settings.json` for project resolution
 - `.prisma/local.json` is a gitignored local pin/cache for Workspace and Project IDs; it is not a declarative repo config file. When a `prisma.compute.ts` is discovered (nearest config from the invocation directory up to the repository or workspace root), the pin and the CLI state cache (`.prisma/cli/state.json`) are read and written in the config file's directory; without a config they stay in the invocation directory
 - `prisma.compute.ts` is a committed deploy-defaults file; it must not contain Workspace, Project, Branch, env-secret, or credential resolution state
+- `init` is the only command that writes `prisma.compute.ts`, and it never overwrites an existing one; deploy reads the config but never writes it
 - Project setup is explicit: users choose an existing Project or explicitly create a new one before remote work starts
 - `app deploy` may orchestrate Project setup, but it must not silently choose or create Project scope
 - everything under a project happens in a branch

packages/cli/src/cli.ts

@@ -9,6 +9,7 @@ import { createBranchCommand } from "./commands/branch";
 import { createBuildCommand } from "./commands/build";
 import { createDatabaseCommand } from "./commands/database";
 import { createGitCommand } from "./commands/git";
+import { createInitCommand } from "./commands/init";
 import { createProjectCommand } from "./commands/project";
 import { createVersionCommand } from "./commands/version";
 import { runVersion } from "./controllers/version";
@@ -83,6 +84,7 @@ export function createProgram(runtime: CliRuntime): Command {
   program.name("prisma").showSuggestionAfterError();
 
   program.addCommand(createVersionCommand(runtime));
+  program.addCommand(createInitCommand(runtime));
   program.addCommand(createAgentCommand(runtime));
   program.addCommand(createAuthCommand(runtime));
   program.addCommand(createProjectCommand(runtime));

packages/cli/src/commands/init/index.ts

@@ -0,0 +1,85 @@
+import { Command, Option } from "commander";
+
+import { runInit } from "../../controllers/init";
+import { renderInit, serializeInit } from "../../presenters/init";
+import { attachCommandDescriptor } from "../../shell/command-meta";
+import { runCommand } from "../../shell/command-runner";
+import { addGlobalFlags } from "../../shell/global-flags";
+import { type CliRuntime, configureRuntimeCommand } from "../../shell/runtime";
+import type { InitResult } from "../../types/init";
+
+export function createInitCommand(runtime: CliRuntime): Command {
+  const command = attachCommandDescriptor(
+    configureRuntimeCommand(new Command("init"), runtime),
+    "init",
+  );
+
+  command
+    .addOption(
+      new Option(
+        "--framework <framework>",
+        "Framework override; detected when omitted",
+      ),
+    )
+    .addOption(
+      new Option(
+        "--entry <path>",
+        "Source entrypoint for entrypoint frameworks (Bun, Hono)",
+      ),
+    )
+    .addOption(new Option("--http-port <port>", "HTTP port the app listens on"))
+    .addOption(
+      new Option(
+        "--region <region>",
+        "Region used when deploy creates the app",
+      ),
+    )
+    .addOption(new Option("--name <app-name>", "App name"))
+    .addOption(new Option("--link", "Link this directory to a Project"))
+    .addOption(new Option("--no-link", "Skip the Project link step"))
+    .addOption(
+      new Option("--project <id-or-name>", "Project to link this directory to"),
+    )
+    .addOption(
+      new Option("--install", "Install @prisma/compute-sdk for config types"),
+    )
+    .addOption(new Option("--no-install", "Skip the types install step"));
+  addGlobalFlags(command);
+
+  command.action(async (options) => {
+    const flags = options as {
+      framework?: string;
+      entry?: string;
+      httpPort?: string;
+      region?: string;
+      name?: string;
+      link?: boolean;
+      project?: string;
+      install?: boolean;
+    };
+
+    await runCommand<InitResult>(
+      runtime,
+      "init",
+      options as Record<string, unknown>,
+      (context) =>
+        runInit(context, {
+          framework: flags.framework,
+          entry: flags.entry,
+          httpPort: flags.httpPort,
+          region: flags.region,
+          name: flags.name,
+          link: flags.link,
+          project: flags.project,
+          install: flags.install,
+        }),
+      {
+        renderHuman: (context, descriptor, result) =>
+          renderInit(context, descriptor, result),
+        renderJson: (result) => serializeInit(result),
+      },
+    );
+  });
+
+  return command;
+}

packages/cli/src/controllers/app.ts

@@ -3777,7 +3777,7 @@ async function resolveDeployBranch(
   };
 }
 
-interface ResolvedDeployFramework {
+export interface ResolvedDeployFramework {
   key: string;
   buildType: FrameworkBuildType;
   displayName: string;
@@ -4074,7 +4074,7 @@ async function resolveDeployEntrypoint(
   }
 }
 
-async function detectDeployFramework(
+export async function detectDeployFramework(
   cwd: string,
   signal: AbortSignal,
 ): Promise<ResolvedDeployFramework | null> {