@projitect/blueprint 0.0.0-stage → 1.0.1

package/dist/sections.js

@@ -0,0 +1,85 @@
+/**
+ * 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 { regionFile } from "./constructors.js";
+/**
+ * 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) => 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) => regionFile({
+    id: spec.id,
+    version: spec.version,
+    ...StructX.defined("description", spec.description),
+    path: spec.path,
+    commentPrefix: "#",
+    content: spec.content,
+    ...StructX.defined("extraPermissions", spec.extraPermissions),
+});
+//# sourceMappingURL=sections.js.map

package/dist/sections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sections.js","sourceRoot":"","sources":["../src/sections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AAEnD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAW9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAiB,EAAuB,EAAE,CACxE,UAAU,CAAC;IACT,EAAE,EAAE,IAAI,CAAC,EAAE;IACX,OAAO,EAAE,IAAI,CAAC,OAAO;IACrB,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,WAAW,CAAC;IACnD,IAAI,EAAE,IAAI,CAAC,IAAI;IACf,aAAa,EAAE,MAAM;IACrB,aAAa,EAAE,MAAM;IACrB,OAAO,EAAE,IAAI,CAAC,OAAO;IACrB,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,IAAI,CAAC,gBAAgB,CAAC;CAC9D,CAAC,CAAA;AAEJ;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAiB,EAAuB,EAAE,CACtE,UAAU,CAAC;IACT,EAAE,EAAE,IAAI,CAAC,EAAE;IACX,OAAO,EAAE,IAAI,CAAC,OAAO;IACrB,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,WAAW,CAAC;IACnD,IAAI,EAAE,IAAI,CAAC,IAAI;IACf,aAAa,EAAE,GAAG;IAClB,OAAO,EAAE,IAAI,CAAC,OAAO;IACrB,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,IAAI,CAAC,gBAAgB,CAAC;CAC9D,CAAC,CAAA"}

package/dist/splice.d.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { Errors } from "@projitect/core";
+/**
+ * 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 declare 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>;
+//# sourceMappingURL=splice.d.ts.map

package/dist/splice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"splice.d.ts","sourceRoot":"","sources":["../src/splice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAQxC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CACtC,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,iBAAiB,CAY9C,CAAA"}

package/dist/splice.js

@@ -0,0 +1,78 @@
+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) => 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) => {
+    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) => {
+    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);
+    });
+};
+//# sourceMappingURL=splice.js.map

package/dist/splice.js.map

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

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@projitect/blueprint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "Authoring SDK for projitect blueprints — BlueprintFileSystem service, region/merge/owned/seed constructors, directory scope, detectors.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/projitect/projitect.git",
+    "directory": "packages/blueprint"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@nunofyobiz/effect-extras": "3.2.0"
+  },
+  "devDependencies": {
+    "effect": "4.0.0-rc.111",
+    "typescript": "5.9.3",
+    "@projitect/core": "1.0.1",
+    "@projitect/test-kit": "1.0.1"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.111",
+    "@projitect/core": "1.0.1"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "build:clean": "tsc --build --clean",
+    "tc": "tsc --build"
+  }
 }

package/src/add-sections.ts

@@ -0,0 +1,140 @@
+import { Array, Effect, Match } from "effect"
+import { Prompt } from "effect/unstable/cli"
+import type { Errors } from "@projitect/core"
+
+/**
+ * The shape of the `"projitect"` field in a blueprint package's `package.json`. Defines how
+ * `pjt add <pkg>` should splice into the user's `.pjt.ts`.
+ */
+export interface ProjitectPackageMetadata {
+  /**
+   * `"blueprint"` for single-call packages (e.g. one default export). `"blueprint-set"` for
+   * packages that expose multiple sections (e.g. `gitignores.macOs()`, `gitignores.node()`).
+   */
+  readonly type: "blueprint" | "blueprint-set"
+  /** The import statement to splice into `// pjt:imports`, e.g. `import { foo } from "foo"`. */
+  readonly import: string
+  /** For `type: "blueprint"` only — the call template, e.g. `myBlueprint()`. */
+  readonly call?: string
+  /** For `type: "blueprint-set"` only — substitute `{section}` with each chosen name. */
+  readonly callTemplate?: string
+  /** For `type: "blueprint-set"` only — the list of available section names. */
+  readonly sections?: readonly string[]
+}
+
+/**
+ * Strategy for picking which sections of a `blueprint-set` package to splice.
+ *
+ *   - `"all"` — silent default; pick every section the package declares. Used when the caller
+ *     wants the legacy "no --section means everything" behavior.
+ *   - `{ kind: "explicit", sections }` — caller already knows. `--section macOs,node` lands here.
+ *   - `{ kind: "ask", choose }` — interactive: defer to the supplied callback (typically
+ *     `chooseSectionsInteractive`). The callback runs only when the installed package's metadata
+ *     says `type: "blueprint-set"` and exposes sections.
+ *
+ * `R` parametrizes the callback's requirement channel so the caller can hand us an Effect
+ * that needs `Prompt.Environment` (FileSystem | Path | Terminal).
+ */
+export type SectionStrategy<R = never> =
+  | { readonly _tag: "All" }
+  | { readonly _tag: "Explicit"; readonly sections: readonly string[] }
+  | {
+      readonly _tag: "Ask"
+      readonly choose: (
+        metadata: ProjitectPackageMetadata,
+      ) => Effect.Effect<readonly string[], Errors.ProjitectError, R>
+    }
+
+/**
+ * What the user wants spliced from a package. Cancellation is its own case so it can never be
+ * mistaken for "all":
+ *
+ *   - `All` — every declared section.
+ *   - `Chosen` — exactly these sections (non-empty).
+ *   - `Nothing` — the user picked no sections or quit the prompt; the host must not write.
+ */
+export type SectionSelection =
+  | { readonly _tag: "All" }
+  | { readonly _tag: "Chosen"; readonly sections: readonly string[] }
+  | { readonly _tag: "Nothing" }
+
+const chosenOr = (sections: readonly string[], whenEmpty: SectionSelection): SectionSelection =>
+  Array.isReadonlyArrayNonEmpty(sections) ? { _tag: "Chosen", sections } : whenEmpty
+
+/** Resolve which sections the user wants, per `strategy`. */
+export const resolveSections = <R>(params: {
+  readonly metadata: ProjitectPackageMetadata
+  readonly strategy: SectionStrategy<R>
+}): Effect.Effect<SectionSelection, Errors.ProjitectError, R> => {
+  const { metadata, strategy } = params
+  // Section strategy only matters for blueprint-sets. For `type: "blueprint"` the selection is
+  // ignored — `computeSplice` emits a single non-templated call line.
+  if (metadata.type === "blueprint") {
+    return Effect.succeed({ _tag: "All" })
+  }
+  return Match.valueTags(strategy, {
+    All: () => Effect.succeed<SectionSelection>({ _tag: "All" }),
+    Explicit: (explicit) => Effect.succeed(chosenOr(explicit.sections, { _tag: "All" })),
+    Ask: (ask) =>
+      Effect.map(ask.choose(metadata), (picked) => chosenOr(picked, { _tag: "Nothing" })),
+  })
+}
+
+/**
+ * Compute the import line and call lines to splice for the selection. A `Nothing` selection
+ * yields no call lines and no sections; hosts check `selection._tag` and skip the write.
+ */
+export const computeSplice = (params: {
+  readonly metadata: ProjitectPackageMetadata
+  readonly selection: SectionSelection
+}): {
+  readonly importLine: string
+  readonly callLines: readonly string[]
+  readonly sectionsAdded: readonly string[]
+} => {
+  const { metadata, selection } = params
+  if (metadata.type === "blueprint") {
+    const call =
+      metadata.call ?? "/* TODO: replace with the blueprint call from the package's README */"
+    return {
+      importLine: metadata.import,
+      callLines: [`${call},`],
+      sectionsAdded: [],
+    }
+  }
+  // Blueprint-set
+  const allSections = metadata.sections ?? []
+  const chosen = Match.value(selection).pipe(
+    Match.tag("All", () => allSections),
+    Match.tag("Chosen", (picked) => picked.sections.filter((s) => allSections.includes(s))),
+    Match.tag("Nothing", () => []),
+    Match.exhaustive,
+  )
+  const template = metadata.callTemplate ?? "{section}()"
+  return {
+    importLine: metadata.import,
+    callLines: chosen.map((s) => `${template.replace("{section}", s)},`),
+    sectionsAdded: chosen,
+  }
+}
+
+/**
+ * Interactive section picker for a `type: "blueprint-set"` package. Ctrl-C yields an empty
+ * selection rather than crashing; `resolveSections` maps an empty `Ask` result to
+ * `Nothing`, so quitting never splices anything.
+ *
+ * Returns an empty selection if no sections are declared (defensive default — shouldn't happen
+ * for well-formed metadata, but we don't want to crash on a malformed package).
+ */
+export const chooseSectionsInteractive = (
+  metadata: ProjitectPackageMetadata,
+): Effect.Effect<readonly string[], never, Prompt.Environment> => {
+  const sections = metadata.sections ?? []
+  if (!Array.isReadonlyArrayNonEmpty(sections)) {
+    return Effect.succeed([])
+  }
+  return Prompt.multiSelect({
+    message: "Pick sections to add (space to toggle, enter to confirm):",
+    choices: sections.map((name) => ({ title: name, value: name })),
+  }).pipe(Effect.catchTag("QuitError", () => Effect.succeed<readonly string[]>([])))
+}

