@projitect/cli-internals 0.0.0-stage → 1.0.1

package/src/commands/inspect-json.ts

@@ -0,0 +1,68 @@
+import { Schema } from "effect"
+import { PjtLock } from "@projitect/core"
+
+/**
+ * Versioned URL for the published `pjt inspect --json` contract. Doubles as the `$id` of the
+ * generated JSON Schema document and the `$schema` value every `--json` output carries. Bumps to
+ * `inspect.v2.json` only on a breaking change to the output shape, shipped in a major release.
+ */
+export const InspectJsonSchemaUrl = "https://projitect.dev/schemas/inspect.v1.json"
+
+/**
+ * Effect Schema for the `pjt inspect --json` output. `renderInspectJson` encodes through this so
+ * the TypeScript types it's built from (`FileDiff`, `UpgradeRecord`, `PjtLock.LockOperation`) are
+ * checked against it at compile time, and the published JSON Schema file is generated from this
+ * same definition — it can't drift from the code that produces the output.
+ */
+export const InspectJson = Schema.Struct({
+  $schema: Schema.Literal(InspectJsonSchemaUrl).annotate({
+    description: "Identifies the published JSON Schema this output conforms to.",
+  }),
+  hasDrift: Schema.Boolean.annotate({
+    description: "Whether the project has drifted from its blueprints or lockfile.",
+  }),
+  files: Schema.Array(
+    Schema.Struct({
+      path: Schema.String,
+      status: Schema.Literals(["create", "modify", "ok"]).annotate({
+        description:
+          '"create" — file absent, will be created; "modify" — exists but content drifts; "ok" — in sync.',
+      }),
+      summary: Schema.String,
+    }),
+  ).annotate({ description: "Per-file drift status, one entry per managed file." }),
+  removals: Schema.Array(PjtLock.LockOperation).annotate({
+    description: "Operations recorded in the lockfile whose owning blueprint has left the tree.",
+  }),
+  upgrades: Schema.Array(
+    Schema.Struct({
+      blueprintId: Schema.String,
+      from: Schema.String,
+      to: Schema.String,
+    }),
+  ).annotate({
+    description: "Blueprints whose locked version differs from the tree's current version.",
+  }),
+}).annotate({
+  title: "pjt inspect --json output",
+  description:
+    "Structured drift report for `pjt inspect --json`. New keys may be added within this version; removing or renaming a key requires a new schema version.",
+})
+
+export type InspectJson = typeof InspectJson.Type
+
+/**
+ * The published schema file's contents — generated from {@link InspectJson}, never hand-edited.
+ * `additionalProperties: true` keeps the documented promise that new keys may be added within a
+ * version without breaking consumers.
+ */
+export const inspectJsonSchemaDocument = (): Record<string, unknown> => {
+  const doc = Schema.toJsonSchemaDocument(InspectJson, { additionalProperties: true })
+  const hasDefinitions = Object.keys(doc.definitions).length > 0
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: InspectJsonSchemaUrl,
+    ...doc.schema,
+    ...(hasDefinitions ? { $defs: doc.definitions } : {}),
+  }
+}

package/src/commands/inspect.ts

