@projitect/cli-internals 0.0.0-stage → 1.0.0

package/src/loader.ts

@@ -0,0 +1,115 @@
+import path from "node:path"
+import { promises as fs } from "node:fs"
+import { pathToFileURL } from "node:url"
+import { Array, Effect, Match, Predicate } from "effect"
+import { PredicateX, StructX } from "@nunofyobiz/effect-extras"
+import { Errors } from "@projitect/core"
+import type { BlueprintFileSystem, Blueprint } from "@projitect/core"
+import type { DirectoryBlueprint } from "@projitect/blueprint"
+
+/**
+ * The shape `.pjt.ts` produces when the user calls `pjt({ blueprints, config })`. Either an
+ * array of blueprints or an Effect that builds the array. The runner unwraps the Effect form
+ * inside the planner so blueprint-tree construction itself can be a typed pipeline.
+ *
+ * The Effect form may fail with any `BlueprintError` and may require `BlueprintFileSystem` —
+ * the CLI provides a "config-time" FS layer with broad read permissions before invoking it.
+ */
+export type BlueprintTree = readonly (Blueprint.Blueprint | DirectoryBlueprint)[]
+
+export interface ProjitectFile {
+  readonly _tag: "ProjitectConfig"
+  readonly blueprints:
+    | BlueprintTree
+    | Effect.Effect<BlueprintTree, Errors.BlueprintError, BlueprintFileSystem>
+  readonly config?: Record<string, unknown>
+}
+
+/**
+ * The user calls this in `.pjt.ts`:
+ *
+ *   export default pjt({ blueprints: [...] })
+ *
+ * It's an identity tag — we only inspect the default export for the `_tag` marker so we can
+ * distinguish accidental other exports from a real projitect config.
+ */
+export const pjt = (input: {
+  readonly blueprints: ProjitectFile["blueprints"]
+  readonly config?: Record<string, unknown>
+}): ProjitectFile => ({
+  _tag: "ProjitectConfig",
+  blueprints: input.blueprints,
+  ...StructX.defined("config", input.config),
+})
+
+/** Type guard: did the user pass an Effect, or a literal array? */
+export const isEffectTree = (
+  v: ProjitectFile["blueprints"],
+): v is Effect.Effect<BlueprintTree, Errors.BlueprintError, BlueprintFileSystem> =>
+  !Array.isArray(v)
+
+/**
+ * Dynamic-import the user's `.pjt.ts` and return the typed default export.
+ *
+ * The user's file is TypeScript. On Node 23.6+ with `--experimental-strip-types`, the import
+ * succeeds natively. On older Node, the binary shim in `packages/projitect` registers `tsx` as
+ * a loader before reaching this function. Either way, by the time we get here, `import(path)`
+ * Just Works.
+ */
+export const loadBlueprintFile = (params: {
+  readonly blueprintFile: string
+  readonly projectRoot: string
+}): Effect.Effect<
+  ProjitectFile,
+  Errors.LoaderImportFailed | Errors.LoaderInvalidDefaultExport | Errors.ConfigBlueprintFileNotFound
+> => {
+  const { blueprintFile, projectRoot } = params
+  const full = path.resolve(projectRoot, blueprintFile)
+  return Effect.gen(function* () {
+    const exists = yield* Effect.promise(() =>
+      fs.access(full).then(
+        () => true,
+        () => false,
+      ),
+    )
+    if (!exists) {
+      return yield* new Errors.ConfigBlueprintFileNotFound({
+        id: "pjt.config.blueprint-file-not-found",
+        blueprintFile,
+        message: `No blueprint file found at ${full}. Run \`pjt init\` to create one.`,
+      })
+    }
+    const module_ = yield* Effect.tryPromise({
+      try: (): Promise<{ readonly default?: unknown }> => import(pathToFileURL(full).href),
+      catch: (e) =>
+        new Errors.LoaderImportFailed({
+          id: "pjt.loader.import-failed",
+          blueprintFile,
+          cause: e instanceof Error ? e.message : String(e),
+          message: `Failed to import ${blueprintFile}: ${e instanceof Error ? e.message : String(e)}`,
+        }),
+    })
+    const value = module_.default
+    if (!isProjitectFile(value)) {
+      return yield* new Errors.LoaderInvalidDefaultExport({
+        id: "pjt.loader.invalid-default-export",
+        blueprintFile,
+        received: describe(value),
+        message: `${blueprintFile} must \`export default pjt({...})\`. Received ${describe(value)}.`,
+      })
+    }
+    return value
+  })
+}
+
+const isProjitectFile = (v: unknown): v is ProjitectFile =>
+  PredicateX.unsafeIsRecord(v) && v["_tag"] === "ProjitectConfig"
+
+const describe = (v: unknown): string =>
+  Match.value(v).pipe(
+    Match.when(Predicate.isUndefined, () => "undefined"),
+    Match.when(Predicate.isNull, () => "null"),
+    Match.when(Array.isArray, () => "Array"),
+    Match.when(PredicateX.unsafeIsRecord, () => 'object without `_tag: "ProjitectConfig"`'),
+    Match.orElse((value) => typeof value),
+  )

