@projitect/blueprint 0.0.0-stage → 1.0.1

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @projitect/blueprint
+ *
+ * Authoring SDK for blueprint packages. Blueprint authors compose these primitives — the
+ * `BlueprintFileSystem` service for FS access, the four ownership-mode constructors
+ * (`regionFile` / `jsonMerge` / `ownFile` / `seedFile`), the post-apply `exec` constructor, the section helpers
+ * (`markdownSection`, `ignoreSection`), the `directory` scope transform, and detectors for
+ * common project introspection.
+ *
+ * Authors use Effect's own control-flow combinators (`Effect.gen`, `Effect.all`, `Effect.if`,
+ * `Effect.when`, `Effect.unless`, `Effect.forEach`) for sequencing and conditionals — we do
+ * not ship duplicates.
+ */
+export * from "./constructors.js"
+export * from "./sections.js"
+export * from "./directory.js"
+export * from "./detect.js"
+export * from "./splice.js"
+export * from "./add-sections.js"
+export { BlueprintFileSystem } from "@projitect/core"
+export { Blueprint, ChangeSet, Permission, Errors } from "@projitect/core"

package/src/sections.ts

@@ -0,0 +1,99 @@
+/**
+ * Section helpers — thin wrappers around `regionFile` that bake in the right comment
+ * delimiters for two common file shapes:
+ *
+ *  - **`markdownSection`** for HTML/MDX/XML files where comments need a closing `-->`.
+ *    The fenced region renders invisible in markdown output — readers never see the markers.
+ *    Useful for README.md, AGENTS.md, CONTRIBUTING.md, generated MDX docs, etc.
+ *
+ *  - **`ignoreSection`** for `#`-comment "ignore"-style files. Same shape as the gitignore
+ *    convention; the helper exists because the name documents intent better than a bare
+ *    `regionFile({ commentPrefix: "#" })` does, and the surface guides authors toward the
+ *    right primitive when they're scaffolding a `.eslintignore` / `.prettierignore` /
+ *    `.dockerignore` / `.npmignore` blueprint.
+ *
+ * Both helpers re-emit the underlying `RegionFileSpec`-shaped result of `regionFile`, so
+ * everything that works for `regionFile` works for these (extra permissions, descriptions,
+ * etc.). They aren't shipped as separate npm packages because there's no opinionated content
+ * to bundle — the blueprint author always provides their own.
+ */
+
+import { StructX } from "@nunofyobiz/effect-extras"
+import type { Blueprint, Permission } from "@projitect/core"
+import { regionFile } from "./constructors.js"
+
+export interface SectionSpec {
+  readonly id: string
+  readonly version: string
+  readonly description?: string
+  readonly path: string
+  readonly content: string
+  readonly extraPermissions?: readonly Permission.Permission[]
+}
+
+/**
+ * Region-mode blueprint for HTML / MDX / XML files. The fence is rendered as two HTML
+ * comments on their own lines:
+ *
+ *     <!-- pjt:<owner-id> start -->
+ *     <body>
+ *     <!-- pjt:<owner-id> end -->
+ *
+ * The markers don't render in HTML output (they're comments), so readers of the published
+ * file never see them. `pjt inspect` flags hand-edits between the markers; lines outside
+ * the fence belong to the user.
+ *
+ * @example
+ * ```ts
+ * markdownSection({
+ *   id: "my-org:readme:badges",
+ *   version: "1.0.0",
+ *   path: "README.md",
+ *   content: "![ci](https://example.com/badge.svg)\n",
+ * })
+ * ```
+ */
+export const markdownSection = (spec: SectionSpec): Blueprint.Blueprint =>
+  regionFile({
+    id: spec.id,
+    version: spec.version,
+    ...StructX.defined("description", spec.description),
+    path: spec.path,
+    commentPrefix: "<!--",
+    commentSuffix: " -->",
+    content: spec.content,
+    ...StructX.defined("extraPermissions", spec.extraPermissions),
+  })
+
+/**
+ * Region-mode blueprint for `#`-comment ignore-style files: `.gitignore`, `.eslintignore`,
+ * `.prettierignore`, `.dockerignore`, `.npmignore`, etc. The fence is two `#`-prefixed lines
+ * on either side of the section content:
+ *
+ *     # pjt:<owner-id> start
+ *     <body>
+ *     # pjt:<owner-id> end
+ *
+ * Equivalent to `regionFile({ commentPrefix: "#", ... })`, but the name documents the
+ * intent and makes the right primitive easy to find.
+ *
+ * @example
+ * ```ts
+ * ignoreSection({
+ *   id: "my-org:eslintignore:generated",
+ *   version: "1.0.0",
+ *   path: ".eslintignore",
+ *   content: "dist/\nbuild/\ncoverage/\n",
+ * })
+ * ```
+ */
+export const ignoreSection = (spec: SectionSpec): Blueprint.Blueprint =>
+  regionFile({
+    id: spec.id,
+    version: spec.version,
+    ...StructX.defined("description", spec.description),
+    path: spec.path,
+    commentPrefix: "#",
+    content: spec.content,
+    ...StructX.defined("extraPermissions", spec.extraPermissions),
+  })