package/src/constructors.ts

@@ -0,0 +1,202 @@
+import { Array, Effect } from "effect"
+import { StructX } from "@nunofyobiz/effect-extras"
+import type { Blueprint, Permission, Errors, BlueprintFileSystem } from "@projitect/core"
+import { ChangeSet } from "@projitect/core"
+
+/**
+ * Spec for a region-mode blueprint: replace or insert the marked section in a shared text file.
+ * Multiple blueprints can coexist in the same file as long as they use different `ownerId`s.
+ */
+export interface RegionFileSpec {
+  readonly id: string
+  readonly version: string
+  readonly description?: string
+  readonly path: string
+  readonly commentPrefix?: string
+  /**
+   * Optional closing delimiter for prefix/suffix-pair comment styles. Set to `" -->"` for
+   * HTML/MDX. Leave undefined (default) for single-prefix styles like `#` and `//`.
+   */
+  readonly commentSuffix?: string
+  readonly content: string
+  readonly extraPermissions?: readonly Permission.Permission[]
+}
+
+/**
+ * Create a region-mode blueprint. The blueprint's `id` doubles as the region's `ownerId`.
+ * `commentPrefix` defaults to `#` (suitable for `.gitignore` / YAML / shell).
+ *
+ * For HTML / MDX / XML files, prefer the `markdownSection` helper — it sets the right
+ * prefix and suffix pair for you. For ignore-style files, prefer `ignoreSection` — same
+ * shape with a name that documents its intent.
+ */
+export const regionFile = (spec: RegionFileSpec): Blueprint.Blueprint => ({
+  id: spec.id,
+  version: spec.version,
+  ...StructX.defined("description", spec.description),
+  permissions: [
+    { kind: "write", glob: spec.path },
+    { kind: "read", glob: spec.path },
+    ...(spec.extraPermissions ?? []),
+  ],
+  plan: Effect.succeed(
+    ChangeSet.of(
+      ChangeSet.RegionOp.make({
+        ownerId: spec.id,
+        path: spec.path,
+        commentPrefix: spec.commentPrefix ?? "#",
+        ...StructX.defined("commentSuffix", spec.commentSuffix),
+        content: spec.content,
+      }),
+    ),
+  ),
+})
+
+/**
+ * Spec for a merge-mode blueprint: deep-merge a partial value into a structured (JSON) file.
+ * The `ownedKeys` list declares which dotted-path keys this blueprint claims — two blueprints
+ * claiming the same key is a `pjt.plan.conflict-merge` error.
+ */
+export interface JsonMergeSpec {
+  readonly id: string
+  readonly version: string
+  readonly description?: string
+  readonly path: string
+  readonly ownedKeys: readonly string[]
+  readonly value: unknown
+  readonly extraPermissions?: readonly Permission.Permission[]
+}
+
+/**
+ * Create a merge-mode blueprint for a JSON file (typically `package.json` / `tsconfig.json`).
+ */
+export const jsonMerge = (spec: JsonMergeSpec): Blueprint.Blueprint => ({
+  id: spec.id,
+  version: spec.version,
+  ...StructX.defined("description", spec.description),
+  permissions: [
+    { kind: "write", glob: spec.path },
+    { kind: "read", glob: spec.path },
+    ...(spec.extraPermissions ?? []),
+  ],
+  plan: Effect.succeed(
+    ChangeSet.of(
+      ChangeSet.MergeOp.make({
+        ownerId: spec.id,
+        path: spec.path,
+        ownedKeys: spec.ownedKeys,
+        value: spec.value,
+      }),
+    ),
+  ),
+})
+
+/**
+ * Spec for an owned-mode blueprint: this blueprint owns the file's entire content. Any other
+ * blueprint touching the same path is a `pjt.plan.conflict-owned` error.
+ */
+export interface OwnFileSpec {
+  readonly id: string
+  readonly version: string
+  readonly description?: string
+  readonly path: string
+  readonly content: string
+  /** Directory the file's owner manages; empty directories are pruned up to it on removal. */
+  readonly ownedDir?: string
+  readonly extraPermissions?: readonly Permission.Permission[]
+}
+
+export const ownFile = (spec: OwnFileSpec): Blueprint.Blueprint => ({
+  id: spec.id,
+  version: spec.version,
+  ...StructX.defined("description", spec.description),
+  permissions: [{ kind: "write", glob: spec.path }, ...(spec.extraPermissions ?? [])],
+  plan: Effect.succeed(
+    ChangeSet.of(
+      ChangeSet.OwnedOp.make({
+        ownerId: spec.id,
+        path: spec.path,
+        content: spec.content,
+        ...StructX.defined("ownedDir", spec.ownedDir),
+      }),
+    ),
+  ),
+})
+
+/**
+ * Spec for a seed-mode blueprint: write the file at first build, never enforce it again. Useful
+ * for templates the project maintainer is expected to customize (e.g. README, initial `.pjt.ts`).
+ */
+export interface SeedFileSpec {
+  readonly id: string
+  readonly version: string
+  readonly description?: string
+  readonly path: string
+  readonly content: string
+  readonly extraPermissions?: readonly Permission.Permission[]
+}
+
+export const seedFile = (spec: SeedFileSpec): Blueprint.Blueprint => ({
+  id: spec.id,
+  version: spec.version,
+  ...StructX.defined("description", spec.description),
+  permissions: [{ kind: "write", glob: spec.path }, ...(spec.extraPermissions ?? [])],
+  plan: Effect.succeed(
+    ChangeSet.of(
+      ChangeSet.SeedOp.make({
+        ownerId: spec.id,
+        path: spec.path,
+        content: spec.content,
+      }),
+    ),
+  ),
+})
+
+/**
+ * Spec for a post-apply command: after every file operation has succeeded, `pjt build` and
+ * `pjt remodel` run `fix` from the project root. `check` is the command that reports whether the
+ * fix is needed. The blueprint declares an `exec` permission for each of the two command lines.
+ */
+export interface ExecSpec {
+  readonly id: string
+  readonly version: string
+  readonly description?: string
+  readonly check: string
+  readonly fix: string
+  readonly extraPermissions?: readonly Permission.Permission[]
+}
+
+export const exec = (spec: ExecSpec): Blueprint.Blueprint => ({
+  id: spec.id,
+  version: spec.version,
+  ...StructX.defined("description", spec.description),
+  permissions: [
+    ...Array.dedupe([spec.fix, spec.check]).map(
+      (command): Permission.Permission => ({ kind: "exec", command }),
+    ),
+    ...(spec.extraPermissions ?? []),
+  ],
+  plan: Effect.succeed(
+    ChangeSet.of(ChangeSet.ExecOp.make({ ownerId: spec.id, command: spec.fix, check: spec.check })),
+  ),
+})
+
+/**
+ * Build a blueprint from a user-supplied plan Effect. Use this when your plan needs to read
+ * existing files, branch on detected state, or compose multiple operations.
+ */
+export interface ComputedSpec {
+  readonly id: string
+  readonly version: string
+  readonly description?: string
+  readonly permissions: readonly Permission.Permission[]
+  readonly plan: Effect.Effect<ChangeSet.ChangeSet, Errors.BlueprintError, BlueprintFileSystem>
+}
+
+export const computed = (spec: ComputedSpec): Blueprint.Blueprint => ({
+  id: spec.id,
+  version: spec.version,
+  ...StructX.defined("description", spec.description),
+  permissions: spec.permissions,
+  plan: spec.plan,
+})