@@ -0,0 +1,106 @@
+import { Array, Effect, Schema } from "effect"
+import { Errors } from "@projitect/core"
+import type { PjtLock, ProjitectConfig } from "@projitect/core"
+import { loadBlueprintFile, isEffectTree } from "../loader.js"
+import type { BlueprintTree } from "../loader.js"
+import { buildPlan, diffLockfile } from "../plan.js"
+import type { UpgradeRecord } from "../plan.js"
+import { diffPlan, renderInspectReport } from "../differ.js"
+import type { FileDiff } from "../differ.js"
+import { makeProjectRootLayer, makeRealLayer } from "../filesystem-impl.js"
+import { readLockfile } from "../lockfile.js"
+import { InspectJson, InspectJsonSchemaUrl } from "./inspect-json.js"
+
+/**
+ * Result of `pjt inspect`. `output` is the human-readable rendering; the structured fields
+ * (`files`, `removals`, `upgrades`) are what `--json` mode emits. Both representations are
+ * always computed — switching modes is just a renderer choice.
+ */
+export interface InspectResult {
+  readonly hasDrift: boolean
+  readonly output: string
+  readonly files: readonly FileDiff[]
+  readonly removals: readonly PjtLock.LockOperation[]
+  readonly upgrades: readonly UpgradeRecord[]
+}
+
+/**
+ * `pjt inspect` — load the blueprint file, build the plan, diff against disk + lockfile, and
+ * return both a human-readable summary and the structured pieces a `--json` consumer needs.
+ *
+ * The dispatcher decides which representation to print; the command keeps the `hasDrift`
+ * boolean separate so the bin shim can set exit code 1 regardless of output mode (`pjt inspect
+ * --json` still exits nonzero on drift, which CI relies on for the "in spec / out of spec"
+ * promise).
+ */
+export const inspect = (params: {
+  readonly config: ProjitectConfig.ProjitectConfig
+}): Effect.Effect<InspectResult, Errors.ProjitectError> =>
+  Effect.gen(function* () {
+    const file = yield* loadBlueprintFile({
+      blueprintFile: params.config.blueprintFile,
+      projectRoot: params.config.projectRoot,
+    })
+    const tree: BlueprintTree = isEffectTree(file.blueprints)
+      ? yield* file.blueprints.pipe(
+          Effect.provide(
+            makeRealLayer({
+              blueprintId: "pjt:config-loader",
+              permissions: [{ kind: "read", glob: "**" }],
+              projectRoot: params.config.projectRoot,
+            }),
+          ),
+        )
+      : file.blueprints
+    const { plan, byBlueprint } = yield* buildPlan({
+      tree,
+      projectRoot: params.config.projectRoot,
+    })
+    // Fail closed: commands cannot be diffed yet, so a clean report would be a false one.
+    if (Array.isReadonlyArrayNonEmpty(plan.commands)) {
+      return yield* new Errors.OperationUnsupportedOnInspect({
+        id: "pjt.inspect.operation-unsupported",
+        operation: "Exec",
+        message: `\`pjt inspect\` cannot check post-apply commands, and ${plan.commands.length === 1 ? "1 is" : `${plan.commands.length} are`} declared (first: \`${plan.commands[0].command}\`).`,
+      })
+    }
+    return yield* Effect.gen(function* () {
+      const previous = yield* readLockfile
+      const { removals, upgrades } = diffLockfile({ previous, current: byBlueprint })
+      const diff = yield* diffPlan({ plan })
+      const hasDrift = diff.hasDrift || removals.length > 0
+      return {
+        hasDrift,
+        output: withNextStep(renderInspectReport({ diff, removals, upgrades }), hasDrift),
+        files: diff.files,
+        removals,
+        upgrades,
+      }
+    }).pipe(Effect.provide(makeProjectRootLayer(params.config.projectRoot)))
+  })
+
+const withNextStep = (report: string, hasDrift: boolean): string =>
+  hasDrift ? `${report}\n\nDrift detected. Run \`pjt remodel\` to apply the blueprints.` : report
+
+/**
+ * Render the inspect result as a stable JSON object for CI / scripting, conforming to the
+ * published JSON Schema at {@link InspectJsonSchemaUrl} (also published at
+ * `apps/website/public/schemas/inspect.v1.json`). The `$schema` key names that contract.
+ *
+ * Stable means: keys won't be renamed or removed without a major bump (and a new schema
+ * version). New keys may be added at either level within a version; consumers should ignore
+ * unknown keys. Encoding through {@link InspectJson} ties this output to the same definition the
+ * schema is generated from, so the two can't drift apart.
+ */
+export const renderInspectJson = (result: InspectResult): string =>
+  `${JSON.stringify(
+    Schema.encodeSync(InspectJson)({
+      $schema: InspectJsonSchemaUrl,
+      hasDrift: result.hasDrift,
+      files: result.files,
+      removals: result.removals,
+      upgrades: result.upgrades,
+    }),
+    null,
+    2,
+  )}\n`

