@projitect/cli-internals 0.0.0-stage → 1.0.1

package/src/platform/process-runner.ts

@@ -0,0 +1,150 @@
+import { spawn } from "node:child_process"
+import { Effect, Option } from "effect"
+import { Errors } from "@projitect/core"
+import type { Permission } from "@projitect/core"
+import { isCommandPermitted } from "../permissions.js"
+
+export interface CommandOutput {
+  readonly stdout: string
+  readonly stderr: string
+}
+
+/**
+ * Starts a process and resolves with its exit code and captured output. `exitCode` is `undefined`
+ * only when the process never started (spawn failure); the failure carries the reason. Injected
+ * into `runCommand` so tests can use a fake instead of a real process.
+ */
+export type ProcessSpawner = (
+  program: string,
+  args: readonly string[],
+  cwd: string,
+) => Effect.Effect<CommandOutput & { readonly exitCode: number }, string>
+
+/** Real spawner: `node:child_process` without a shell, so `&&`, `;` and pipes are plain arguments. */
+export const nodeSpawner: ProcessSpawner = (program, args, cwd) =>
+  Effect.callback((resume) => {
+    const child = spawn(program, args, { cwd, shell: false })
+    let stdout = ""
+    let stderr = ""
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout = stdout + chunk.toString("utf8")
+    })
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr = stderr + chunk.toString("utf8")
+    })
+    child.on("error", (error) => {
+      resume(Effect.fail(error.message))
+    })
+    child.on("close", (code) => {
+      resume(Effect.succeed({ exitCode: code ?? 1, stdout, stderr }))
+    })
+    // On interruption, terminate the child we own so it doesn't outlive the fiber.
+    return Effect.sync(() => {
+      child.kill("SIGKILL")
+    })
+  })
+
+/**
+ * Argv contract (no shell): arguments are separated by unquoted whitespace; `'...'` and `"..."`
+ * group characters (including whitespace) into one argument and the quotes are dropped. There are
+ * no escapes, globs, variables or operators — everything else is literal. An unterminated quote,
+ * or a command with no program, is unsupported and yields `None`. The permission is matched
+ * against the raw string, so exactly what was declared is what gets parsed and run.
+ */
+export const parseArgv = (command: string): Option.Option<readonly string[]> => {
+  const argv: string[] = []
+  let current: string | undefined
+  let quote: string | undefined
+  for (const ch of command) {
+    if (quote !== undefined) {
+      if (ch === quote) {
+        quote = undefined
+      } else {
+        current = (current ?? "") + ch
+      }
+    } else if (ch === "'" || ch === '"') {
+      quote = ch
+      current = current ?? ""
+    } else if (/\s/u.test(ch)) {
+      if (current !== undefined) {
+        argv.push(current)
+        current = undefined
+      }
+    } else {
+      current = (current ?? "") + ch
+    }
+  }
+  if (quote !== undefined) {
+    return Option.none()
+  }
+  if (current !== undefined) {
+    argv.push(current)
+  }
+  return argv[0] === undefined || argv[0] === "" ? Option.none() : Option.some(argv)
+}
+
+/** The refusal for a command no declared `exec` permission names exactly. */
+export const commandNotPermitted = (command: string): Errors.CommandNotPermitted =>
+  new Errors.CommandNotPermitted({
+    id: "pjt.exec.command-not-permitted",
+    command,
+    message: `No declared exec permission covers \`${command}\``,
+  })
+
+/**
+ * Runs `command` (parsed per `parseArgv`) in `cwd`, after checking it against
+ * the declared `exec` permissions. A command no permission names exactly fails with
+ * `CommandNotPermitted` and the spawner is never called; a non-zero exit or spawn failure fails
+ * with `CommandFailed` carrying the exit code and captured output; so does a command `parseArgv`
+ * rejects (the spawner is not called).
+ */
+export const runCommand = (params: {
+  readonly permissions: readonly Permission.Permission[]
+  readonly command: string
+  readonly cwd: string
+  readonly spawner: ProcessSpawner
+}): Effect.Effect<CommandOutput, Errors.CommandFailed | Errors.CommandNotPermitted> => {
+  const { permissions, command, cwd, spawner } = params
+  return Effect.gen(function* () {
+    if (!isCommandPermitted(permissions, command)) {
+      return yield* commandNotPermitted(command)
+    }
+    const [program = "", ...args] = yield* Option.match(parseArgv(command), {
+      onNone: () =>
+        Effect.fail(
+          new Errors.CommandFailed({
+            id: "pjt.exec.command-failed",
+            command,
+            stdout: "",
+            stderr: "",
+            cause: "unsupported command syntax: empty program or unterminated quote",
+            message: `Cannot run \`${command}\`: empty program or unterminated quote`,
+          }),
+        ),
+      onSome: Effect.succeed,
+    })
+    const result = yield* Effect.mapError(
+      spawner(program, args, cwd),
+      (cause) =>
+        new Errors.CommandFailed({
+          id: "pjt.exec.command-failed",
+          command,
+          stdout: "",
+          stderr: "",
+          cause,
+          message: `Failed to start \`${command}\`: ${cause}`,
+        }),
+    )
+    if (result.exitCode !== 0) {
+      return yield* new Errors.CommandFailed({
+        id: "pjt.exec.command-failed",
+        command,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        message: `\`${command}\` exited with code ${String(result.exitCode)}`,
+      })
+    }
+    return { stdout: result.stdout, stderr: result.stderr }
+  })
+}

