@projitect/cli-internals 0.0.0-stage → 1.0.1

package/src/commands/dispatch.ts

@@ -0,0 +1,345 @@
+import { Effect, Match, Option, Terminal } from "effect"
+import type { Prompt } from "effect/unstable/cli"
+import { Argument, Command, Flag } from "effect/unstable/cli"
+import type { Errors, ProjitectConfig } from "@projitect/core"
+import { chooseSectionsInteractive } from "@projitect/blueprint"
+import type { SectionStrategy } from "@projitect/blueprint"
+import { parseEnv, resolveConfig } from "../config-cascade.js"
+import { inspect, renderInspectJson } from "./inspect.js"
+import { InspectJsonSchemaUrl } from "./inspect-json.js"
+import { remodel } from "./remodel.js"
+import { build, renderBuildResult } from "./build.js"
+import { init } from "./init.js"
+import { explain } from "./explain.js"
+import { add } from "./add.js"
+
+/**
+ * Per-handler error renderer. Catches our typed `ProjitectError` union and writes a
+ * consistent `Error [id]: message` line plus the docs URL / explain hint — or, with `json`, an
+ * `{ "error": { ... } }` object carrying the error's id and fields. Sets `process.exitCode = 1`
+ * so the CLI exits non-zero. Returns void so the handler chain stays happy.
+ */
+const reportError = (
+  error: Errors.ProjitectError,
+  json = false,
+): Effect.Effect<void, never, Terminal.Terminal> =>
+  Effect.gen(function* () {
+    if (json) {
+      yield* display(`${JSON.stringify({ error }, null, 2)}\n`)
+    } else {
+      yield* display(`Error [${error.id}]: ${error.message}\n`)
+      yield* display(
+        `  See https://projitect.dev/errors/${error.id} or run \`pjt explain ${error.id}\`\n`,
+      )
+    }
+    process.exitCode = 1
+  })
+
+const jsonFlag = (description: string) =>
+  Flag.boolean("json").pipe(Flag.withDefault(false), Flag.withDescription(description))
+
+const display = (text: string): Effect.Effect<void, never, Terminal.Terminal> =>
+  Effect.gen(function* () {
+    const terminal = yield* Terminal.Terminal
+    // Best-effort write; PlatformError on display is non-actionable from a handler
+    yield* Effect.ignore(terminal.display(text))
+  })
+
+const configFromEnv = (): ProjitectConfig.ProjitectConfig =>
+  resolveConfig({
+    env: parseEnv(process.env),
+    cliArgs: { projectRoot: process.cwd() },
+  })
+
+// ---------------------------------------------------------------------------
+// pjt init
+// ---------------------------------------------------------------------------
+
+const initCmd = Command.make(
+  "init",
+  {
+    yes: Flag.boolean("yes").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription(
+        "Auto-bootstrap missing `.git/` (via `git init`) and `package.json` (minimal stub).",
+      ),
+    ),
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const config = configFromEnv()
+      const result = yield* init({ config, yes: input.yes }).pipe(
+        Effect.matchEffect({
+          onSuccess: (r) => Effect.succeed(r),
+          onFailure: (error: Errors.ProjitectError) => reportError(error).pipe(Effect.as(null)),
+        }),
+      )
+      if (result === null) {
+        return
+      }
+      const lines: string[] = []
+      if (result.bootstrappedGit) {
+        lines.push("Initialized git repo (.git/)")
+      }
+      if (result.bootstrappedPackageJson) {
+        lines.push("Created package.json")
+      }
+      if (result.seededBlueprintFile) {
+        lines.push(`Created ${config.blueprintFile}`)
+      }
+      if (result.remodel.written.length > 0) {
+        lines.push(
+          `Wrote ${result.remodel.written.length} file${result.remodel.written.length === 1 ? "" : "s"}:`,
+          ...result.remodel.written.map((p) => `  ${p}`),
+        )
+      }
+      lines.push(
+        "",
+        "projitect initialized. Edit `.pjt.ts` to add blueprints, then run `pnpm pjt remodel`.",
+      )
+      yield* display(`${lines.join("\n")}\n`)
+    }),
+).pipe(Command.withDescription("Bootstrap projitect in the current project."))
+
+// ---------------------------------------------------------------------------
+// pjt remodel
+// ---------------------------------------------------------------------------
+
+const remodelCmd = Command.make(
+  "remodel",
+  {
+    json: jsonFlag("Emit the result, or the error with its id and fields, as JSON."),
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const config = configFromEnv()
+      const result = yield* remodel({ config }).pipe(
+        Effect.matchEffect({
+          onSuccess: (r) => Effect.succeed(r),
+          onFailure: (error: Errors.ProjitectError) =>
+            reportError(error, input.json).pipe(Effect.as(null)),
+        }),
+      )
+      if (result === null) {
+        return
+      }
+      if (input.json) {
+        yield* display(`${JSON.stringify(result, null, 2)}\n`)
+        return
+      }
+      const parts: string[] = []
+      if (result.written.length > 0) {
+        parts.push(
+          `Wrote ${result.written.length} file${result.written.length === 1 ? "" : "s"}:`,
+          ...result.written.map((p) => `  ${p}`),
+        )
+      }
+      if (result.removed.length > 0) {
+        parts.push(
+          `Cleaned up ${result.removed.length} orphan${result.removed.length === 1 ? "" : "s"}:`,
+          ...result.removed.map((p) => `  ${p}`),
+        )
+      }
+      if (result.ran.length > 0) {
+        parts.push(
+          `Ran ${result.ran.length} command${result.ran.length === 1 ? "" : "s"}:`,
+          ...result.ran.map((c) => `  ${c}`),
+        )
+      }
+      if (parts.length === 0) {
+        parts.push("Project already in sync. No changes written.")
+      }
+      yield* display(`${parts.join("\n")}\n`)
+    }),
+).pipe(
+  Command.withDescription(
+    "Apply the blueprint plan to disk (non-destructive), then run post-apply commands.",
+  ),
+)
+
+// ---------------------------------------------------------------------------
+// pjt inspect
+// ---------------------------------------------------------------------------
+
+const inspectCmd = Command.make(
+  "inspect",
+  {
+    json: Flag.boolean("json").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription(
+        `Emit machine-readable JSON output conforming to ${InspectJsonSchemaUrl}; an error is emitted as an \`{ "error": ... }\` object. Exit code still 1 on drift.`,
+      ),
+    ),
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const config = configFromEnv()
+      const result = yield* inspect({ config }).pipe(
+        Effect.matchEffect({
+          onSuccess: (r) => Effect.succeed(r),
+          onFailure: (error: Errors.ProjitectError) =>
+            reportError(error, input.json).pipe(Effect.as(null)),
+        }),
+      )
+      if (result === null) {
+        return
+      }
+      const rendered = input.json ? renderInspectJson(result) : `${result.output}\n`
+      yield* display(rendered)
+      if (result.hasDrift) {
+        process.exitCode = 1
+      }
+    }),
+).pipe(
+  Command.withDescription(
+    "Report drift between project and blueprints (exit 1 on drift; built for CI).",
+  ),
+)
+
+// ---------------------------------------------------------------------------
+// pjt build --force
+// ---------------------------------------------------------------------------
+
+const buildCmd = Command.make(
+  "build",
+  {
+    force: Flag.boolean("force").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription("Required. Wipe the project tree and rebuild from scratch."),
+    ),
+    forceDirty: Flag.boolean("force-dirty").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription("Allow wiping even when git has uncommitted changes."),
+    ),
+    yes: Flag.boolean("yes").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription("Skip the interactive confirmation prompt."),
+    ),
+    json: jsonFlag("Emit the result, or the error with its id and fields, as JSON."),
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const config = configFromEnv()
+      const result = yield* build({
+        config,
+        force: input.force,
+        forceDirty: input.forceDirty,
+        yes: input.yes,
+      }).pipe(
+        Effect.matchEffect({
+          onSuccess: (r) => Effect.succeed(r),
+          onFailure: (error) =>
+            Match.value(error).pipe(
+              // QuitError from Prompt = user pressed Ctrl-C; treat as graceful cancel.
+              Match.tag("QuitError", () => {
+                process.exitCode = 130
+                return display("Cancelled.\n").pipe(Effect.as(null))
+              }),
+              Match.orElse((projitectError) =>
+                reportError(projitectError, input.json).pipe(Effect.as(null)),
+              ),
+            ),
+        }),
+      )
+      if (result === null) {
+        return
+      }
+      if (input.json) {
+        yield* display(`${JSON.stringify(result, null, 2)}\n`)
+        return
+      }
+      yield* display(renderBuildResult(result))
+    }),
+).pipe(
+  Command.withDescription(
+    "Scratch-build the project from blueprints. Destructive — requires --force and clean git.",
+  ),
+)
+
+// ---------------------------------------------------------------------------
+// pjt explain <error-id>
+// ---------------------------------------------------------------------------
+
+const explainCmd = Command.make("explain", { errorId: Argument.string("error-id") }, (input) =>
+  Effect.gen(function* () {
+    const out = yield* explain({ errorId: input.errorId })
+    yield* display(`${out}\n`)
+  }),
+).pipe(Command.withDescription("Print a description of a projitect error id."))
+
+// ---------------------------------------------------------------------------
+// pjt add <package>
+// ---------------------------------------------------------------------------
+
+const addCmd = Command.make(
+  "add",
+  {
+    pkg: Argument.string("package"),
+    section: Flag.string("section").pipe(
+      Flag.optional,
+      Flag.withDescription(
+        "Comma-separated section names for blueprint-set packages (e.g. `--section macOs,node`).",
+      ),
+    ),
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const config = configFromEnv()
+      const explicitSections = Option.match(input.section, {
+        onNone: () => null as readonly string[] | null,
+        onSome: (raw) =>
+          raw
+            .split(",")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0),
+      })
+
+      // When `--section` is given, honor it verbatim. Otherwise: if stdin is a TTY, ask the
+      // user via `Prompt.multiSelect`; if not (CI / piped), fall back to "all" so scripted
+      // installs stay deterministic. The strategy is parametrized over Prompt.Environment so
+      // the requirement propagates out through `add`; Command.run provides the platform.
+      const strategy: SectionStrategy<Prompt.Environment> =
+        explicitSections === null
+          ? process.stdin.isTTY
+            ? { _tag: "Ask", choose: chooseSectionsInteractive }
+            : { _tag: "All" }
+          : { _tag: "Explicit", sections: explicitSections }
+
+      const result = yield* add({ config, pkg: input.pkg, strategy }).pipe(
+        Effect.matchEffect({
+          onSuccess: (r) => Effect.succeed(r),
+          onFailure: (error: Errors.ProjitectError) => reportError(error).pipe(Effect.as(null)),
+        }),
+      )
+      if (result === null) {
+        return
+      }
+      const lines = [`Installed ${result.pkg} via ${result.pm}.`]
+      if (result.splicedIntoBlueprintFile) {
+        if (result.sectionsAdded.length > 0) {
+          lines.push(`Added to ${config.blueprintFile}: ${result.sectionsAdded.join(", ")}.`)
+        } else {
+          lines.push(`Added to ${config.blueprintFile}.`)
+        }
+        lines.push("Run `pjt remodel` to apply.")
+      } else {
+        lines.push(`No sections selected; ${config.blueprintFile} was not changed.`)
+      }
+      yield* display(`${lines.join("\n")}\n`)
+    }),
+).pipe(
+  Command.withDescription(
+    "Install a blueprint package and splice it into .pjt.ts via the marker anchors.",
+  ),
+)
+
+// ---------------------------------------------------------------------------
+// Root
+// ---------------------------------------------------------------------------
+
+export const rootCommand = Command.make("pjt").pipe(
+  Command.withDescription("Project scaffolding that stays in sync — drift-aware blueprints."),
+  Command.withSubcommands([initCmd, remodelCmd, inspectCmd, buildCmd, explainCmd, addCmd]),
+)
+
+export type RootCommand = typeof rootCommand