package/src/commands/remodel.ts

@@ -0,0 +1,72 @@
+import { Effect } from "effect"
+import { StructX } from "@nunofyobiz/effect-extras"
+import type { Errors, PjtLock, ProjitectConfig } from "@projitect/core"
+import { loadBlueprintFile, isEffectTree } from "../loader.js"
+import type { BlueprintTree } from "../loader.js"
+import { buildPlan, diffLockfile } from "../plan.js"
+import { applyPlan } from "../applier.js"
+import { applyRemovals } from "../remover.js"
+import { makeProjectRootLayer, makeRealLayer } from "../filesystem-impl.js"
+import { readLockfile, writeLockfile } from "../lockfile.js"
+import { runPostApply } from "../post-apply.js"
+import type { ProcessSpawner } from "../platform/process-runner.js"
+
+export interface RemodelResult {
+  readonly written: readonly string[]
+  readonly removed: readonly string[]
+  /** Post-apply commands that ran, deduplicated, in the order they ran. */
+  readonly ran: readonly string[]
+}
+
+/**
+ * `pjt remodel` — load blueprints, build the plan, apply changes to disk, rewrite `.pjt.lock`,
+ * then run the blueprints' post-apply commands.
+ * Non-destructive at the file-tree level: only touches files the plan covers (additions) and
+ * files where a blueprint that previously had ownership left the tree (removals). Commands run
+ * only after every file operation and the lockfile write have succeeded. `spawner` replaces the
+ * real process spawner in tests.
+ */
+export const remodel = (params: {
+  readonly config: ProjitectConfig.ProjitectConfig
+  readonly spawner?: ProcessSpawner
+}): Effect.Effect<RemodelResult, Errors.ProjitectError> =>
+  Effect.gen(function* () {
+    const file = yield* loadBlueprintFile({
+      blueprintFile: params.config.blueprintFile,
+      projectRoot: params.config.projectRoot,
+    })
+    const tree: BlueprintTree = isEffectTree(file.blueprints)
+      ? yield* file.blueprints.pipe(
+          Effect.provide(
+            makeRealLayer({
+              blueprintId: "pjt:config-loader",
+              permissions: [{ kind: "read", glob: "**" }],
+              projectRoot: params.config.projectRoot,
+            }),
+          ),
+        )
+      : file.blueprints
+
+    const { plan, byBlueprint } = yield* buildPlan({
+      tree,
+      projectRoot: params.config.projectRoot,
+    })
+    return yield* Effect.gen(function* () {
+      const previous = yield* readLockfile
+      const { removals } = diffLockfile({ previous, current: byBlueprint })
+
+      const written = yield* applyPlan({ plan })
+      const removed = yield* applyRemovals({ removals })
+
+      const nextLock: PjtLock.PjtLock = { version: 1, blueprints: byBlueprint }
+      yield* writeLockfile({ lock: nextLock })
+
+      const ran = yield* runPostApply({
+        commands: plan.commands,
+        projectRoot: params.config.projectRoot,
+        ...StructX.defined("spawner", params.spawner),
+      })
+
+      return { written, removed, ran }
+    }).pipe(Effect.provide(makeProjectRootLayer(params.config.projectRoot)))
+  })

package/src/config-cascade.ts