package/src/detect.ts

@@ -0,0 +1,48 @@
+import { Effect } from "effect"
+import { BlueprintFileSystem } from "@projitect/core"
+import type { Errors } from "@projitect/core"
+
+export type PackageManager = "pnpm" | "npm" | "yarn" | "bun"
+
+/**
+ * Inspect lockfiles to determine which package manager the project uses. Reads (in order):
+ * `pnpm-lock.yaml`, `bun.lockb`, `yarn.lock`, `package-lock.json`. Falls back to `npm` if none
+ * are present.
+ *
+ * Returns the detected manager; the blueprint must declare `read:` permission on the relevant
+ * lockfile path globs (e.g. `pnpm-lock.yaml`).
+ */
+export const detectPackageManager: Effect.Effect<
+  PackageManager,
+  Errors.FsPermissionDenied | Errors.FsReadFailed,
+  BlueprintFileSystem
+> = Effect.gen(function* () {
+  const fs = yield* BlueprintFileSystem
+  if (yield* fs.exists("pnpm-lock.yaml")) {
+    return "pnpm" as const
+  }
+  if (yield* fs.exists("bun.lockb")) {
+    return "bun" as const
+  }
+  if (yield* fs.exists("yarn.lock")) {
+    return "yarn" as const
+  }
+  if (yield* fs.exists("package-lock.json")) {
+    return "npm" as const
+  }
+  return "npm" as const
+})
+
+/**
+ * Read and parse `package.json` from the project root. Returns the parsed object as `unknown` —
+ * blueprints should decode it with a `Schema` if they need typed access to fields.
+ */
+export const readPackageJson: Effect.Effect<
+  unknown,
+  Errors.FsReadFailed | Errors.FsPermissionDenied,
+  BlueprintFileSystem
+> = Effect.gen(function* () {
+  const fs = yield* BlueprintFileSystem
+  const raw = yield* fs.readFile("package.json")
+  return JSON.parse(raw) as unknown
+})