package/src/commands/explain.ts

@@ -0,0 +1,81 @@
+import { Effect, Option, Schema } from "effect"
+import { Errors } from "@projitect/core"
+
+const ErrorId = Schema.Literals(Errors.ERROR_IDS)
+
+/**
+ * `pjt explain <id>` — print a short description of an error id, with a link to the docs page.
+ * The full content lives on the marketing site at `/errors/<id>`; this CLI gives the basics
+ * without a network call.
+ */
+export const explain = (params: { readonly errorId: string }): Effect.Effect<string> =>
+  Effect.sync(() =>
+    Option.match(Schema.decodeUnknownOption(ErrorId)(params.errorId), {
+      onNone: () =>
+        `Unknown error id: ${params.errorId}\nSee https://projitect.dev/errors for the full registry.`,
+      onSome: (id) => `${id}\n${ERROR_BLURBS[id]}\nMore at: ${Errors.docsUrl(id)}`,
+    }),
+  )
+
+const ERROR_BLURBS: Readonly<Record<Errors.ErrorId, string>> = {
+  "pjt.fs.permission-denied":
+    "A blueprint attempted a filesystem operation outside its declared permissions. Check the blueprint's `permissions` array.",
+  "pjt.fs.read-failed":
+    "A read operation failed at the OS level (typically ENOENT or EACCES). The cause is printed alongside.",
+  "pjt.fs.write-failed":
+    "A write operation failed at the OS level. The cause is printed alongside.",
+  "pjt.loader.import-failed":
+    "The `.pjt.ts` file could not be imported. Check for syntax errors or missing dependencies.",
+  "pjt.loader.invalid-default-export":
+    "`.pjt.ts` must `export default pjt({...})`. Found a different shape.",
+  "pjt.config.invalid":
+    "A config value failed schema validation. The offending field and source layer are reported.",
+  "pjt.config.blueprint-file-not-found":
+    "No `.pjt.ts` at the project root. Run `pjt init` to create one.",
+  "pjt.plan.conflict-region":
+    "Two blueprints share the same `ownerId` for a region in the same file. Pick distinct ids.",
+  "pjt.plan.conflict-merge":
+    "Two blueprints claim the same JSON key in the same file. Coordinate ownership.",
+  "pjt.plan.conflict-owned":
+    "Two blueprints both claim full ownership of one file. Only one `ownFile` per path is allowed.",
+  "pjt.skills.invalid-path":
+    "A skill name, target root or file path is empty, absolute, or tries to leave the skills directory — or a skill has no `SKILL.md`.",
+  "pjt.region.missing-end":
+    "A region start marker was found without a matching end marker. The file has been hand-edited and the closing marker removed.",
+  "pjt.region.duplicate": "Multiple start markers for the same region in one file. Hand-edited?",
+  "pjt.apply.dirty-git":
+    "`build` requires a clean git working tree. Commit or stash first, then retry.",
+  "pjt.init.git-missing":
+    "`pjt init` requires a git repository. Run `git init` first, or rerun with --yes.",
+  "pjt.init.package-json-missing":
+    "`pjt init` requires a `package.json`. Run `npm init -y` first, or rerun with --yes.",
+  "pjt.drift.detected":
+    "`pjt inspect` exits nonzero when the project drifts from its blueprints. Run `pjt remodel` to sync.",
+  "pjt.lock.parse-failed":
+    "`.pjt.lock` is corrupted or doesn't match the expected schema. Delete it and rerun `pjt remodel` to rebuild.",
+  "pjt.lock.version-mismatch":
+    "`.pjt.lock` was written by a newer projitect than the one currently installed. Upgrade the `projitect` devDep.",
+  "pjt.git.not-a-repo": "Required a git repository, but `.git/` was missing. Run `git init` first.",
+  "pjt.git.command-failed":
+    "A `git` command exited non-zero or git isn't installed. The underlying error is included in the message.",
+  "pjt.exec.command-failed":
+    "A command run by projitect exited non-zero or could not be started. Its exit code, stdout and stderr are included.",
+  "pjt.exec.command-not-permitted":
+    "A blueprint tried to run a command that none of its declared `exec` permissions names exactly.",
+  "pjt.inspect.operation-unsupported":
+    "`pjt inspect` cannot check a project whose blueprints declare post-apply commands, so it fails instead of reporting clean.",
+  "pjt.pm.not-detected":
+    "Could not figure out which package manager you're using. Add a lockfile (`pnpm-lock.yaml`, `package-lock.json`, etc.) at your project root.",
+  "pjt.pm.install-failed":
+    "The package manager install command exited non-zero. The underlying error is included in the message.",
+  "pjt.add.markers-missing":
+    "Your `.pjt.ts` is missing the marker comment pairs `pjt:imports` and `pjt:blueprints`. `pjt add` uses those as splice anchors. Restore them and re-run.",
+  "pjt.add.metadata-missing":
+    "The package you added has no `projitect` field in its package.json, so `pjt add` can't splice it. Import it in `.pjt.ts` by hand, then run `pjt remodel`.",
+  "pjt.worker.crashed":
+    "The worker process that runs blueprint code crashed before it returned a result. The exit code or signal is included in the message.",
+  "pjt.worker.timed-out":
+    "The worker process that runs blueprint code did not finish within its time limit and was stopped. Check for a blueprint that never completes.",
+  "pjt.worker.exited-early":
+    "The worker process that runs blueprint code exited before it finished its work. The exit code or signal is included in the message.",
+}