package/src/lockfile.ts

@@ -0,0 +1,81 @@
+import { Effect, Schema } from "effect"
+import { BlueprintFileSystem, Errors, PjtLock } from "@projitect/core"
+import { readIfExists } from "./project-file.js"
+
+const LOCKFILE_NAME = ".pjt.lock"
+const CURRENT_VERSION = 1 as const
+
+/**
+ * Read `.pjt.lock` from the project root of the provided `BlueprintFileSystem`. Returns `null` if the file doesn't exist (fresh project).
+ * Fails with `pjt.lock.parse-failed` on JSON or schema errors, `pjt.lock.version-mismatch` if
+ * the lockfile was written by a newer projitect.
+ */
+export const readLockfile: Effect.Effect<
+  PjtLock.PjtLock | null,
+  Errors.LockParseFailed | Errors.LockVersionMismatch,
+  BlueprintFileSystem
+> = Effect.gen(function* () {
+  const file = LOCKFILE_NAME
+  const raw = yield* readIfExists(file)
+  if (raw === null) {
+    return null
+  }
+
+  const parsed = yield* Effect.try({
+    try: () => JSON.parse(raw) as unknown,
+    catch: (e) =>
+      new Errors.LockParseFailed({
+        id: "pjt.lock.parse-failed",
+        path: file,
+        cause: e instanceof Error ? e.message : String(e),
+        message: `Could not parse ${LOCKFILE_NAME}. The file is corrupted — delete it and rerun \`pjt remodel\` to rebuild.`,
+      }),
+  })
+
+  if (
+    typeof parsed === "object" &&
+    parsed !== null &&
+    "version" in parsed &&
+    typeof parsed.version === "number" &&
+    parsed.version > CURRENT_VERSION
+  ) {
+    return yield* new Errors.LockVersionMismatch({
+      id: "pjt.lock.version-mismatch",
+      found: parsed.version,
+      expected: CURRENT_VERSION,
+      message: `${LOCKFILE_NAME} was written by a newer projitect (version ${parsed.version}). Upgrade the \`projitect\` devDep.`,
+    })
+  }
+
+  return yield* Schema.decodeUnknownEffect(PjtLock.PjtLock)(parsed).pipe(
+    Effect.mapError(
+      (e) =>
+        new Errors.LockParseFailed({
+          id: "pjt.lock.parse-failed",
+          path: file,
+          cause: String(e),
+          message: `${LOCKFILE_NAME} does not match the expected schema. Delete it and rerun \`pjt remodel\` to rebuild.`,
+        }),
+    ),
+  )
+})
+
+/**
+ * Write `.pjt.lock` through the provided `BlueprintFileSystem`. Always writes the current schema
+ * version.
+ */
+export const writeLockfile = (params: {
+  readonly lock: PjtLock.PjtLock
+}): Effect.Effect<void, Errors.FsWriteFailed | Errors.FsPermissionDenied, BlueprintFileSystem> =>
+  Effect.gen(function* () {
+    const fs = yield* BlueprintFileSystem
+    yield* fs.writeFile(LOCKFILE_NAME, `${JSON.stringify(params.lock, null, 2)}\n`)
+  })
+
+/**
+ * Build the set of blueprint ids currently expected to be present from a lockfile. Used by the
+ * planner to compute which blueprints have left the tree (their ops will be turned into
+ * removals on next apply).
+ */
+export const blueprintIds = (lock: PjtLock.PjtLock | null): ReadonlySet<string> =>
+  new Set(lock === null ? [] : Object.keys(lock.blueprints))

package/src/permissions.ts

