@projitect/cli-internals 0.0.0-stage → 1.0.1

package/dist/remover.js

@@ -0,0 +1,88 @@
+import { Array, Effect, Match, Option, Predicate } from "effect";
+import { PredicateX, RecordX, StringX } from "@nunofyobiz/effect-extras";
+import { BlueprintFileSystem } from "@projitect/core";
+import { readIfExists } from "./project-file.js";
+import { findRegion } from "./region.js";
+/**
+ * Apply removal operations through the project `BlueprintFileSystem`. Used by `pjt remodel` / `pjt build` after a blueprint
+ * leaves `.pjt.ts` — the operations come from the diff between the previous lockfile and the
+ * current blueprint set.
+ *
+ * Returns the list of paths actually mutated.
+ */
+export const applyRemovals = (params) => Effect.forEach(params.removals, (op) => Effect.map(applyOne(op), (mutated) => (mutated ? Option.some(op.path) : Option.none()))).pipe(Effect.map(Array.getSomes));
+const applyOne = (op) => Match.valueTags(op, {
+    Region: (region) => removeRegion(region),
+    Merge: (merge) => removeMergeKeys(merge.path, merge.ownedKeys),
+    Owned: (owned) => removeFile(owned.path, owned.ownedDir),
+    // Seed is write-once; we never delete the file when a seed blueprint leaves.
+    Seed: () => Effect.succeed(false),
+});
+const removeRegion = (op) => Effect.gen(function* () {
+    const fs = yield* BlueprintFileSystem;
+    const current = yield* readIfExists(op.path);
+    if (current === null) {
+        return false;
+    }
+    const found = yield* findRegion({
+        fileContent: current,
+        ownerId: op.ownerId,
+        commentPrefix: op.commentPrefix,
+        commentSuffix: op.commentSuffix ?? "",
+        path: op.path,
+    });
+    if (found._tag === "Absent") {
+        return false;
+    }
+    const next = StringX.replaceLineRange(current, found.startLine, found.endLine, []);
+    yield* fs.writeFile(op.path, next);
+    return true;
+});
+const removeMergeKeys = (file, keys) => Effect.gen(function* () {
+    const fs = yield* BlueprintFileSystem;
+    const raw = yield* readIfExists(file);
+    if (raw === null) {
+        return false;
+    }
+    const parsed = yield* Effect.try(() => JSON.parse(raw)).pipe(Effect.option);
+    if (Option.isNone(parsed) || !PredicateX.unsafeIsRecord(parsed.value)) {
+        return false;
+    }
+    // Fold each dotted key out of the tree, tracking whether anything actually changed.
+    const seed = {
+        tree: parsed.value,
+        mutated: false,
+    };
+    const result = Array.reduce(keys, seed, (state, key) => Option.match(RecordX.deleteByPath(state.tree, key.split(".")), {
+        onSome: (tree) => ({ tree, mutated: true }),
+        onNone: () => state,
+    }));
+    if (!result.mutated) {
+        return false;
+    }
+    yield* fs.writeFile(file, `${JSON.stringify(result.tree, null, 2)}\n`);
+    return true;
+});
+const removeFile = (file, ownedDir) => Effect.gen(function* () {
+    const fs = yield* BlueprintFileSystem;
+    yield* fs.remove(file);
+    if (Predicate.isNotUndefined(ownedDir)) {
+        yield* pruneEmptyDirs(parentDir(file), ownedDir);
+    }
+    return true;
+}).pipe(Effect.orElseSucceed(() => false));
+// Project-relative paths use `/`; the parent of a top-level name is the project root (`""`).
+const parentDir = (file) => file.slice(0, Math.max(0, file.lastIndexOf("/")));
+/** Remove empty directories upward from `dir` to `ownedDir` inclusive, never above it. */
+const pruneEmptyDirs = (dir, ownedDir) => Effect.gen(function* () {
+    if (dir !== ownedDir && !dir.startsWith(`${ownedDir}/`)) {
+        return;
+    }
+    const fs = yield* BlueprintFileSystem;
+    // Atomic: fails (and stops the climb) if `dir` holds any entry, however recently it appeared.
+    yield* fs.removeEmptyDir(dir);
+    if (dir !== ownedDir) {
+        yield* pruneEmptyDirs(parentDir(dir), ownedDir);
+    }
+}).pipe(Effect.orElseSucceed(() => undefined));
+//# sourceMappingURL=remover.js.map