package/src/commands/init.ts

@@ -0,0 +1,233 @@
+import { promises as fs } from "node:fs"
+import { spawn } from "node:child_process"
+import { createRequire } from "node:module"
+import path from "node:path"
+import { Array, Effect, Option, Schema } from "effect"
+import { Errors } from "@projitect/core"
+import type { ProjitectConfig } from "@projitect/core"
+import { detect, installDev as installDevelopment, installProject } from "../pm.js"
+import { remodel } from "./remodel.js"
+import type { RemodelResult } from "./remodel.js"
+
+const manifest = Schema.decodeUnknownSync(
+  Schema.Struct({
+    version: Schema.String,
+    peerDependencies: Schema.Struct({ effect: Schema.String }),
+  }),
+)(createRequire(import.meta.url)("../../package.json"))
+
+export interface InitResult {
+  readonly seededBlueprintFile: boolean
+  readonly bootstrappedGit: boolean
+  readonly bootstrappedPackageJson: boolean
+  readonly remodel: RemodelResult
+}
+
+/**
+ * `pjt init` — bootstrap projitect in the current project.
+ *
+ * Verifies the prerequisites (`.git/` and `package.json` both present), seeds an empty
+ * `.pjt.ts` with the marker structure if absent, then delegates to `remodel` which runs the
+ * standard plan/apply/lockfile-write pipeline. The projitect blueprint (prepended automatically
+ * by `@projitect/cli`'s `pjt()`) writes the package.json entries and the `.pjt.ts` import region
+ * on its first apply. Before seeding or loading the config, missing local CLI and Effect
+ * dependencies are installed so an ephemeral dlx invocation can resolve those imports.
+ *
+ * With `yes: true`, both prerequisites are auto-bootstrapped instead of erroring:
+ *   - Missing `.git/` → `git init -q` shell-out.
+ *   - Missing `package.json` → a minimal stub is written (`{ "name": "<dirname>", ... }`).
+ * This is what CI / scripted setups use (`pjt init --yes`); the interactive flow keeps the
+ * stricter prerequisite checks so a typo doesn't accidentally create a git repo in `$HOME`.
+ *
+ * No special-case code for "the projitect bootstrap" lives here — the projitect blueprint owns
+ * those concerns and runs through the same pipeline as every other blueprint.
+ */
+export const init = (params: {
+  readonly config: ProjitectConfig.ProjitectConfig
+  readonly yes?: boolean
+}): Effect.Effect<InitResult, Errors.ProjitectError> =>
+  Effect.gen(function* () {
+    const bootstrappedGit = yield* ensureGit(params.config.projectRoot, params.yes ?? false)
+    const bootstrappedPackageJson = yield* ensurePackageJson(
+      params.config.projectRoot,
+      params.yes ?? false,
+    )
+
+    const bootstrapPm = yield* ensureBootstrapDependencies(params.config.projectRoot)
+
+    const seededBlueprintFile = yield* seedBlueprintFileIfAbsent(
+      params.config.projectRoot,
+      params.config.blueprintFile,
+    )
+
+    const remodelResult = yield* remodel({ config: params.config })
+    yield* Option.match(bootstrapPm, {
+      onNone: () => Effect.void,
+      onSome: (pm) => installProject({ projectRoot: params.config.projectRoot, pm }),
+    })
+
+    return {
+      seededBlueprintFile,
+      bootstrappedGit,
+      bootstrappedPackageJson,
+      remodel: remodelResult,
+    }
+  })
+
+/** A dlx runner lives outside the project; generated imports must resolve locally first. */
+const ensureBootstrapDependencies = (projectRoot: string) =>
+  Effect.forEach(
+    [
+      { name: "@projitect/cli", spec: `@projitect/cli@${manifest.version}` },
+      { name: "effect", spec: `effect@${manifest.peerDependencies.effect}` },
+    ],
+    ({ name, spec }) =>
+      Effect.gen(function* () {
+        const installed = yield* Effect.promise(() =>
+          fs.access(path.join(projectRoot, "node_modules", name, "package.json")).then(
+            () => true,
+            () => false,
+          ),
+        )
+        if (installed) {
+          return Option.none()
+        }
+        const pm = yield* detect({ projectRoot })
+        yield* installDevelopment({ projectRoot, pm, pkg: spec })
+        return Option.some(pm)
+      }),
+  ).pipe(Effect.map((results) => Array.head(Array.getSomes(results))))
+
+const ensureGit = (
+  projectRoot: string,
+  yes: boolean,
+): Effect.Effect<boolean, Errors.InitGitMissing> =>
+  Effect.gen(function* () {
+    const ok = yield* Effect.promise(() =>
+      fs.access(path.join(projectRoot, ".git")).then(
+        () => true,
+        () => false,
+      ),
+    )
+    if (ok) {
+      return false
+    }
+    if (!yes) {
+      return yield* new Errors.InitGitMissing({
+        id: "pjt.init.git-missing",
+        message:
+          "No `.git` directory found. Run `git init` and then `pjt init` again, or run `pjt init --yes` to create the repository for you.",
+      })
+    }
+    yield* Effect.promise(
+      () =>
+        new Promise<void>((resolve, reject) => {
+          const child = spawn("git", ["init", "-q"], { cwd: projectRoot, stdio: "ignore" })
+          child.on("error", reject)
+          child.on("close", (code) => {
+            if (code === 0) {
+              resolve()
+            } else {
+              reject(new Error(`git init exited with ${String(code)}`))
+            }
+          })
+        }),
+    )
+    return true
+  })
+
+const ensurePackageJson = (
+  projectRoot: string,
+  yes: boolean,
+): Effect.Effect<boolean, Errors.InitPackageJsonMissing | Errors.FsWriteFailed> =>
+  Effect.gen(function* () {
+    const ok = yield* Effect.promise(() =>
+      fs.access(path.join(projectRoot, "package.json")).then(
+        () => true,
+        () => false,
+      ),
+    )
+    if (ok) {
+      return false
+    }
+    if (!yes) {
+      return yield* new Errors.InitPackageJsonMissing({
+        id: "pjt.init.package-json-missing",
+        message:
+          "No `package.json` found. Run `npm init -y` (or your PM equivalent) first, then re-run `pjt init` — or pass `--yes` to auto-bootstrap.",
+      })
+    }
+    const name = path.basename(projectRoot) || "project"
+    const stub = {
+      name,
+      version: "0.0.0",
+      private: true,
+      type: "module" as const,
+    }
+    yield* Effect.tryPromise({
+      try: () =>
+        fs.writeFile(
+          path.join(projectRoot, "package.json"),
+          `${JSON.stringify(stub, null, 2)}\n`,
+          "utf8",
+        ),
+      catch: (e) =>
+        new Errors.FsWriteFailed({
+          id: "pjt.fs.write-failed",
+          path: "package.json",
+          cause: e instanceof Error ? e.message : String(e),
+          message: "Failed to seed package.json during `pjt init --yes`",
+        }),
+    })
+    return true
+  })
+
+const seedBlueprintFileIfAbsent = (
+  projectRoot: string,
+  blueprintFile: string,
+): Effect.Effect<boolean, Errors.FsWriteFailed> =>
+  Effect.gen(function* () {
+    const full = path.join(projectRoot, blueprintFile)
+    const exists = yield* Effect.promise(() =>
+      fs.access(full).then(
+        () => true,
+        () => false,
+      ),
+    )
+    if (exists) {
+      return false
+    }
+
+    yield* Effect.tryPromise({
+      try: () => fs.writeFile(full, STARTER_PJT_TS, "utf8"),
+      catch: (e) =>
+        new Errors.FsWriteFailed({
+          id: "pjt.fs.write-failed",
+          path: blueprintFile,
+          cause: e instanceof Error ? e.message : String(e),
+          message: `Failed to seed ${blueprintFile}`,
+        }),
+    })
+    return true
+  })
+
+/**
+ * Starter `.pjt.ts` template. Three marker regions: the projitect blueprint owns
+ * `pjt:projitect:imports` (it writes the `import { pjt } from "@projitect/cli"` line on first
+ * remodel). The other two — `pjt:imports` and `pjt:blueprints` — are **convention anchors**
+ * that `pjt add` splices into; they are not managed regions and don't appear in `.pjt.lock`.
+ */
+const STARTER_PJT_TS = `// pjt:projitect:imports start
+import { pjt } from "@projitect/cli"
+// pjt:projitect:imports end
+
+// pjt:imports start
+// pjt:imports end
+
+export default pjt({
+  blueprints: [
+    // pjt:blueprints start
+    // pjt:blueprints end
+  ],
+})
+`