package/src/platform/stdio.ts

@@ -0,0 +1,11 @@
+import { Effect, Stdio } from "effect"
+
+/**
+ * Node-backed `Stdio` Layer. We only need `args` to satisfy `Command.run`'s argv source;
+ * the stdout/stderr sinks and stdin stream from `layerTest` (drain sinks + empty stream) are
+ * adequate because all our output goes through `Terminal.display` and we don't currently read
+ * from stdin outside the `Prompt` module (which uses `Terminal.readLine` / `Terminal.readInput`).
+ */
+export const StdioLive = Stdio.layerTest({
+  args: Effect.succeed(process.argv.slice(2)),
+})

package/src/platform/terminal.ts

@@ -0,0 +1,89 @@
+import * as keypress from "node:readline"
+import * as readline from "node:readline/promises"
+import { Effect, Layer, Option, Queue, Terminal } from "effect"
+import type { Cause } from "effect"
+import * as PlatformError from "effect/PlatformError"
+
+/**
+ * Node-backed `Terminal` Layer.
+ *
+ * - `columns` / `rows` read from `process.stdout` (fall back to sensible defaults when not a TTY)
+ * - `display(text)` writes to `process.stdout` synchronously
+ * - `readLine` uses `node:readline/promises` so `Prompt.text` and `Prompt.confirm` work
+ * - `readInput` (the low-level keypress stream used by `Prompt.select` / `Prompt.multiSelect`)
+ *   puts a TTY stdin into raw mode for the lifetime of the enclosing scope and queues one
+ *   `UserInput` per keypress. Raw mode means Ctrl-C arrives as a keypress rather than as SIGINT,
+ *   so Ctrl-C ends the queue and the prompt fails with `QuitError`.
+ */
+const readInput: Terminal.Terminal["readInput"] = Effect.gen(function* () {
+  const queue = yield* Queue.unbounded<Terminal.UserInput, Cause.Done>()
+  yield* Effect.acquireRelease(
+    Effect.sync(() => {
+      const onKeypress = (input: string | undefined, key: keypress.Key | undefined): void => {
+        Queue.offerUnsafe(queue, {
+          input: Option.fromNullishOr(input),
+          key: {
+            name: key?.name ?? "",
+            ctrl: key?.ctrl ?? false,
+            meta: key?.meta ?? false,
+            shift: key?.shift ?? false,
+          },
+        })
+        if (key?.ctrl === true && key.name === "c") {
+          // Raw mode swallows SIGINT; ending the queue makes the prompt fail with `QuitError`.
+          Queue.endUnsafe(queue)
+        }
+      }
+      keypress.emitKeypressEvents(process.stdin)
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true)
+      }
+      process.stdin.on("keypress", onKeypress)
+      process.stdin.resume()
+      return onKeypress
+    }),
+    (onKeypress) =>
+      Effect.sync(() => {
+        process.stdin.off("keypress", onKeypress)
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(false)
+        }
+        process.stdin.pause()
+      }),
+  )
+  return queue
+})
+
+const make = Terminal.make({
+  // @types/node types columns/rows as non-nullable, but they're undefined on non-TTY stdout.
+  /* eslint-disable @typescript-eslint/no-unnecessary-condition */
+  columns: Effect.sync(() => process.stdout.columns ?? 80),
+  rows: Effect.sync(() => process.stdout.rows ?? 24),
+  /* eslint-enable @typescript-eslint/no-unnecessary-condition */
+  display: (text) =>
+    Effect.try({
+      try: () => {
+        process.stdout.write(text)
+      },
+      catch: (cause) =>
+        PlatformError.badArgument({
+          module: "Terminal",
+          method: "display",
+          description: cause instanceof Error ? cause.message : String(cause),
+        }),
+    }),
+  readLine: Effect.tryPromise({
+    try: async () => {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+      try {
+        return await rl.question("")
+      } finally {
+        rl.close()
+      }
+    },
+    catch: () => new Terminal.QuitError({}),
+  }),
+  readInput,
+})
+
+export const TerminalLive: Layer.Layer<Terminal.Terminal> = Layer.succeed(Terminal.Terminal, make)