@@ -0,0 +1,60 @@
+import { StructX } from "@nunofyobiz/effect-extras"
+import { ProjitectConfig } from "@projitect/core"
+
+/** Partial config with mutable properties — for building up an override layer locally. */
+export type WritablePartialConfig = {
+  -readonly [K in keyof ProjitectConfig.ProjitectConfig]?: ProjitectConfig.ProjitectConfig[K]
+}
+
+/**
+ * Resolve the four config layers into a single `ProjitectConfig`. Later layers win.
+ *
+ * Layers, in priority order (low to high):
+ *   1. `ProjitectConfig.defaults`
+ *   2. `env`: parsed `PJT_*` environment variables
+ *   3. `blueprintFile`: the `config:` field of the user's `.pjt.ts`
+ *   4. `cliArgs`: command-line overrides
+ */
+export const resolveConfig = (layers: {
+  readonly env?: WritablePartialConfig
+  readonly blueprintFile?: WritablePartialConfig
+  readonly cliArgs?: WritablePartialConfig
+}): ProjitectConfig.ProjitectConfig =>
+  // Absent layers map to `{}` — the cascade reducer's identity, so they fold as a no-op.
+  ProjitectConfig.resolve(layers.env ?? {}, layers.blueprintFile ?? {}, layers.cliArgs ?? {})
+
+/**
+ * Parse the relevant `PJT_*` environment variables into a partial config. Unknown vars are
+ * ignored. Boolean vars accept `1`/`0`/`true`/`false`; numeric vars are parsed with `Number`.
+ */
+export const parseEnv = (
+  env: Readonly<Record<string, string | undefined>>,
+): WritablePartialConfig =>
+  StructX.filterDefined({
+    projectRoot: env["PJT_PROJECT_ROOT"],
+    blueprintFile: env["PJT_BLUEPRINT_FILE"],
+    requireCleanGit: parseBool(env["PJT_REQUIRE_CLEAN_GIT"]),
+    jsonOutput: parseBool(env["PJT_JSON_OUTPUT"]),
+    verbosity: parseNumber(env["PJT_VERBOSITY"]),
+  })
+
+const parseBool = (v: string | undefined): boolean | undefined => {
+  if (v === undefined) {
+    return undefined
+  }
+  if (v === "1" || v.toLowerCase() === "true") {
+    return true
+  }
+  if (v === "0" || v.toLowerCase() === "false") {
+    return false
+  }
+  return undefined
+}
+
+const parseNumber = (v: string | undefined): number | undefined => {
+  if (v === undefined) {
+    return undefined
+  }
+  const n = Number(v)
+  return Number.isFinite(n) ? n : undefined
+}

package/src/differ.ts