package/dist/remover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remover.js","sourceRoot":"","sources":["../src/remover.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@projitect/cli-internals",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "Engine for the projitect CLI — loader, planner, differ, applier, and command dispatchers.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/projitect/projitect.git",
+    "directory": "packages/cli-internals"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./bin": {
+      "types": "./dist/bin.d.ts",
+      "import": "./dist/bin.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@nunofyobiz/effect-extras": "3.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.19",
+    "effect": "4.0.0-rc.111",
+    "typescript": "5.9.3",
+    "@projitect/blueprint": "1.0.1",
+    "@projitect/blueprint-gitignore": "1.0.1",
+    "@projitect/blueprint-markdown": "1.0.1",
+    "@projitect/blueprint-next": "1.0.1",
+    "@projitect/blueprint-react": "1.0.1",
+    "@projitect/core": "1.0.1",
+    "@projitect/test-kit": "1.0.1"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.111",
+    "@projitect/blueprint": "1.0.1",
+    "@projitect/core": "1.0.1"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "build:clean": "tsc --build --clean",
+    "tc": "tsc --build"
+  }
 }

package/src/applier.ts

@@ -0,0 +1,91 @@
+import { Effect, Match } from "effect"
+import { RecordX } from "@nunofyobiz/effect-extras"
+import { BlueprintFileSystem } from "@projitect/core"
+import type { Errors } from "@projitect/core"
+import type { FilePlan, ProjectPlan, RegionPlanFile, MergePlanFile } from "./plan.js"
+import { readIfExists } from "./project-file.js"
+import { findRegion, renderRegion, upsertRegion } from "./region.js"
+
+/**
+ * Apply a plan through the project `BlueprintFileSystem` (which creates parent directories). Used by `pjt remodel` (non-destructive) and `pjt build` (after wiping
+ * the project tree). Returns the list of paths actually written.
+ */
+export const applyPlan = (params: {
+  readonly plan: ProjectPlan
+}): Effect.Effect<
+  readonly string[],
+  | Errors.RegionMissingEnd
+  | Errors.RegionDuplicate
+  | Errors.FsWriteFailed
+  | Errors.FsPermissionDenied,
+  BlueprintFileSystem
+> => {
+  const { plan } = params
+  return Effect.gen(function* () {
+    const fs = yield* BlueprintFileSystem
+    const written: string[] = []
+    for (const file of plan.files) {
+      const current = yield* readIfExists(file.path)
+      const next = yield* nextContent({ file, current })
+      if (next === null) {
+        continue
+      } // Seed-mode no-op
+      if (next === current) {
+        continue
+      } // Already in sync
+      yield* fs.writeFile(file.path, next)
+      written.push(file.path)
+    }
+    return written
+  })
+}
+
+const nextContent = (params: {
+  readonly file: FilePlan
+  readonly current: string | null
+}): Effect.Effect<string | null, Errors.RegionMissingEnd | Errors.RegionDuplicate> =>
+  Match.valueTags(params.file, {
+    Region: (file) => nextRegion(file, params.current),
+    Merge: (file) => Effect.succeed(nextMerge(file, params.current)),
+    Owned: (file) => Effect.succeed(file.content),
+    Seed: (file) => Effect.succeed(params.current === null ? file.content : null),
+  })
+
+const nextRegion = (
+  file: RegionPlanFile,
+  current: string | null,
+): Effect.Effect<string, Errors.RegionMissingEnd | Errors.RegionDuplicate> =>
+  Effect.gen(function* () {
+    let content = current ?? ""
+    for (const region of file.regions) {
+      const found = yield* findRegion({
+        fileContent: content,
+        ownerId: region.ownerId,
+        commentPrefix: file.commentPrefix,
+        commentSuffix: file.commentSuffix,
+        path: file.path,
+      })
+      const rendered = renderRegion({
+        ownerId: region.ownerId,
+        commentPrefix: file.commentPrefix,
+        commentSuffix: file.commentSuffix,
+        content: region.content,
+      })
+      content = upsertRegion({ fileContent: content, existing: found, rendered })
+    }
+    return content
+  })
+
+const nextMerge = (file: MergePlanFile, current: string | null): string => {
+  const existing = current === null ? {} : (safeParseJson(current) ?? {})
+  const merged = RecordX.deepMerge(existing, file.value)
+  return `${JSON.stringify(merged, null, 2)}\n`
+}
+
+const safeParseJson = (text: string): unknown => {
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    return null
+  }
+}

package/src/commands/add.ts