package/src/pm.ts

@@ -0,0 +1,163 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { spawn } from "node:child_process"
+import { Array, Effect, Match, Option, Predicate } from "effect"
+import { PredicateX, StructX } from "@nunofyobiz/effect-extras"
+import { Errors } from "@projitect/core"
+import type { ProjitectPackageMetadata } from "@projitect/blueprint"
+
+export type PackageManager = "pnpm" | "npm" | "yarn" | "bun"
+
+const LOCKFILES: readonly (readonly [string, PackageManager])[] = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["bun.lockb", "bun"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"],
+]
+
+/**
+ * Detect the user's package manager from known lockfiles in `projectRoot`.
+ * Without a lockfile, uses the invoking package manager's user-agent, then `npm`.
+ * Used by `pjt add` and first-run bootstrap to select the install command.
+ */
+export const detect = (params: {
+  readonly projectRoot: string
+}): Effect.Effect<PackageManager, Errors.PmNotDetected> =>
+  Effect.map(
+    Effect.findFirst(LOCKFILES, ([filename]) =>
+      Effect.promise(() =>
+        fs.access(path.join(params.projectRoot, filename)).then(
+          () => true,
+          () => false,
+        ),
+      ),
+    ),
+    Option.match({
+      onSome: ([, pm]) => pm,
+      onNone: (): PackageManager =>
+        Match.value(process.env["npm_config_user_agent"] ?? "").pipe(
+          Match.when(
+            (agent) => agent.startsWith("pnpm/"),
+            () => "pnpm" as const,
+          ),
+          Match.when(
+            (agent) => agent.startsWith("yarn/"),
+            () => "yarn" as const,
+          ),
+          Match.when(
+            (agent) => agent.startsWith("bun/"),
+            () => "bun" as const,
+          ),
+          Match.orElse(() => "npm" as const),
+        ),
+    }),
+  )
+
+/**
+ * Run `<pm> add -D <pkg>` in `projectRoot`. Wraps spawn failures (non-zero exit, PM not
+ * installed) as `pjt.pm.install-failed`.
+ */
+export const installDev = (params: {
+  readonly projectRoot: string
+  readonly pm: PackageManager
+  readonly pkg: string
+}): Effect.Effect<void, Errors.PmInstallFailed> =>
+  runInstallation({ ...params, args: installArgs(params.pm, params.pkg) })
+
+/** Synchronize the lockfile after bootstrap has applied its managed manifest ranges. */
+export const installProject = (params: {
+  readonly projectRoot: string
+  readonly pm: PackageManager
+}): Effect.Effect<void, Errors.PmInstallFailed> =>
+  runInstallation({
+    ...params,
+    pkg: "project dependencies",
+    args: params.pm === "pnpm" ? ["install", "--no-frozen-lockfile"] : ["install"],
+  })
+
+const runInstallation = (params: {
+  readonly projectRoot: string
+  readonly pm: PackageManager
+  readonly pkg: string
+  readonly args: readonly string[]
+}): Effect.Effect<void, Errors.PmInstallFailed> =>
+  Effect.tryPromise({
+    try: () =>
+      new Promise<void>((resolve, reject) => {
+        const child = spawn(params.pm, params.args, {
+          cwd: params.projectRoot,
+          stdio: "inherit",
+        })
+        child.on("error", reject)
+        child.on("close", (code) => {
+          if (code === 0) {
+            resolve()
+          } else {
+            reject(new Error(`${params.pm} ${params.args.join(" ")} exited with ${String(code)}`))
+          }
+        })
+      }),
+    catch: (e) =>
+      new Errors.PmInstallFailed({
+        id: "pjt.pm.install-failed",
+        packageManager: params.pm,
+        pkg: params.pkg,
+        cause: e instanceof Error ? e.message : String(e),
+        message: `Failed to install \`${params.pkg}\` via ${params.pm}`,
+      }),
+  })
+
+const installArgs = (pm: PackageManager, pkg: string): readonly string[] =>
+  Match.value(pm).pipe(
+    Match.whenOr("pnpm", "yarn", () => ["add", "-D", pkg]),
+    Match.when("bun", () => ["add", "-d", pkg]),
+    Match.when("npm", () => ["install", "-D", pkg]),
+    Match.exhaustive,
+  )
+
+/**
+ * Read the installed package's `package.json` and return its `"projitect"` metadata, if any.
+ * Returns null if the package doesn't have the field; `pjt add` falls back to install-only
+ * behavior with a printed instruction snippet.
+ */
+export const readProjitectMetadata = (params: {
+  readonly projectRoot: string
+  readonly pkg: string
+}): Effect.Effect<ProjitectPackageMetadata | null> =>
+  Effect.promise(async () => {
+    const pkgJsonPath = path.join(params.projectRoot, "node_modules", params.pkg, "package.json")
+    try {
+      const parsed: unknown = JSON.parse(await fs.readFile(pkgJsonPath, "utf8"))
+      if (!PredicateX.unsafeIsRecord(parsed)) {
+        return null
+      }
+      const meta = parsed["projitect"]
+      if (!PredicateX.unsafeIsRecord(meta)) {
+        return null
+      }
+      const type = meta["type"]
+      const importStmt = meta["import"]
+      if (type !== "blueprint" && type !== "blueprint-set") {
+        return null
+      }
+      if (!Predicate.isString(importStmt)) {
+        return null
+      }
+      const sections = meta["sections"]
+      return {
+        type,
+        import: importStmt,
+        ...StructX.defined("call", Predicate.isString(meta["call"]) ? meta["call"] : undefined),
+        ...StructX.defined(
+          "callTemplate",
+          Predicate.isString(meta["callTemplate"]) ? meta["callTemplate"] : undefined,
+        ),
+        ...StructX.defined(
+          "sections",
+          Array.isArray(sections) ? Array.filter(sections, Predicate.isString) : undefined,
+        ),
+      }
+    } catch {
+      return null
+    }
+  })