@@ -0,0 +1,188 @@
+import { Array, Effect, Match } from "effect"
+import type { BlueprintFileSystem, PjtLock, Errors } from "@projitect/core"
+import { RecordX } from "@nunofyobiz/effect-extras"
+import { readIfExists } from "./project-file.js"
+import { findRegion } from "./region.js"
+import type {
+  FilePlan,
+  ProjectPlan,
+  RegionPlanFile,
+  MergePlanFile,
+  OwnedPlanFile,
+  SeedPlanFile,
+  UpgradeRecord,
+} from "./plan.js"
+
+export interface FileDiff {
+  readonly path: string
+  /** "create" — file absent, will be created; "modify" — exists but content drifts; "ok" — in sync. */
+  readonly status: "create" | "modify" | "ok"
+  readonly summary: string
+}
+
+export interface PlanDiff {
+  readonly files: readonly FileDiff[]
+  readonly hasDrift: boolean
+}
+
+/**
+ * Compare each file in the plan against the project filesystem. Returns a structured diff suitable for either
+ * human rendering (`renderPlanDiff`) or machine consumption (`--json`).
+ */
+export const diffPlan = (params: {
+  readonly plan: ProjectPlan
+}): Effect.Effect<
+  PlanDiff,
+  Errors.RegionMissingEnd | Errors.RegionDuplicate,
+  BlueprintFileSystem
+> => {
+  const { plan } = params
+  return Effect.gen(function* () {
+    const files = yield* Effect.forEach(plan.files, (file) =>
+      readIfExists(file.path).pipe(Effect.flatMap((current) => diffFile({ file, current }))),
+    )
+    const hasDrift = Array.some(files, (file) => file.status !== "ok")
+    return { files, hasDrift }
+  })
+}
+
+const diffFile = (params: {
+  readonly file: FilePlan
+  readonly current: string | null
+}): Effect.Effect<FileDiff, Errors.RegionMissingEnd | Errors.RegionDuplicate> =>
+  Match.valueTags(params.file, {
+    Region: (file) => diffRegion(file, params.current),
+    Merge: (file) => Effect.succeed(diffMerge(file, params.current)),
+    Owned: (file) => Effect.succeed(diffOwned(file, params.current)),
+    Seed: (file) => Effect.succeed(diffSeed(file, params.current)),
+  })
+
+const diffRegion = (
+  file: RegionPlanFile,
+  current: string | null,
+): Effect.Effect<FileDiff, Errors.RegionMissingEnd | Errors.RegionDuplicate> =>
+  Effect.gen(function* () {
+    if (current === null) {
+      return {
+        path: file.path,
+        status: "create" as const,
+        summary: `+ create ${file.path} (${file.regions.length} region${file.regions.length === 1 ? "" : "s"})`,
+      }
+    }
+    const drifted: string[] = []
+    for (const region of file.regions) {
+      const found = yield* findRegion({
+        fileContent: current,
+        ownerId: region.ownerId,
+        commentPrefix: file.commentPrefix,
+        commentSuffix: file.commentSuffix,
+        path: file.path,
+      })
+      const expected = region.content.trimEnd()
+      if (found._tag === "Absent") {
+        drifted.push(`missing region ${region.ownerId}`)
+      } else if (found.content.trimEnd() !== expected) {
+        drifted.push(`region ${region.ownerId} content drift`)
+      }
+    }
+    if (drifted.length === 0) {
+      return { path: file.path, status: "ok" as const, summary: `  ok ${file.path}` }
+    }
+    return {
+      path: file.path,
+      status: "modify" as const,
+      summary: `~ modify ${file.path} — ${drifted.join(", ")}`,
+    }
+  })
+
+const diffMerge = (file: MergePlanFile, current: string | null): FileDiff => {
+  if (current === null) {
+    return {
+      path: file.path,
+      status: "create",
+      summary: `+ create ${file.path}`,
+    }
+  }
+  try {
+    const parsed = JSON.parse(current) as unknown
+    const target = RecordX.deepMerge(parsed, file.value)
+    if (canonicalJson(parsed) === canonicalJson(target)) {
+      return { path: file.path, status: "ok", summary: `  ok ${file.path}` }
+    }
+    return {
+      path: file.path,
+      status: "modify",
+      summary: `~ modify ${file.path} (JSON merge)`,
+    }
+  } catch {
+    return {
+      path: file.path,
+      status: "modify",
+      summary: `~ modify ${file.path} (unparseable JSON)`,
+    }
+  }
+}
+
+const diffOwned = (file: OwnedPlanFile, current: string | null): FileDiff => {
+  if (current === null) {
+    return { path: file.path, status: "create", summary: `+ create ${file.path}` }
+  }
+  if (current === file.content) {
+    return { path: file.path, status: "ok", summary: `  ok ${file.path}` }
+  }
+  return { path: file.path, status: "modify", summary: `~ modify ${file.path}` }
+}
+
+const diffSeed = (file: SeedPlanFile, current: string | null): FileDiff => {
+  if (current === null) {
+    return { path: file.path, status: "create", summary: `+ create ${file.path} (seed)` }
+  }
+  return { path: file.path, status: "ok", summary: `  ok ${file.path} (seed, never enforced)` }
+}
+
+// Stable JSON string for structural comparison: deep key-sort, then stringify.
+const canonicalJson = (v: unknown): string => JSON.stringify(RecordX.canonicalize(v))
+
+// ---------------------------------------------------------------------------
+// Render a diff for the terminal
+// ---------------------------------------------------------------------------
+
+export const renderPlanDiff = (diff: PlanDiff): string => {
+  if (!diff.hasDrift) {
+    return "Project is in sync with blueprints. No changes needed."
+  }
+  const lines = diff.files.map((f) => f.summary)
+  return lines.join("\n")
+}
+
+/**
+ * Render the full inspect output: file-diff lines + lockfile-driven removals + version upgrades.
+ * Used by `pjt inspect` and `pjt remodel --dry-run` (future) to give a complete picture.
+ */
+export const renderInspectReport = (params: {
+  readonly diff: PlanDiff
+  readonly removals: readonly PjtLock.LockOperation[]
+  readonly upgrades: readonly UpgradeRecord[]
+}): string => {
+  const { diff, removals, upgrades } = params
+  const lines = Array.flatten([
+    Array.map(upgrades, (u) => `↑ upgrade ${u.blueprintId} ${u.from} → ${u.to}`),
+    Array.map(removals, removalSummary),
+    Array.map(diff.files, (f) => f.summary),
+  ])
+  if (lines.length === 0) {
+    return "Project is in sync with blueprints. No changes needed."
+  }
+  return lines.join("\n")
+}
+
+const removalSummary = (op: PjtLock.LockOperation): string =>
+  Match.valueTags(op, {
+    Region: (region) =>
+      `- remove ${region.ownerId} region from ${region.path}   (blueprint left .pjt.ts)`,
+    Merge: (merge) =>
+      `- remove merge keys ${merge.ownedKeys.join(", ")} from ${merge.path}   (blueprint left .pjt.ts)`,
+    Owned: (owned) => `- delete ${owned.path}   (blueprint left .pjt.ts)`,
+    Seed: (seed) =>
+      `  (seed ${seed.ownerId} for ${seed.path} retained; blueprint left but seed mode is write-once)`,
+  })