@@ -0,0 +1,106 @@
+import { Array } from "effect"
+import type { Permission } from "@projitect/core"
+
+/**
+ * Finds the `}` closing the group opened at `open`, and the top-level comma positions between them.
+ * Returns `undefined` when the group is unbalanced or has no top-level comma (so `{a}` stays literal).
+ */
+const parseBraceGroup = (
+  glob: string,
+  open: number,
+): { readonly close: number; readonly commas: readonly number[] } | undefined => {
+  const commas: number[] = []
+  let depth = 0
+  for (let index = open; index < glob.length; index++) {
+    const ch = glob.charAt(index)
+    if (ch === "{") {
+      depth++
+    } else if (ch === "}") {
+      depth--
+      if (depth === 0) {
+        return Array.isArrayNonEmpty(commas) ? { close: index, commas } : undefined
+      }
+    } else if (ch === "," && depth === 1) {
+      commas.push(index)
+    }
+  }
+  return undefined
+}
+
+/**
+ * Minimal glob matcher for permission globs. Supports asterisk (any non-slash chars), double
+ * asterisk (any chars including slashes) and `{a,b}` alternation (alternatives may be empty or
+ * nested). A brace group needs a closing brace and at least one top-level comma; otherwise the
+ * braces and commas match literally. No character classes, `?`, negation or extglobs.
+ *
+ * Examples that match `src/(double-star)/*.{ts,tsx}`: `src/a.ts`, `src/foo/b.tsx`.
+ */
+const globToPattern = (glob: string): string => {
+  let pattern = ""
+  for (let index = 0; index < glob.length; index++) {
+    const ch = glob.charAt(index)
+    const group = ch === "{" ? parseBraceGroup(glob, index) : undefined
+    if (group !== undefined) {
+      const bounds = [index, ...group.commas, group.close]
+      const alternatives = Array.zipWith(bounds, bounds.slice(1), (start, end) =>
+        globToPattern(glob.slice(start + 1, end)),
+      )
+      pattern = `${pattern}(?:${alternatives.join("|")})`
+      index = group.close
+    } else if (ch === "*" && glob.charAt(index + 1) === "*") {
+      pattern = `${pattern}.*`
+      index++
+    } else if (ch === "*") {
+      pattern = `${pattern}[^/]*`
+    } else if (".+^${}()|[]\\".includes(ch)) {
+      pattern = `${pattern}\\${ch}`
+    } else {
+      pattern = pattern + ch
+    }
+  }
+  return pattern
+}
+
+const globToRegex = (glob: string): RegExp => new RegExp(`^${globToPattern(glob)}$`, "u")
+
+const matchesGlob = (path: string, glob: string): boolean => globToRegex(glob).test(path)
+
+export type FsOp = "read" | "write" | "exists" | "remove" | "removeEmptyDir" | "mkdir" | "listDir"
+
+const opCategory = (op: FsOp): "read" | "write" =>
+  op === "read" || op === "exists" || op === "listDir" ? "read" : "write"
+
+/**
+ * Returns `true` if the declared permissions cover the requested operation on the given path.
+ * `read`-permissioned globs cover `read | exists | listDir`. `write`-permissioned globs cover all
+ * write-side operations (`write | remove | removeEmptyDir | mkdir`) **and implicitly** the read operations on the
+ * same path — a blueprint that writes a file naturally needs to read it back for region updates.
+ */
+export const isPermitted = (
+  permissions: readonly Permission.Permission[],
+  op: FsOp,
+  path: string,
+): boolean => {
+  const category = opCategory(op)
+  // A permission grants the op when its glob matches and it's a write (writes imply reads) or
+  // it's a read covering a read-category op.
+  return Array.some(
+    permissions,
+    (p) =>
+      p.kind !== "exec" && matchesGlob(path, p.glob) && (p.kind === "write" || category === "read"),
+  )
+}
+
+/**
+ * Returns `true` if some declared `exec` permission names `command`.
+ *
+ * Decision: the permission's `command` matches by **exact string** against the full command line —
+ * no glob, no normalisation. A glob such as `pnpm *` would let a blueprint run any subcommand,
+ * which defeats declaring the permission; exact matching fails closed, so `pnpm lint:fix` is denied
+ * when only `pnpm lint` is declared. Relaxing to globs later is additive (the schema stores a plain
+ * string). `read`/`write` permissions never grant exec, and `exec` never grants file access.
+ */
+export const isCommandPermitted = (
+  permissions: readonly Permission.Permission[],
+  command: string,
+): boolean => Array.some(permissions, (p) => p.kind === "exec" && p.command === command)