@clearlydev/nx-archweave 0.0.0-stage → 0.1.1

package/dist/generators/record-integration/render.js

@@ -0,0 +1,31 @@
+// Never renders installPath or any absolute/home-directory path — the
+// manifest entry types used here already exclude installPath by
+// construction, and this function only ever reads from
+// those already-narrowed values.
+export function renderRecordIntegrationView(view) {
+    const lines = [
+        `Integration: ${view.tool}`,
+        `Target: ${view.target}`,
+        `Source repository: ${view.sourceRepository}`,
+        `License: ${view.license}`,
+        `Verification source: ${view.verificationSource}`,
+        `Current verification: ${view.verification.verified ? 'passed' : 'not verified'}`,
+        ...view.verification.problems.map((problem) => `  ! ${problem}`),
+        '',
+    ];
+    if (view.hasConflict && view.existingEntry) {
+        lines.push('Conflict: an existing manifest entry differs from what would be recorded.', `  Existing: ${JSON.stringify(view.existingEntry)}`, `  Proposed: ${JSON.stringify(view.proposedEntry)}`, '');
+    }
+    if (view.proposedEntry) {
+        lines.push(view.wasWritten
+            ? 'Recorded — the following manifest entry was written:'
+            : 'The following manifest entry would be recorded:', `  ${JSON.stringify(view.proposedEntry)}`);
+    }
+    else {
+        lines.push('Nothing would be recorded — verification did not succeed via the authoritative claude-cli signal.');
+    }
+    lines.push('', view.wasWritten
+        ? '(recorded — the manifest was written)'
+        : '(dry-run — no files were changed, no installer was executed, manifest was not written)');
+    return lines.join('\n');
+}

package/dist/generators/shared/dry-run.js

@@ -0,0 +1,12 @@
+/**
+ * `nx g` owns the dry-run flag: Nx 23.1's generate command deletes `dryRun` /
+ * `dry-run` from the options it hands a generator and then refills the schema
+ * default, and signals its own `--dry-run` only through `NX_DRY_RUN=true`
+ * (`nx/src/command-line/generate/generate.js`, `command-object.js`). So an Nx
+ * entry point that read only `options.dryRun` would always see `false` and print
+ * "created" for a run Nx never flushes. Programmatic callers (init → the `run*`
+ * cores, tests) keep passing `dryRun` explicitly; Nx's own flag always wins.
+ */
+export function resolveDryRun(options) {
+    return process.env['NX_DRY_RUN'] === 'true' || (options.dryRun ?? false);
+}

package/dist/generators/shared/frontend-app.js

@@ -0,0 +1,57 @@
+import { getProjects } from '@nx/devkit';
+import { resolveProjectType } from "./project-type.js";
+const baseNameOf = (root) => root.split('/').pop() ?? root;
+function isEndToEnd(root) {
+    const dir = baseNameOf(root);
+    return dir === 'e2e' || dir.endsWith('-e2e');
+}
+/** add-backend's api app (default name `api`) and anything tagged as the backend scope are
+ * applications, but not frontends. */
+function isBackend(root, config) {
+    return baseNameOf(root) === 'api' || (config.tags ?? []).includes('scope:backend');
+}
+function sourceRootOf(config) {
+    if (config.sourceRoot)
+        return config.sourceRoot;
+    return config.root === '' || config.root === '.' ? 'src' : `${config.root}/src`;
+}
+/**
+ * Same two tiers as add-backend's frontend lookup: declared applications first; only when
+ * there are none do undeclared projects count, typed the way Nx infers them (Nx's Next.js
+ * and classic-preset apps are bare package.json projects). A declared root application
+ * (a standalone workspace, root `.`) counts; an undeclared root package.json never does.
+ */
+export function resolveFrontendApp(tree, explicitProject) {
+    let projects;
+    try {
+        projects = getProjects(tree);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const pathMatch = /Cannot parse ([^:]+):/.exec(message);
+        return { kind: 'invalid-project-json', detail: pathMatch ? pathMatch[1] : message };
+    }
+    const found = (project, config) => ({
+        kind: 'found',
+        project,
+        root: config.root,
+        sourceRoot: sourceRootOf(config),
+    });
+    if (explicitProject !== undefined) {
+        const config = projects.get(explicitProject);
+        return config ? found(explicitProject, config) : { kind: 'not-found', project: explicitProject };
+    }
+    const eligible = [...projects.entries()].filter(([, config]) => !isEndToEnd(config.root) && !isBackend(config.root, config));
+    const declared = eligible.filter(([, config]) => config.projectType === 'application');
+    const inferred = eligible.filter(([, config]) => config.projectType === undefined &&
+        config.root !== '' &&
+        config.root !== '.' &&
+        resolveProjectType(tree, config.root, undefined) === 'application');
+    const candidates = (declared.length > 0 ? declared : inferred).sort(([a], [b]) => a.localeCompare(b));
+    if (candidates.length === 0)
+        return { kind: 'none' };
+    if (candidates.length > 1)
+        return { kind: 'ambiguous', candidates: candidates.map(([name]) => name) };
+    const [project, config] = candidates[0];
+    return found(project, config);
+}