package/src/post-apply.ts

@@ -0,0 +1,45 @@
+import { Array, Effect, Option } from "effect"
+import type { Errors } from "@projitect/core"
+import { isCommandPermitted } from "./permissions.js"
+import type { PlannedCommand } from "./plan.js"
+import { commandNotPermitted, nodeSpawner, runCommand } from "./platform/process-runner.js"
+import type { ProcessSpawner } from "./platform/process-runner.js"
+
+/**
+ * The final phase of `build` and `remodel`: run the plan's `Exec` commands once every file
+ * operation has succeeded.
+ *
+ * Every declaring blueprint's permissions must cover its own command; that is checked for the whole
+ * list before any command starts, so a denial never leaves a half-run phase. Identical command
+ * strings run once, at their first position. Commands run sequentially from the project root, in
+ * blueprint tree order then op order, and the first failure stops the phase. Returns the commands
+ * that ran.
+ */
+export const runPostApply = (params: {
+  readonly commands: readonly PlannedCommand[]
+  readonly projectRoot: string
+  readonly spawner?: ProcessSpawner
+}): Effect.Effect<readonly string[], Errors.ExecError> =>
+  Effect.gen(function* () {
+    const { commands, projectRoot, spawner = nodeSpawner } = params
+    const denied = Array.findFirst(
+      commands,
+      (planned) => !isCommandPermitted(planned.permissions, planned.command),
+    )
+    if (Option.isSome(denied)) {
+      return yield* commandNotPermitted(denied.value.command)
+    }
+    const unique = Array.dedupeWith(commands, (a, b) => a.command === b.command)
+    yield* Effect.forEach(
+      unique,
+      (planned) =>
+        runCommand({
+          permissions: planned.permissions,
+          command: planned.command,
+          cwd: projectRoot,
+          spawner,
+        }),
+      { discard: true },
+    )
+    return Array.map(unique, (planned) => planned.command)
+  })

package/src/project-file.ts

@@ -0,0 +1,15 @@
+import { Effect } from "effect"
+import { BlueprintFileSystem } from "@projitect/core"
+
+/**
+ * Read a project-relative file through the `BlueprintFileSystem` service, treating any read
+ * failure as "absent" (`null`). Shared by the lockfile, differ, applier and remover.
+ */
+export const readIfExists = (
+  file: string,
+): Effect.Effect<string | null, never, BlueprintFileSystem> =>
+  Effect.gen(function* () {
+    const fs = yield* BlueprintFileSystem
+    const present = yield* fs.exists(file)
+    return present ? yield* fs.readFile(file) : null
+  }).pipe(Effect.orElseSucceed(() => null))

package/src/region.ts