package/src/edit-pjt.ts

@@ -0,0 +1,56 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { Effect } from "effect"
+import { Errors } from "@projitect/core"
+import { spliceBlueprintFile } from "@projitect/blueprint"
+
+export interface SpliceParams {
+  readonly projectRoot: string
+  readonly blueprintFile: string
+  /** Import statement to splice (one line, no trailing newline). Deduped. */
+  readonly importLine: string
+  /** Blueprint call lines (one entry per line, no leading indent, no trailing newline). */
+  readonly callLines: readonly string[]
+}
+
+/**
+ * Read `.pjt.ts`, splice an import and call lines in via the shared `spliceBlueprintFile`, and
+ * write it back. The marker convention and splice behavior live in `@projitect/blueprint`.
+ *
+ * Fails with `pjt.add.markers-missing` if either marker pair is missing — the user has
+ * hand-edited the file and we won't guess. They restore the markers, then re-run `pjt add`.
+ */
+export const splice = (
+  params: SpliceParams,
+): Effect.Effect<void, Errors.AddMarkersMissing | Errors.FsReadFailed | Errors.FsWriteFailed> =>
+  Effect.gen(function* () {
+    const full = path.join(params.projectRoot, params.blueprintFile)
+    const raw = yield* Effect.tryPromise({
+      try: () => fs.readFile(full, "utf8"),
+      catch: (e) =>
+        new Errors.FsReadFailed({
+          id: "pjt.fs.read-failed",
+          path: params.blueprintFile,
+          cause: e instanceof Error ? e.message : String(e),
+          message: `Could not read ${params.blueprintFile}`,
+        }),
+    })
+
+    const next = yield* spliceBlueprintFile({
+      content: raw,
+      blueprintFile: params.blueprintFile,
+      importLine: params.importLine,
+      callLines: params.callLines,
+    })
+
+    yield* Effect.tryPromise({
+      try: () => fs.writeFile(full, next, "utf8"),
+      catch: (e) =>
+        new Errors.FsWriteFailed({
+          id: "pjt.fs.write-failed",
+          path: params.blueprintFile,
+          cause: e instanceof Error ? e.message : String(e),
+          message: `Could not write ${params.blueprintFile}`,
+        }),
+    })
+  })