package/dist/generators/shared/generator.js

@@ -0,0 +1,395 @@
+// src/generators/slice/core.ts
+import { join } from "node:path";
+
+// ../template-engine/dist/fsd/slice-rules.js
+function toCamelCase(kebabName) {
+  return kebabName.split("-").filter((part) => part.length > 0).map((part, index) => index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function resolveSlicePublicApiName(name, publicApiName) {
+  return publicApiName ?? toCamelCase(name);
+}
+var IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var RESERVED_WORDS = /* @__PURE__ */ new Set([
+  "await",
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "implements",
+  "import",
+  "in",
+  "instanceof",
+  "interface",
+  "let",
+  "new",
+  "null",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "return",
+  "static",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield"
+]);
+function isUsableSliceApiName(candidate) {
+  return IDENTIFIER_PATTERN.test(candidate) && !RESERVED_WORDS.has(candidate);
+}
+var ESSENCE_SEGMENT_NAMES = [
+  "components",
+  "hooks",
+  "helpers",
+  "utils",
+  "types",
+  "constants",
+  "consts",
+  "interfaces",
+  "enums",
+  "modals",
+  "stores",
+  "services"
+];
+function isEssenceSegmentName(name) {
+  return ESSENCE_SEGMENT_NAMES.includes(name);
+}
+var SEGMENT_NAME_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+// src/generators/shared/toolkit-config-file.ts
+var TOOLKIT_CONFIG_PATH = "toolkit.config.json";
+function readToolkitConfigFile(tree) {
+  const raw = tree.read(TOOLKIT_CONFIG_PATH, "utf-8");
+  if (raw === null) return { raw: null, parsed: null };
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      raw,
+      parsed: typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null
+    };
+  } catch {
+    return { raw, parsed: null };
+  }
+}
+function readToolkitConfig(tree) {
+  return readToolkitConfigFile(tree).parsed;
+}
+function resolveLocaleOption(option, config) {
+  if (option) return option;
+  const locale = config?.["locale"];
+  return locale === "ko" || locale === "en" ? locale : "en";
+}
+var RECORDED_FRONTENDS = ["react-vite", "next", "none"];
+
+// src/generators/shared/frontend-app.ts
+import { getProjects } from "@nx/devkit";
+
+// src/generators/shared/project-type.ts
+import { parseJson } from "@nx/devkit";
+function resolveProjectType(tree, root, declared) {
+  if (declared) return declared === "library" ? "library" : "application";
+  const prefix = root === "" || root === "." ? "" : `${root}/`;
+  if (tree.exists(`${prefix}tsconfig.lib.json`)) return "library";
+  if (tree.exists(`${prefix}tsconfig.app.json`)) return "application";
+  const raw = tree.read(`${prefix}package.json`, "utf-8");
+  if (raw === null) return "library";
+  try {
+    const manifest = parseJson(raw);
+    if (manifest && !["exports", "main", "module", "bin"].some((key) => Boolean(manifest[key]))) return "application";
+  } catch {
+  }
+  return "library";
+}
+
+// src/generators/shared/frontend-app.ts
+var baseNameOf = (root) => root.split("/").pop() ?? root;
+function isEndToEnd(root) {
+  const dir = baseNameOf(root);
+  return dir === "e2e" || dir.endsWith("-e2e");
+}
+function isBackend(root, config) {
+  return baseNameOf(root) === "api" || (config.tags ?? []).includes("scope:backend");
+}
+function sourceRootOf(config) {
+  if (config.sourceRoot) return config.sourceRoot;
+  return config.root === "" || config.root === "." ? "src" : `${config.root}/src`;
+}
+function resolveFrontendApp(tree, explicitProject) {
+  let projects;
+  try {
+    projects = getProjects(tree);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const pathMatch = /Cannot parse ([^:]+):/.exec(message);
+    return { kind: "invalid-project-json", detail: pathMatch ? pathMatch[1] : message };
+  }
+  const found = (project2, config2) => ({
+    kind: "found",
+    project: project2,
+    root: config2.root,
+    sourceRoot: sourceRootOf(config2)
+  });
+  if (explicitProject !== void 0) {
+    const config2 = projects.get(explicitProject);
+    return config2 ? found(explicitProject, config2) : { kind: "not-found", project: explicitProject };
+  }
+  const eligible = [...projects.entries()].filter(([, config2]) => !isEndToEnd(config2.root) && !isBackend(config2.root, config2));
+  const declared = eligible.filter(([, config2]) => config2.projectType === "application");
+  const inferred = eligible.filter(
+    ([, config2]) => config2.projectType === void 0 && config2.root !== "" && config2.root !== "." && resolveProjectType(tree, config2.root, void 0) === "application"
+  );
+  const candidates = (declared.length > 0 ? declared : inferred).sort(([a], [b]) => a.localeCompare(b));
+  if (candidates.length === 0) return { kind: "none" };
+  if (candidates.length > 1) return { kind: "ambiguous", candidates: candidates.map(([name]) => name) };
+  const [project, config] = candidates[0];
+  return found(project, config);
+}
+
+// src/generators/shared/template-files.ts
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { generateFiles } from "@nx/devkit";
+import { createTree } from "@nx/devkit/testing";
+function generatorFilesDir(generator, fromUrl) {
+  for (const relative of [`../${generator}/files`, `./generators/${generator}/files`]) {
+    const dir = fileURLToPath(new URL(relative, fromUrl));
+    if (existsSync(dir)) return dir;
+  }
+  throw new Error(`The "${generator}" generator's template files are missing next to ${fileURLToPath(fromUrl)}`);
+}
+function renderTemplateFiles(srcFolder, target, substitutions) {
+  const scratch = createTree();
+  const seeded = new Set(scratch.listChanges().map((change) => change.path));
+  generateFiles(scratch, srcFolder, target, substitutions);
+  return scratch.listChanges().flatMap(
+    (change) => change.type === "CREATE" && change.content !== null && !seeded.has(change.path) ? [{ filePath: change.path, content: change.content.toString("utf-8") }] : []
+  ).sort((a, b) => a.filePath.localeCompare(b.filePath));
+}
+
+// src/generators/slice/core.ts
+function composeSlice(input) {
+  const files = generatorFilesDir("slice", import.meta.url);
+  const directory = `${input.sourceRoot}/${input.layerDirName}/${input.name}`;
+  const shared = input.layer === "shared";
+  const values = {
+    name: input.name,
+    publicApiName: input.publicApiName,
+    layer: input.layer,
+    locale: input.locale,
+    modulePath: shared ? `./${input.name}` : `./model/${input.name}`
+  };
+  const module = renderTemplateFiles(join(files, "module"), shared ? directory : `${directory}/model`, values).sort((a, b) => Number(a.filePath.endsWith(".spec.ts")) - Number(b.filePath.endsWith(".spec.ts")));
+  const segments = shared ? [] : Array.from(new Set(input.segments)).filter((segment) => segment !== "model").flatMap((segment) => renderTemplateFiles(join(files, "segment"), `${directory}/${segment}`, { ...values, segment }));
+  return {
+    directory,
+    publicApiName: input.publicApiName,
+    files: [...renderTemplateFiles(join(files, "index"), directory, values), ...module, ...segments]
+  };
+}
+var KEBAB_CASE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function layerDirNameFor(layer, frontend) {
+  return layer === "pages" && frontend === "next" ? "_pages" : layer;
+}
+function layerDirFor(layer, sourceRoot, frontend = "react-vite") {
+  return `${sourceRoot}/${layerDirNameFor(layer, frontend)}`;
+}
+var NEXT_CONFIG_FILES = ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"];
+function resolveFrontendForApp(option, config, appRoot, tree) {
+  if (option === "react-vite" || option === "next") return option;
+  const recorded = config?.["frontend"];
+  if (typeof recorded === "string" && RECORDED_FRONTENDS.includes(recorded) && recorded !== "none") {
+    return recorded;
+  }
+  const prefix = appRoot === "" || appRoot === "." ? "" : `${appRoot}/`;
+  return NEXT_CONFIG_FILES.some((file) => tree.exists(`${prefix}${file}`)) ? "next" : "react-vite";
+}
+function listFilesUnder(tree, dir, prefix = "") {
+  return tree.children(dir).flatMap((child) => {
+    const path = `${dir}/${child}`;
+    return tree.isFile(path) ? [`${prefix}${child}`] : listFilesUnder(tree, path, `${prefix}${child}/`);
+  });
+}
+function computeSliceAction(tree, plan) {
+  if (!tree.exists(plan.directory)) return "created";
+  const expectedNames = plan.files.map((f) => f.filePath.slice(plan.directory.length + 1)).sort();
+  const actualNames = listFilesUnder(tree, plan.directory).sort();
+  if (actualNames.length !== expectedNames.length || !actualNames.every((n, i) => n === expectedNames[i])) {
+    return "skipped";
+  }
+  const allMatch = plan.files.every((f) => tree.read(f.filePath, "utf-8") === f.content);
+  return allMatch ? "unchanged" : "skipped";
+}
+function refusal(reason, dryRun, layer, name, app, extra = {}) {
+  const layerDir = layerDirFor(layer, app.sourceRoot);
+  return {
+    dryRun,
+    layer,
+    name,
+    project: app.project,
+    layerDir,
+    directory: `${layerDir}/${name}`,
+    publicApiName: null,
+    refused: true,
+    refusalReason: reason,
+    action: null,
+    files: [],
+    ...extra
+  };
+}
+function runFsdSlice(tree, layer, options) {
+  const dryRun = options.dryRun ?? false;
+  const unresolved = { project: null, sourceRoot: "<app>/src" };
+  if (!KEBAB_CASE.test(options.name)) {
+    return refusal("invalid-name", dryRun, layer, options.name, unresolved);
+  }
+  if (!isUsableSliceApiName(resolveSlicePublicApiName(options.name, options.publicApiName))) {
+    return refusal("invalid-public-api-name", dryRun, layer, options.name, unresolved);
+  }
+  if (layer === "shared" && isEssenceSegmentName(options.name)) {
+    return refusal("segment-by-essence", dryRun, layer, options.name, unresolved);
+  }
+  const segments = Array.from(new Set(options.segments ?? []));
+  if (segments.length > 0 && layer === "shared") {
+    return refusal("segments-on-shared", dryRun, layer, options.name, unresolved);
+  }
+  const badSegment = segments.find((segment) => !SEGMENT_NAME_PATTERN.test(segment));
+  if (badSegment !== void 0) return refusal("invalid-segment", dryRun, layer, options.name, unresolved, { detail: badSegment });
+  const essenceSegment = segments.find((segment) => isEssenceSegmentName(segment));
+  if (essenceSegment !== void 0) return refusal("segment-by-essence", dryRun, layer, options.name, unresolved, { detail: essenceSegment });
+  const app = resolveFrontendApp(tree, options.project);
+  if (app.kind === "not-found") return refusal("project-not-found", dryRun, layer, options.name, { project: app.project, sourceRoot: unresolved.sourceRoot });
+  if (app.kind === "ambiguous") return refusal("ambiguous-frontend", dryRun, layer, options.name, unresolved, { candidates: app.candidates });
+  if (app.kind === "invalid-project-json") return refusal("invalid-project-json", dryRun, layer, options.name, unresolved, { detail: app.detail });
+  if (app.kind === "none") return refusal("no-frontend-app", dryRun, layer, options.name, unresolved);
+  const config = readToolkitConfig(tree);
+  const frontend = resolveFrontendForApp(options.frontend, config, app.root, tree);
+  const layerDir = layerDirFor(layer, app.sourceRoot, frontend);
+  const locale = resolveLocaleOption(options.locale, config);
+  const plan = composeSlice({
+    layer,
+    name: options.name,
+    publicApiName: resolveSlicePublicApiName(options.name, options.publicApiName),
+    locale,
+    sourceRoot: app.sourceRoot,
+    layerDirName: layerDirNameFor(layer, frontend),
+    segments
+  });
+  const action = computeSliceAction(tree, plan);
+  if (action === "created" && !dryRun) {
+    for (const file of plan.files) tree.write(file.filePath, file.content);
+  }
+  return {
+    dryRun,
+    layer,
+    name: options.name,
+    project: app.project,
+    layerDir,
+    directory: plan.directory,
+    publicApiName: plan.publicApiName,
+    refused: false,
+    refusalReason: null,
+    action,
+    files: plan.files
+  };
+}
+
+// src/generators/slice/render.ts
+var ACTION_LINES = {
+  created: "created",
+  unchanged: "unchanged (already matches the generated content)",
+  skipped: "skipped \u2014 a slice with this name already exists with different content"
+};
+function renderSliceReport(report) {
+  const lines = [];
+  const label = `${report.layer} "${report.name}"`;
+  if (report.refused) {
+    lines.push(`${label}: refused \u2014 nothing was written.`);
+    lines.push("");
+    if (report.refusalReason === "invalid-name") {
+      lines.push(`  "${report.name}" is not a valid kebab-case slice name.`);
+      lines.push('  Use lowercase letters, digits, and single hyphens, starting with a letter (e.g. "add-to-cart").');
+    } else if (report.refusalReason === "invalid-public-api-name") {
+      lines.push("  The public API name is not a usable JavaScript identifier (or is a reserved word).");
+      lines.push('  Pass --publicApiName with a valid identifier, e.g. "addToCart" (this also happens when');
+      lines.push('  the slice name camelCases into a reserved word, like "class" or "delete").');
+    } else if (report.refusalReason === "project-not-found") {
+      lines.push(`  --project=${report.project} names no project in this workspace.`);
+    } else if (report.refusalReason === "ambiguous-frontend") {
+      lines.push("  More than one frontend app was found \u2014 rerun with --project=<one of them>:");
+      for (const name of report.candidates ?? []) lines.push(`    - ${name}`);
+    } else if (report.refusalReason === "invalid-project-json") {
+      lines.push(`  A project.json could not be parsed (${report.detail ?? "unknown"}) \u2014 fix it, then rerun.`);
+    } else if (report.refusalReason === "no-frontend-app") {
+      lines.push("  The workspace has no frontend application to hold FSD layers \u2014 create one, or pass --project.");
+    } else if (report.refusalReason === "invalid-segment") {
+      lines.push(`  --segments: "${report.detail ?? ""}" is not a valid segment name.`);
+      lines.push("  Use lowercase letters, digits, and single hyphens, starting with a letter (e.g. ui, api, lib).");
+    } else if (report.refusalReason === "segments-on-shared") {
+      lines.push("  --segments does not apply to shared: a shared segment holds no segments of its own.");
+      lines.push("  Run the generator once per segment instead (e.g. --name=ui, then --name=api).");
+    } else {
+      const offender = report.detail ?? report.name;
+      lines.push(`  "${offender}" names what a segment contains, not what it is for.`);
+      lines.push("  Canonical FSD names segments by purpose \u2014 ui, api, model, lib, config \u2014 so the code stays");
+      lines.push("  findable by what it does (e.g. a date helper lives in shared/lib, a Button in shared/ui).");
+    }
+    return lines.join("\n");
+  }
+  if (report.dryRun) {
+    lines.push("dry-run \u2014 no files were written.");
+    lines.push("");
+  }
+  lines.push(`${label}: ${ACTION_LINES[report.action]}`);
+  if (report.action === "skipped") {
+    lines.push(`  ${report.directory} already exists and does not exactly match the generated content.`);
+    lines.push("  Pick a new slice name (a name collision is a signal to rename, not to merge)");
+    lines.push("  \u2014 or remove the existing directory manually first if you intended to replace it.");
+    return lines.join("\n");
+  }
+  if (report.dryRun) {
+    for (const file of report.files) {
+      lines.push("");
+      lines.push(`${file.filePath}:`);
+      lines.push(file.content);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/generators/shared/dry-run.ts
+function resolveDryRun(options) {
+  return process.env["NX_DRY_RUN"] === "true" || (options.dryRun ?? false);
+}
+
+// src/generators/shared/generator.ts
+async function sharedGenerator(tree, options) {
+  console.log(renderSliceReport(runFsdSlice(tree, "shared", { ...options, dryRun: resolveDryRun(options) })));
+}
+var generator_default = sharedGenerator;
+export {
+  generator_default as default,
+  sharedGenerator
+};

package/dist/generators/shared/project-type.js

@@ -0,0 +1,39 @@
+import { parseJson } from '@nx/devkit';
+/**
+ * The project type Nx itself would use when a project declares none — the
+ * classic-preset Nx 23 layout configures apps through a bare package.json, so a
+ * filter on the declared `projectType` alone misses every one of them.
+ *
+ * Mirrors the project graph's rule (nx 23 core `normalize-project-nodes`
+ * `getProjectType`): a declared type wins (anything but `library` counts as an
+ * application, as in Nx); then `tsconfig.lib.json` → library; `tsconfig.app.json`
+ * → application; a readable package.json with none of exports/main/module/bin
+ * set → application; anything else — including a missing or unparseable
+ * package.json — → library. Mirrored, not imported: the plugin's only runtime
+ * dependency stays @nx/devkit. Not mirrored: the package-json plugin's
+ * `workspaceLayout.appsDir`/`libsDir` override, which devkit's tree-based
+ * `getProjects` never applies either.
+ */
+export function resolveProjectType(tree, root, declared) {
+    if (declared)
+        return declared === 'library' ? 'library' : 'application';
+    const prefix = root === '' || root === '.' ? '' : `${root}/`;
+    if (tree.exists(`${prefix}tsconfig.lib.json`))
+        return 'library';
+    if (tree.exists(`${prefix}tsconfig.app.json`))
+        return 'application';
+    const raw = tree.read(`${prefix}package.json`, 'utf-8');
+    if (raw === null)
+        return 'library';
+    try {
+        // parseJson accepts comments and trailing commas, like Nx's readJsonFile
+        const manifest = parseJson(raw);
+        // truthiness, like Nx: an empty "main": "" is no entry point
+        if (manifest && !['exports', 'main', 'module', 'bin'].some((key) => Boolean(manifest[key])))
+            return 'application';
+    }
+    catch {
+        // unparseable — Nx's graph falls through to library as well
+    }
+    return 'library';
+}

package/dist/generators/shared/record-pipeline.js

@@ -0,0 +1,34 @@
+import { buildRecordPlan, getCatalogEntry, loadManifest, recordMetadataFor, verifyClaudeMarketplacePlugin, writeManifestAtomic, } from '@nx-archweave/integrations';
+/**
+ * Live verify → manifest record, shared by record-integration and install-integration.
+ * Always a fresh call — never a cached result. Only a
+ * claude-cli-sourced verified:true is recordable (buildRecordPlan enforces it); the write
+ * is the atomic manifest write and happens only when `write` is set.
+ */
+export async function runRecordPipeline(input) {
+    const entry = getCatalogEntry(input.id);
+    // Where it came from comes from the catalog entry.
+    const metadata = entry === undefined ? undefined : recordMetadataFor(entry);
+    if (!entry || !metadata) {
+        throw new Error(`No manifest metadata is defined for "${input.id}".`);
+    }
+    const { result: verification, source: verificationSource } = await verifyClaudeMarketplacePlugin(entry, { runner: input.runner }, { workspaceRoot: input.workspaceRoot, targetEnvironment: input.target });
+    const manifest = loadManifest(input.workspaceRoot);
+    const existingEntry = manifest.integrations[input.id];
+    const plan = buildRecordPlan({ id: input.id, target: input.target, verificationSource, verification, existingEntry, metadata });
+    let wasWritten = false;
+    if (input.write && plan.proposedEntry) {
+        writeManifestAtomic(input.workspaceRoot, {
+            integrations: { ...manifest.integrations, [input.id]: plan.proposedEntry },
+        });
+        wasWritten = true;
+    }
+    return {
+        verificationSource,
+        verification,
+        existingEntry,
+        proposedEntry: plan.proposedEntry,
+        hasConflict: plan.hasConflict,
+        wasWritten,
+    };
+}

package/dist/generators/shared/run-nx.js

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { packageManagerCommands } from '@nx-archweave/template-engine';
+import { TOOLKIT_CONFIG_PATH, workspacePackageManager } from "./toolkit-config-file.js";
+/** How a person runs the workspace's own nx — `pnpm nx`, `yarn nx`, `bun nx` or
+ * `npm exec nx --` — for the commands generators print. The detected package manager, then
+ * the one init recorded, else pnpm (the same order init, add-backend and add-review use). */
+export function runNxFor(exists, read) {
+    let config = null;
+    try {
+        const parsed = JSON.parse(read(TOOLKIT_CONFIG_PATH) ?? 'null');
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed))
+            config = parsed;
+    }
+    catch {
+        // an unreadable config only means nothing is recorded
+    }
+    return packageManagerCommands(workspacePackageManager(exists, read, config) ?? 'pnpm').runNx;
+}
+/** From the workspace on disk — doctor and the integration generators, which act on the
+ * real workspace (tree.root) rather than the Nx Tree. */
+export function diskRunNx(root) {
+    return runNxFor((path) => existsSync(join(root, path)), (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf-8') : undefined));
+}

package/dist/generators/shared/template-files.js

@@ -0,0 +1,38 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { generateFiles } from '@nx/devkit';
+// createTree is the devkit's in-memory Tree; it holds the rendered files until the caller has
+// compared each one with the workspace.
+import { createTree } from '@nx/devkit/testing';
+/**
+ * The `files/` directory of a generator. `fromUrl` is the calling module's `import.meta.url`:
+ * from source and from a generator's own bundle that is `../<generator>/files`; from a bundle
+ * that inlines another generator (init runs add-github-templates) the sibling directory is
+ * the same, and from the package's root `index.js` it is `./generators/<generator>/files`.
+ */
+export function generatorFilesDir(generator, fromUrl) {
+    for (const relative of [`../${generator}/files`, `./generators/${generator}/files`]) {
+        const dir = fileURLToPath(new URL(relative, fromUrl));
+        if (existsSync(dir))
+            return dir;
+    }
+    throw new Error(`The "${generator}" generator's template files are missing next to ${fileURLToPath(fromUrl)}`);
+}
+/**
+ * Renders a template folder the way every Nx generator does — `generateFiles`: `__key__` in
+ * paths and EJS in contents take the substitutions, a `.template` suffix is dropped — into a
+ * scratch tree, and returns the files sorted by path. The caller decides what reaches the
+ * workspace (create, leave an existing file alone, or only report it in a dry run).
+ */
+export function renderTemplateFiles(srcFolder, target, substitutions) {
+    const scratch = createTree();
+    // createTree seeds a .prettierrc; only what generateFiles adds belongs to the result.
+    const seeded = new Set(scratch.listChanges().map((change) => change.path));
+    generateFiles(scratch, srcFolder, target, substitutions);
+    return scratch
+        .listChanges()
+        .flatMap((change) => change.type === 'CREATE' && change.content !== null && !seeded.has(change.path)
+        ? [{ filePath: change.path, content: change.content.toString('utf-8') }]
+        : [])
+        .sort((a, b) => a.filePath.localeCompare(b.filePath));
+}