@@ -0,0 +1,139 @@
+import { Data, Effect, String } from "effect"
+import { StringX } from "@nunofyobiz/effect-extras"
+import { Errors } from "@projitect/core"
+
+/**
+ * Render a region marker. The optional `suffix` covers comment styles that need a closing
+ * delimiter — HTML/MDX/XML need `-->`, everything else passes the empty string. Without a
+ * suffix the marker just runs to end-of-line (the `#` and `//` cases).
+ */
+const START = (prefix: string, owner: string, suffix = ""): string =>
+  `${prefix} ${owner} start${suffix}`
+const END = (prefix: string, owner: string, suffix = ""): string =>
+  `${prefix} ${owner} end${suffix}`
+
+export type RegionLookup = Data.TaggedEnum<{
+  readonly Found: {
+    readonly startLine: number
+    readonly endLine: number
+    readonly content: string
+  }
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- Data.taggedEnum's no-field member shape
+  readonly Absent: {}
+}>
+export const RegionLookup = Data.taggedEnum<RegionLookup>()
+
+/**
+ * Find the existing region for `ownerId` inside `fileContent`. Returns its line range and
+ * content, or `{ kind: "absent" }`. A start marker without an end is a
+ * `pjt.region.missing-end` error; duplicate start markers are `pjt.region.duplicate`.
+ */
+export const findRegion = (params: {
+  readonly fileContent: string
+  readonly ownerId: string
+  readonly commentPrefix: string
+  /**
+   * Optional closing delimiter for the comment style (e.g. `" -->"` for HTML/MDX). Defaults
+   * to the empty string so single-prefix styles (`#`, `//`) stay unchanged.
+   */
+  readonly commentSuffix?: string
+  readonly path: string
+}): Effect.Effect<RegionLookup, Errors.RegionMissingEnd | Errors.RegionDuplicate> => {
+  const { fileContent, ownerId, commentPrefix, commentSuffix = "", path } = params
+  type Result = Effect.Effect<RegionLookup, Errors.RegionMissingEnd | Errors.RegionDuplicate>
+  return Effect.suspend((): Result => {
+    const lines = fileContent.split("\n")
+    const startMarker = START(commentPrefix, ownerId, commentSuffix)
+    const endMarker = END(commentPrefix, ownerId, commentSuffix)
+
+    let startLine = -1
+    let endLine = -1
+    let duplicateStart = false
+
+    for (const [index, line_] of lines.entries()) {
+      const line = line_.trimEnd()
+      if (line === startMarker) {
+        if (startLine === -1) {
+          startLine = index
+        } else {
+          duplicateStart = true
+        }
+      } else if (line === endMarker) {
+        endLine = index
+      }
+    }
+
+    if (duplicateStart) {
+      return Effect.fail(
+        new Errors.RegionDuplicate({
+          id: "pjt.region.duplicate",
+          path,
+          ownerId,
+          message: `Multiple start markers for region ${ownerId} in ${path}`,
+        }),
+      )
+    }
+
+    if (startLine === -1) {
+      return Effect.succeed(RegionLookup.Absent())
+    }
+
+    if (endLine === -1 || endLine < startLine) {
+      return Effect.fail(
+        new Errors.RegionMissingEnd({
+          id: "pjt.region.missing-end",
+          path,
+          ownerId,
+          startLine,
+          message: `Region ${ownerId} started at line ${startLine + 1} of ${path} but never closed`,
+        }),
+      )
+    }
+
+    return Effect.succeed(
+      RegionLookup.Found({
+        startLine,
+        endLine,
+        content: lines.slice(startLine + 1, endLine).join("\n"),
+      }),
+    )
+  })
+}
+
+/**
+ * Render a region block (markers + content) ready to splice into a file.
+ */
+export const renderRegion = (params: {
+  readonly ownerId: string
+  readonly commentPrefix: string
+  readonly commentSuffix?: string
+  readonly content: string
+}): string => {
+  const suffix = params.commentSuffix ?? ""
+  const body = params.content.endsWith("\n") ? params.content.slice(0, -1) : params.content
+  return [
+    START(params.commentPrefix, params.ownerId, suffix),
+    body,
+    END(params.commentPrefix, params.ownerId, suffix),
+  ].join("\n")
+}
+
+/**
+ * Splice or append a region into a file's existing content. Returns the updated text.
+ */
+export const upsertRegion = (params: {
+  readonly fileContent: string
+  readonly existing: RegionLookup
+  readonly rendered: string
+}): string => {
+  const { fileContent, existing, rendered } = params
+  if (existing._tag === "Absent") {
+    if (String.isEmpty(fileContent)) {
+      return `${rendered}\n`
+    }
+    return fileContent.endsWith("\n")
+      ? `${fileContent}${rendered}\n`
+      : `${fileContent}\n${rendered}\n`
+  }
+  return StringX.replaceLineRange(fileContent, existing.startLine, existing.endLine, [rendered])
+}