@@ -0,0 +1,88 @@
+import { Effect } from "effect"
+import { Errors } from "@projitect/core"
+import type { ProjitectConfig } from "@projitect/core"
+import { computeSplice, resolveSections } from "@projitect/blueprint"
+import type { ProjitectPackageMetadata, SectionStrategy } from "@projitect/blueprint"
+import { detect, installDev as installDevelopment, readProjitectMetadata } from "../pm.js"
+import { splice } from "../edit-pjt.js"
+
+export interface AddResult {
+  readonly pm: string
+  readonly pkg: string
+  readonly metadata: ProjitectPackageMetadata
+  readonly sectionsAdded: readonly string[]
+  readonly splicedIntoBlueprintFile: boolean
+  /** The user picked no sections (or quit the prompt); `.pjt.ts` was left untouched. */
+  readonly selectionCancelled: boolean
+}
+
+/**
+ * `pjt add <package>` — install a blueprint package and splice it into `.pjt.ts`.
+ *
+ * Flow:
+ *   1. Detect package manager (pnpm / yarn / bun / npm).
+ *   2. Shell out `<pm> add -D <package>`.
+ *   3. Read the installed package's `package.json` for the `"projitect"` metadata field.
+ *      - If present and `type: "blueprint-set"`: section selection resolves per `strategy`
+ *        (all / explicit / ask).
+ *      - If present and `type: "blueprint"`: a single call line, strategy ignored.
+ *      - If absent: fails with `pjt.add.metadata-missing`. The package stays installed; the
+ *        message tells the user to import it in `.pjt.ts` by hand and run `pjt remodel`.
+ *   4. Splice the import + call lines into `.pjt.ts` between the convention markers
+ *      (`pjt:imports` and `pjt:blueprints`).
+ */
+export const add = <R = never>(params: {
+  readonly config: ProjitectConfig.ProjitectConfig
+  readonly pkg: string
+  readonly strategy: SectionStrategy<R>
+}): Effect.Effect<AddResult, Errors.ProjitectError, R> =>
+  Effect.gen(function* () {
+    const pm = yield* detect({ projectRoot: params.config.projectRoot })
+    yield* installDevelopment({ projectRoot: params.config.projectRoot, pm, pkg: params.pkg })
+    const metadata = yield* readProjitectMetadata({
+      projectRoot: params.config.projectRoot,
+      pkg: params.pkg,
+    })
+
+    if (metadata === null) {
+      return yield* new Errors.AddMetadataMissing({
+        id: "pjt.add.metadata-missing",
+        pkg: params.pkg,
+        blueprintFile: params.config.blueprintFile,
+        message:
+          `${params.pkg} was installed but has no \`"projitect"\` metadata in its package.json, so \`pjt add\` can't splice it into ${params.config.blueprintFile}. ` +
+          `Import it in ${params.config.blueprintFile} by hand, then run \`pjt remodel\`.`,
+      })
+    }
+
+    const selection = yield* resolveSections({ metadata, strategy: params.strategy })
+
+    if (selection._tag === "Nothing") {
+      return {
+        pm,
+        pkg: params.pkg,
+        metadata,
+        sectionsAdded: [],
+        splicedIntoBlueprintFile: false,
+        selectionCancelled: true,
+      }
+    }
+
+    const { importLine, callLines, sectionsAdded } = computeSplice({ metadata, selection })
+
+    yield* splice({
+      projectRoot: params.config.projectRoot,
+      blueprintFile: params.config.blueprintFile,
+      importLine,
+      callLines,
+    })
+
+    return {
+      pm,
+      pkg: params.pkg,
+      metadata,
+      sectionsAdded,
+      splicedIntoBlueprintFile: true,
+      selectionCancelled: false,
+    }
+  })

package/src/commands/build.ts