package/src/splice.ts

@@ -0,0 +1,99 @@
+import { Effect } from "effect"
+import { Errors } from "@projitect/core"
+import { StringX } from "@nunofyobiz/effect-extras"
+
+const IMPORTS_START = "// pjt:imports start"
+const IMPORTS_END = "// pjt:imports end"
+const BLUEPRINTS_START = "// pjt:blueprints start"
+const BLUEPRINTS_END = "// pjt:blueprints end"
+
+/**
+ * Splice an import line and one or more blueprint call lines into `.pjt.ts` text using the
+ * convention markers. The import goes between `// pjt:imports start/end` (deduped against
+ * existing content), the calls go between `// pjt:blueprints start/end` (appended, with 4-space
+ * indent to match the standard template). An empty `callLines` leaves the blueprints block alone.
+ *
+ * Pure string-to-string: the caller owns reading and writing the file. `blueprintFile` is only
+ * used to name the file in the error message.
+ *
+ * Fails with `pjt.add.markers-missing` if either marker pair is missing — the user has
+ * hand-edited the file and we won't guess.
+ */
+export const spliceBlueprintFile = (params: {
+  readonly content: 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[]
+}): Effect.Effect<string, Errors.AddMarkersMissing> =>
+  Effect.gen(function* () {
+    const afterImport = yield* spliceImport({
+      content: params.content,
+      blueprintFile: params.blueprintFile,
+      importLine: params.importLine,
+    })
+    return yield* spliceCalls({
+      content: afterImport,
+      blueprintFile: params.blueprintFile,
+      callLines: params.callLines,
+    })
+  })
+
+const spliceImport = (params: {
+  readonly content: string
+  readonly blueprintFile: string
+  readonly importLine: string
+}): Effect.Effect<string, Errors.AddMarkersMissing> => {
+  const { content, blueprintFile, importLine } = params
+  return Effect.gen(function* () {
+    const lines = content.split("\n")
+    const startIndex = lines.findIndex((l) => l.trim() === IMPORTS_START)
+    const endIndex = lines.findIndex((l) => l.trim() === IMPORTS_END)
+    if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
+      return yield* new Errors.AddMarkersMissing({
+        id: "pjt.add.markers-missing",
+        blueprintFile,
+        missingMarker: `${IMPORTS_START} / ${IMPORTS_END}`,
+        message:
+          `${blueprintFile} is missing the \`pjt:imports start\` / \`pjt:imports end\` markers. ` +
+          "Restore them (see `pjt init`'s starter template) and re-run `pjt add`.",
+      })
+    }
+    // Dedupe: skip if any line between the markers already equals the import
+    const between = lines.slice(startIndex + 1, endIndex).map((l) => l.trim())
+    if (between.includes(importLine.trim())) {
+      return content
+    }
+    return StringX.insertBeforeLine(content, endIndex, [importLine])
+  })
+}
+
+const spliceCalls = (params: {
+  readonly content: string
+  readonly blueprintFile: string
+  readonly callLines: readonly string[]
+}): Effect.Effect<string, Errors.AddMarkersMissing> => {
+  const { content, blueprintFile, callLines } = params
+  return Effect.gen(function* () {
+    if (callLines.length === 0) {
+      return content
+    }
+    const lines = content.split("\n")
+    const startIndex = lines.findIndex((l) => l.trim() === BLUEPRINTS_START)
+    const endIndex = lines.findIndex((l) => l.trim() === BLUEPRINTS_END)
+    if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
+      return yield* new Errors.AddMarkersMissing({
+        id: "pjt.add.markers-missing",
+        blueprintFile,
+        missingMarker: `${BLUEPRINTS_START} / ${BLUEPRINTS_END}`,
+        message:
+          `${blueprintFile} is missing the \`pjt:blueprints start\` / \`pjt:blueprints end\` markers. ` +
+          "Restore them and re-run `pjt add`.",
+      })
+    }
+    const indent = "    " // 4-space, matching the starter template
+    const newCalls = callLines.map((c) => `${indent}${c.replace(/^\s+/u, "")}`)
+    return StringX.insertBeforeLine(content, endIndex, newCalls)
+  })
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.