package/src/directory.ts

@@ -0,0 +1,30 @@
+import { Predicate } from "effect"
+import type { Blueprint } from "@projitect/core"
+
+/**
+ * Scope children to a subdirectory. Inside a `directory(name, [...])` group, every child
+ * blueprint's `path` is reinterpreted relative to `name/`, and write permissions outside the
+ * subtree are stripped from the children's declared `Permission`s.
+ *
+ * Implementation note: `directory` returns a `DirectoryBlueprint` — a tagged variant that the
+ * planner unpacks. Authors should treat the return value as opaque.
+ */
+export interface DirectoryBlueprint {
+  readonly _tag: "Directory"
+  readonly name: string
+  readonly children: readonly (Blueprint.Blueprint | DirectoryBlueprint)[]
+}
+
+export const directory = (
+  name: string,
+  children: readonly (Blueprint.Blueprint | DirectoryBlueprint)[],
+): DirectoryBlueprint => ({
+  _tag: "Directory",
+  name,
+  children,
+})
+
+export const isDirectoryBlueprint = (
+  v: Blueprint.Blueprint | DirectoryBlueprint,
+  // `Directory` is the only member of the union carrying a `_tag`, so its presence is decisive.
+): v is DirectoryBlueprint => Predicate.hasProperty(v, "_tag")