@@ -0,0 +1,156 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { Effect } from "effect"
+import type { Terminal } from "effect"
+import { Prompt } from "effect/unstable/cli"
+import { StructX } from "@nunofyobiz/effect-extras"
+import { Errors } from "@projitect/core"
+import type { ProjitectConfig } from "@projitect/core"
+import { ensureGitRepo, gitStatus } from "../git.js"
+import type { ProcessSpawner } from "../platform/process-runner.js"
+import { remodel } from "./remodel.js"
+import type { RemodelResult } from "./remodel.js"
+
+export interface BuildResult {
+  /** True when the confirmation prompt was declined, so nothing was wiped, written or run. */
+  readonly cancelled: boolean
+  readonly wiped: readonly string[]
+  readonly remodel: RemodelResult
+}
+
+/**
+ * Paths that survive `pjt build --force`. Everything else under projectRoot is deleted before
+ * the plan re-applies. This intentionally preserves the manifest (`package.json`), the blueprint
+ * file, the lockfile, the dependency store, the git history, and PM lockfiles so the project is
+ * recoverable.
+ */
+const PRESERVED = new Set<string>([
+  ".git",
+  "node_modules",
+  ".pjt.ts",
+  ".pjt.lock",
+  "package.json",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+  "bun.lockb",
+])
+
+/**
+ * `pjt build --force` — wipe the project tree (modulo preserved entries) and re-apply the plan
+ * from scratch.
+ *
+ * Safety net:
+ *   1. `--force` is required (the dispatcher's flag config enforces this at the CLI layer).
+ *   2. The project must be a git repository (`pjt.git.not-a-repo` otherwise).
+ *   3. The working tree must be clean (`pjt.apply.dirty-git`), unless `--force-dirty` is set.
+ *   4. An interactive confirmation prompt fires unless `--yes` is passed.
+ */
+type BuildError = Errors.ProjitectError | Terminal.QuitError
+type BuildRequirements = Prompt.Environment
+
+export const build = (params: {
+  readonly config: ProjitectConfig.ProjitectConfig
+  readonly force: boolean
+  readonly forceDirty: boolean
+  readonly yes: boolean
+  readonly spawner?: ProcessSpawner
+}): Effect.Effect<BuildResult, BuildError, BuildRequirements> =>
+  Effect.gen(function* () {
+    if (!params.force) {
+      return yield* new Errors.ApplyDirtyGit({
+        id: "pjt.apply.dirty-git",
+        command: "build",
+        message:
+          "`pjt build` requires the `--force` flag. This command is destructive — it wipes the project tree before re-applying.",
+      })
+    }
+
+    yield* ensureGitRepo({ projectRoot: params.config.projectRoot })
+
+    if (!params.forceDirty) {
+      const status = yield* gitStatus({ projectRoot: params.config.projectRoot })
+      if (!status.clean) {
+        return yield* new Errors.ApplyDirtyGit({
+          id: "pjt.apply.dirty-git",
+          command: "build",
+          message:
+            `Git working tree is dirty (${status.lines.length} uncommitted change${status.lines.length === 1 ? "" : "s"}). ` +
+            "Commit your changes (`git add -A && git commit -m wip`) and re-run `pjt build --force`, or pass `--force-dirty` to wipe anyway.",
+        })
+      }
+    }
+
+    if (!params.yes) {
+      const confirmed = yield* Prompt.confirm({
+        message: `This will delete everything under ${params.config.projectRoot} except .git, node_modules, .pjt.ts, .pjt.lock, package.json, and the PM lockfile. Continue?`,
+        initial: false,
+      })
+      if (!confirmed) {
+        return {
+          cancelled: true,
+          wiped: [],
+          remodel: { written: [], removed: [], ran: [] },
+        }
+      }
+    }
+
+    const wiped = yield* wipeTree(params.config.projectRoot)
+    const remodelResult = yield* remodel({
+      config: params.config,
+      ...StructX.defined("spawner", params.spawner),
+    })
+    return { cancelled: false, wiped, remodel: remodelResult }
+  })
+
+const count = (n: number, singular: string, plural: string): string =>
+  `${n} ${n === 1 ? singular : plural}`
+
+/**
+ * The human summary `pjt build` prints. Cancellation is the declined prompt, not "nothing
+ * happened": a build that only ran post-apply commands is a success and lists them.
+ */
+export const renderBuildResult = (result: BuildResult): string => {
+  const { cancelled, wiped, remodel: applied } = result
+  const lines = cancelled
+    ? ["Cancelled. No changes made."]
+    : [
+        ...(wiped.length > 0
+          ? [`Wiped ${count(wiped.length, "entry", "entries")}:`, ...wiped.map((p) => `  ${p}`)]
+          : []),
+        ...(applied.written.length > 0
+          ? [
+              `Rebuilt ${count(applied.written.length, "file", "files")} from the plan:`,
+              ...applied.written.map((p) => `  ${p}`),
+            ]
+          : []),
+        ...(applied.ran.length > 0
+          ? [
+              `Ran ${count(applied.ran.length, "command", "commands")}:`,
+              ...applied.ran.map((c) => `  ${c}`),
+            ]
+          : []),
+      ]
+  return `${lines.join("\n")}\n`
+}
+
+const wipeTree = (projectRoot: string): Effect.Effect<readonly string[], Errors.FsWriteFailed> =>
+  Effect.tryPromise({
+    try: async () => {
+      const entries = await fs.readdir(projectRoot)
+      const toRemove = entries.filter((name) => !PRESERVED.has(name))
+      await Promise.all(
+        toRemove.map((name) =>
+          fs.rm(path.join(projectRoot, name), { recursive: true, force: true }),
+        ),
+      )
+      return toRemove
+    },
+    catch: (e) =>
+      new Errors.FsWriteFailed({
+        id: "pjt.fs.write-failed",
+        path: projectRoot,
+        cause: e instanceof Error ? e.message : String(e),
+        message: `Failed to wipe project tree at ${projectRoot}`,
+      }),
+  })