Brownfield Import¶

forge import analyze turns an existing TypeScript or JavaScript app into a reviewed migration map.

It performs a static scan only. It does not edit source code, execute handlers, create runtime entries, or expose imported operations to agents.

Analyze An Existing App¶

forge import analyze --json
forge import inspect --json
forge inspect imported --json

The analyzer writes:

.forge/import/inventory.json
.forge/import/routes.json
.forge/import/frontendCalls.json
.forge/import/candidateEntries.json
.forge/import/riskReport.json
.forge/import/migrationPlan.md
.forge/import/importedAgentContract.json

What It Detects¶

Surface	Examples
Frameworks	`next`, `react`, `vue`, `nuxt`, `express`, `nest`
Routes	Next.js App Router, Next.js Pages API, Express-style routes, Nest controllers
Frontend calls	`fetch("/api/...")`, `axios.post("/api/...")`
Environment	`process.env.NAME`, `.env.example`, `.env.sample`
Data packages	Prisma, Drizzle, TypeORM, Mongoose, Sequelize, Knex
External packages	Stripe, Resend, SendGrid, Twilio, OpenAI, Anthropic, AWS S3

Safety Defaults¶

Every imported candidate starts with:

{
  "origin": "imported",
  "assurance": "static-scan",
  "reviewStatus": "needs-review",
  "visibleToAgent": false
}

Command-like, destructive, external, or unknown entries also keep:

{
  "needsApproval": true
}

These defaults prevent a static guess from becoming an executable agent tool.

Brownfield classification is intentionally conservative:

route handlers are classified from the most specific handler text ForgeOS can identify, so a read-only GET route is not treated as a write just because a sibling POST in the same file mutates state
mutating methods, destructive paths, database writes, and external side effects remain command-like and approval-required
read-shaped POST /search, /query, /filter, /lookup, and /graphql routes are emitted as kind: "command-candidate" with ambiguous-post-query risk until a human decides whether they should become Forge queries or commands

Import Analysis Versus Adapters¶

Use brownfield import when you need a map. Use an adapter when you need execution.

Need	Use
Discover routes, calls, env usage, and risks in an existing app	`forge import analyze`
Plan a staged migration without changing source code	`forge import analyze`
Expose a Go, Java, or other service as Forge commands and queries	Forge Protocol adapter
Run imported operations through `forge run` or `forge query`	Adapter or native Forge migration

The usual flow is:

Run forge import analyze.
Review riskReport.json and migrationPlan.md.
Convert safe reads to Forge queries.
Convert writes and side effects to commands, actions, or workflows.
Use an adapter when the service should stay external but become executable through Forge.

See Forge Protocol for executable external runtime adapters.