@clearlydev/nx-archweave 0.0.0-stage → 0.1.1

package/dist/runtime/integrations-composition-root.js

@@ -0,0 +1,20 @@
+import { createCatalogIntegrations, createIntegrationRegistry, getIntegration as getIntegrationFromRegistry, listIntegrations as listIntegrationsFromRegistry, } from '@nx-archweave/integrations';
+import { NodeCommandRunner } from "./node-command-runner.js";
+// The single place every generator (doctor, add-integration,
+// record-integration) obtains its ToolIntegration objects from — never a
+// package-level singleton (factory-based
+// construction). Each call constructs a fresh registry; there is no shared,
+// mutated module state between calls. Defaults to the real, Node-backed
+// runner; tests inject a fake one. The tool list is the plugin catalog (data, in
+// @nx-archweave/integrations); the generators' --tool/--target schema enums are kept
+// equal to it by a test (catalog-schema-enums.spec.ts).
+export function createIntegrationsCompositionRoot(deps = {}) {
+    const runner = deps.runner ?? new NodeCommandRunner();
+    const registry = createIntegrationRegistry(createCatalogIntegrations({ runner }));
+    return {
+        registry,
+        runner,
+        getIntegration: (id) => getIntegrationFromRegistry(registry, id),
+        listIntegrations: () => listIntegrationsFromRegistry(registry),
+    };
+}

package/dist/runtime/node-command-runner.js

@@ -0,0 +1,81 @@
+import { spawn } from 'node:child_process';
+import { spawnableCommand } from '@nx-archweave/shared';
+// SIGTERM is not guaranteed to actually end a process — a child that traps
+// or ignores it would otherwise keep this runner's promise pending forever,
+// silently defeating the fixed timeout/output-limit guarantees. SIGKILL
+// cannot be caught or ignored, so it is the backstop once a process has had
+// a short grace period to exit cleanly on its own.
+const KILL_GRACE_MS = 500;
+// The one place node:child_process is imported — packages/integrations never
+// imports it directly. Uses spawn (never a shell) so stdout/stderr can be bounded
+// independently at the exact approved limits, and so the child process can be
+// terminated on timeout or overflow without waiting for it to finish producing output.
+export class NodeCommandRunner {
+    run(input) {
+        return new Promise((resolve, reject) => {
+            let stdout = '';
+            let stderr = '';
+            let timedOut = false;
+            let outputExceeded = false;
+            let settled = false;
+            let killTimer;
+            // An npm-installed claude is a .cmd shim on Windows: it runs through cmd.exe with every
+            // argument escaped — still never a shell string built from raw input.
+            const spawnable = spawnableCommand(input.executable, input.argv);
+            const child = spawn(spawnable.command, spawnable.args, {
+                cwd: input.cwd,
+                shell: false,
+                windowsVerbatimArguments: spawnable.windowsVerbatimArguments,
+                windowsHide: true,
+                // No stdin: nothing here ever answers a prompt (a command that wants
+                // confirmation must fail fast instead of waiting on an open pipe).
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            // SIGTERM first (lets a well-behaved process clean up); SIGKILL after a
+            // short grace period as a backstop against one that ignores it.
+            const terminate = () => {
+                child.kill('SIGTERM');
+                killTimer = setTimeout(() => {
+                    child.kill('SIGKILL');
+                }, KILL_GRACE_MS);
+            };
+            const timer = setTimeout(() => {
+                timedOut = true;
+                terminate();
+            }, input.timeoutMs);
+            child.stdout.on('data', (chunk) => {
+                stdout += chunk.toString('utf8');
+                if (Buffer.byteLength(stdout, 'utf8') > input.stdoutLimitBytes) {
+                    outputExceeded = true;
+                    terminate();
+                }
+            });
+            child.stderr.on('data', (chunk) => {
+                stderr += chunk.toString('utf8');
+                if (Buffer.byteLength(stderr, 'utf8') > input.stderrLimitBytes) {
+                    outputExceeded = true;
+                    terminate();
+                }
+            });
+            // Spawn-level failure (e.g. ENOENT — executable not found) is distinct
+            // from a completed process with a non-zero exit code. Only this case
+            // rejects the promise.
+            child.on('error', (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                clearTimeout(killTimer);
+                reject(error);
+            });
+            child.on('close', (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                clearTimeout(killTimer);
+                resolve({ stdout, stderr, exitCode: code, timedOut, outputExceeded });
+            });
+        });
+    }
+}

package/generators.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://raw.githubusercontent.com/nrwl/nx/master/packages/nx/schemas/generators.json",
+  "generators": {
+    "doctor": {
+      "factory": "./dist/generators/doctor/generator",
+      "schema": "./src/generators/doctor/schema.json",
+      "description": "Diagnose the current Nx workspace (read-only)"
+    },
+    "init": {
+      "factory": "./dist/generators/init/generator",
+      "schema": "./src/generators/init/schema.json",
+      "description": "Run the preset-driven init pipeline (FSD Lite, agent rules, GitHub templates, review) against a clean working tree"
+    },
+    "add-integration": {
+      "factory": "./dist/generators/add-integration/generator",
+      "schema": "./src/generators/add-integration/schema.json",
+      "description": "Preview the official installation flow for a supported external integration"
+    },
+    "add-review": {
+      "factory": "./dist/generators/add-review/generator",
+      "schema": "./src/generators/add-review/schema.json",
+      "description": "Install the Claude PR review workflow"
+    },
+    "add-backend": {
+      "factory": "./dist/generators/add-backend/generator",
+      "schema": "./src/generators/add-backend/schema.json",
+      "description": "Wire a backend app into the workspace: shared-types lib, scope tags, and module-boundary constraints"
+    },
+    "add-agent-rules": {
+      "factory": "./dist/generators/add-agent-rules/generator",
+      "schema": "./src/generators/add-agent-rules/schema.json",
+      "description": "Install CLAUDE.md / AGENTS.md agent rules"
+    },
+    "add-github-templates": {
+      "factory": "./dist/generators/add-github-templates/generator",
+      "schema": "./src/generators/add-github-templates/schema.json",
+      "description": "Install GitHub Issue/PR templates and CODEOWNERS"
+    },
+    "add-fsd-lite": {
+      "factory": "./dist/generators/add-fsd-lite/generator",
+      "schema": "./src/generators/add-fsd-lite/schema.json",
+      "description": "Wire the archweave/fsd-boundaries ESLint rule into the frontend app and print the FSD layer guide"
+    },
+    "page": {
+      "factory": "./dist/generators/page/generator",
+      "schema": "./src/generators/page/schema.json",
+      "description": "Scaffold a new FSD page slice under src/pages (src/_pages on Next.js)"
+    },
+    "widget": {
+      "factory": "./dist/generators/widget/generator",
+      "schema": "./src/generators/widget/schema.json",
+      "description": "Scaffold a new FSD widget slice under src/widgets (opt-in: outside the Lite default scope)"
+    },
+    "feature": {
+      "factory": "./dist/generators/feature/generator",
+      "schema": "./src/generators/feature/schema.json",
+      "description": "Scaffold a new FSD feature slice under src/features"
+    },
+    "entity": {
+      "factory": "./dist/generators/entity/generator",
+      "schema": "./src/generators/entity/schema.json",
+      "description": "Scaffold a new FSD entity slice under src/entities"
+    },
+    "shared": {
+      "factory": "./dist/generators/shared/generator",
+      "schema": "./src/generators/shared/schema.json",
+      "description": "Scaffold a new FSD shared slice under src/shared"
+    },
+    "install-integration": {
+      "factory": "./dist/generators/install-integration/generator",
+      "schema": "./src/generators/install-integration/schema.json",
+      "description": "Install a supported external integration through its official CLI (on --dryRun=false), verify it live, record it, and declare it"
+    },
+    "record-integration": {
+      "factory": "./dist/generators/record-integration/generator",
+      "schema": "./src/generators/record-integration/schema.json",
+      "description": "Verify a manually installed integration and record its verified state"
+    },
+    "allow-builds": {
+      "factory": "./dist/generators/allow-builds/generator",
+      "schema": "./src/generators/allow-builds/schema.json",
+      "description": "Allow dependency build scripts pnpm skipped (pnpm-workspace.yaml) and, on --apply, run pnpm rebuild for them"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,97 @@
 {
   "name": "@clearlydev/nx-archweave",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Nx generators that make a workspace ready to work on in one preset: FSD Lite structure with enforced module boundaries, AI agent rules, GitHub templates, and optional AI PR review (Claude, Gemini, GPT, Cursor)",
+  "license": "MIT",
+  "author": "clearlydev (https://github.com/clearlydev)",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clearlydev/nx-archweave.git",
+    "directory": "packages/nx-plugin"
+  },
+  "homepage": "https://github.com/clearlydev/nx-archweave/tree/main/packages/nx-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/clearlydev/nx-archweave/issues"
+  },
+  "keywords": [
+    "nx",
+    "nx-plugin",
+    "generators",
+    "monorepo",
+    "scaffolding",
+    "feature-sliced-design",
+    "fsd",
+    "ai",
+    "code-review",
+    "claude",
+    "gemini",
+    "gpt",
+    "cursor"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "pnpm exec nx run @clearlydev/nx-archweave:bundle && node ../../tools/pack-sanitize.mjs prepack",
+    "postpack": "node ../../tools/pack-sanitize.mjs postpack"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "generators": "./generators.json",
+  "bin": {
+    "archweave-review-verdict": "dist/bin/review-verdict.js"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@nx-archweave/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./eslint": {
+      "@nx-archweave/source": "./src/eslint/index.ts",
+      "types": "./dist/eslint/index.d.ts",
+      "import": "./dist/eslint/index.js",
+      "default": "./dist/eslint/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "generators.json",
+    "src/generators/*/schema.json",
+    "!**/*.tsbuildinfo",
+    "!**/*.d.ts.map",
+    "!dist/generators/**/*.d.ts",
+    "!dist/runtime/**/*.d.ts",
+    "!dist/bin/**/*.d.ts"
+  ],
+  "nx": {
+    "tags": [
+      "type:plugin"
+    ],
+    "targets": {
+      "bundle": {
+        "executor": "nx:run-commands",
+        "dependsOn": [
+          "build"
+        ],
+        "options": {
+          "command": "node tools/bundle.mjs nx-plugin"
+        },
+        "outputs": [
+          "{projectRoot}/dist"
+        ]
+      }
+    }
+  },
+  "dependencies": {
+    "@nx/devkit": "^23.1.0"
+  }
+}

package/src/generators/add-agent-rules/schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "id": "AddAgentRules",
+  "title": "Write nx-archweave's agent rules into CLAUDE.md / AGENTS.md for the AI hosts you use",
+  "type": "object",
+  "properties": {
+    "hosts": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["claude-code", "codex", "cursor", "gemini-cli"]
+      },
+      "description": "The AI coding tools you use. Claude Code reads CLAUDE.md; Codex, Cursor and Gemini CLI read AGENTS.md. Defaults to toolkit.config.json's aiHosts, else Claude Code.",
+      "x-prompt": {
+        "message": "Which AI coding tools do you use? (space to select, enter to confirm; none selected = toolkit.config.json's aiHosts, else Claude Code)",
+        "type": "list",
+        "multiselect": true,
+        "items": [
+          { "value": "claude-code", "label": "Claude Code" },
+          { "value": "codex", "label": "Codex" },
+          { "value": "cursor", "label": "Cursor" },
+          { "value": "gemini-cli", "label": "Gemini CLI" }
+        ]
+      }
+    },
+    "locale": {
+      "type": "string",
+      "enum": ["ko", "en"],
+      "description": "Content language. Defaults to toolkit.config.json's locale, else en"
+    },
+    "teamRules": {
+      "type": "boolean",
+      "description": "Include the Team Rules section (collaboration rules for a shared repository). Defaults to toolkit.config.json's agentRules.teamRules, else false"
+    },
+    "dryRun": {
+      "type": "boolean",
+      "default": false,
+      "description": "Print the full generated content and effective decision without writing"
+    }
+  },
+  "required": []
+}

package/src/generators/add-backend/schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "id": "AddBackend",
+  "title": "Wire a backend app into the workspace: shared-types, scope tags, module-boundary constraints",
+  "type": "object",
+  "properties": {
+    "backend": {
+      "type": "string",
+      "enum": [
+        "express",
+        "nest"
+      ],
+      "description": "Which backend the api app uses. App creation itself is delegated to the official @nx generator — when the api project is missing, the refusal report prints the exact commands to run first"
+    },
+    "apiName": {
+      "type": "string",
+      "default": "api",
+      "description": "Name of the backend application project to wire (convention: api)"
+    },
+    "frontendProject": {
+      "type": "string",
+      "description": "Explicit frontend project to wire, skipping auto-detection — the escape hatch when the workspace has several applications"
+    },
+    "applyEslint": {
+      "type": "boolean",
+      "default": false,
+      "description": "Write the scope depConstraints into the root ESLint config (only the exact Nx-generated allow-all block is rewritten; anything else degrades to a report-only snippet). Off by default so existing configs are never modified unasked"
+    },
+    "dryRun": {
+      "type": "boolean",
+      "default": false,
+      "description": "Preview every wiring action with zero writes"
+    }
+  },
+  "required": [
+    "backend"
+  ]
+}

package/src/generators/add-fsd-lite/schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "id": "AddFsdLite",
+  "title": "Wire the FSD layer rules into the frontend app",
+  "type": "object",
+  "properties": {
+    "frontend": {
+      "type": "string",
+      "enum": ["react-vite", "next"],
+      "description": "Target frontend — decides the layer set the guide prints. Next.js has no FSD 'app' layer (its App Router directory is it) and its pages layer is the _pages/ directory (FSD's Next.js guide: Next.js reads src/pages as its Pages Router). Omitted: toolkit.config.json's frontend (init records it); required when none is recorded"
+    },
+    "project": {
+      "type": "string",
+      "description": "The frontend app whose eslint.config.mjs gets the rule and whose source root holds the layers. Omitted: the workspace's one frontend application (e2e projects and the backend api are not candidates); with more than one, the run is refused with the candidates listed"
+    },
+    "enforcement": {
+      "type": "string",
+      "enum": ["error", "warn"],
+      "description": "Severity of the archweave/fsd-boundaries ESLint rule. The rule is canonical FSD either way; only how hard it reports differs (Team preset: error; Solo / Quick Start: warn). Defaults to toolkit.config.json's fsd.enforcement, else warn"
+    },
+    "applyEslint": {
+      "type": "boolean",
+      "default": false,
+      "description": "Write the rule into the app's ESLint config instead of printing a paste-ready snippet. The create CLI passes this on workspaces it just created; leave it off to keep an existing config untouched"
+    },
+    "steiger": {
+      "type": "boolean",
+      "default": false,
+      "description": "Also set up steiger, the official FSD linter, as an opt-in fsd-check target: writes the app's steiger.config.mjs (recommended rules; an existing config is kept), adds the target to the app and the two devDependencies to the root package.json, and prints the install command. Needs Node >= 22.18"
+    },
+    "locale": {
+      "type": "string",
+      "enum": ["ko", "en"],
+      "description": "Report and snippet language. Defaults to toolkit.config.json's locale, else en"
+    },
+    "dryRun": {
+      "type": "boolean",
+      "default": false,
+      "description": "Print the report (including what --applyEslint would write) without writing anything"
+    }
+  }
+}

package/src/generators/add-github-templates/schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "id": "AddGithubTemplates",
+  "title": "Install GitHub Issue/PR templates and CODEOWNERS",
+  "type": "object",
+  "properties": {
+    "issue": {
+      "type": "boolean",
+      "default": false,
+      "description": "Install the bug-report and feature-request Issue Forms"
+    },
+    "pr": {
+      "type": "boolean",
+      "default": true,
+      "description": "Install the PULL_REQUEST_TEMPLATE.md"
+    },
+    "codeowners": {
+      "type": "boolean",
+      "default": false,
+      "description": "Install a CODEOWNERS placeholder"
+    },
+    "locale": {
+      "type": "string",
+      "enum": ["ko", "en"],
+      "description": "Template language. Defaults to toolkit.config.json's locale, else en"
+    },
+    "dryRun": {
+      "type": "boolean",
+      "default": false,
+      "description": "Print the full content of every selected file without writing"
+    }
+  },
+  "required": []
+}

package/src/generators/add-integration/schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "id": "AddIntegration",
+  "title": "Preview the official installation flow for a supported external integration",
+  "type": "object",
+  "properties": {
+    "tool": {
+      "type": "string",
+      "enum": ["ponytail"],
+      "description": "The plugin to preview, by its plugin-catalog id (@nx-archweave/integrations plugin-catalog.ts). The enum is kept equal to the catalog by a test."
+    },
+    "target": {
+      "type": "string",
+      "enum": ["claude-code"],
+      "default": "claude-code",
+      "description": "The host environment to target. Hosts with a plugin adapter; today only 'claude-code'."
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["user", "project", "local"],
+      "description": "Claude Code plugin scope shown in the previewed install command (default project: recorded in the workspace's .claude/settings.json). Only an explicit value is carried into the install-integration hint."
+    },
+    "versionRange": {
+      "type": "string",
+      "description": "Version to show as requested. Without it, the preview says the marketplace decides — it installs its own latest. No network access."
+    },
+    "dryRun": {
+      "type": "boolean",
+      "default": true,
+      "description": "Always previews only — no installer, file, or manifest write ever occurs, regardless of this value."
+    }
+  },
+  "required": ["tool"]
+}

package/src/generators/add-review/schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "id": "AddReview",
+  "title": "Install the PR review workflow",
+  "type": "object",
+  "properties": {
+    "provider": {
+      "type": "string",
+      "enum": [
+        "claude",
+        "gemini",
+        "gpt",
+        "cursor"
+      ],
+      "description": "Review provider whose workflow to install. Omitted: toolkit.config.json's review.provider, else claude (no schema default — it would shadow the recorded one on a rerun)"
+    },
+    "mode": {
+      "type": "string",
+      "enum": [
+        "fast",
+        "standard",
+        "thorough"
+      ],
+      "description": "Review mode (thorough adds the over-engineering pass). Omitted: toolkit.config.json's review.mode, else standard"
+    },
+    "locale": {
+      "type": "string",
+      "enum": [
+        "ko",
+        "en"
+      ],
+      "description": "Review language. Defaults to toolkit.config.json's locale, else en"
+    },
+    "maxRounds": {
+      "type": "number",
+      "enum": [
+        1,
+        2,
+        3,
+        4,
+        5
+      ],
+      "description": "Automatic review round cap per PR (bounded 1-5). Omitted: toolkit.config.json's review.maxRounds, else 3"
+    },
+    "onConflict": {
+      "type": "string",
+      "enum": [
+        "overwrite",
+        "skip",
+        "alternate-filename"
+      ],
+      "description": "How to resolve an existing, differing workflow file. Omit to get a merge proposal (diff printed, nothing written)"
+    },
+    "dryRun": {
+      "type": "boolean",
+      "default": false,
+      "description": "Print the full generated YAML, config snippet, and effective decision without writing"
+    },
+    "packageManager": {
+      "type": "string",
+      "enum": [
+        "pnpm",
+        "npm",
+        "yarn",
+        "bun"
+      ],
+      "description": "Package manager the generated workflow installs with (default: detected, then pnpm)."
+    }
+  },
+  "required": []
+}

package/src/generators/allow-builds/schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "id": "AllowBuilds",
+  "title": "Allow dependency build scripts pnpm skipped, and run them",
+  "type": "object",
+  "properties": {
+    "packages": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "npm package names whose install scripts may run (comma-separated: --packages=sharp,@swc/core). Each must be installed (listed in pnpm-lock.yaml)."
+    },
+    "apply": {
+      "type": "boolean",
+      "default": false,
+      "description": "Allow the builds in pnpm-workspace.yaml and run `pnpm rebuild` for them. Without it (default) the generator shows what would change and writes nothing. Ignored when Nx's own --dry-run is set."
+    }
+  },
+  "required": ["packages"]
+}

package/src/generators/doctor/schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "id": "Doctor",
+  "title": "Diagnose the current Nx workspace (read-only)",
+  "type": "object",
+  "properties": {
+    "liveIntegrations": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, performs live verification (e.g. claude plugin list --json for the catalog's Claude Code plugins) instead of trusting only the recorded manifest state. Still fully read-only \u2014 no config or manifest write, no repair."
+    },
+    "json": {
+      "type": "boolean",
+      "default": false,
+      "description": "Print the machine-readable archweave/doctor-report@1 JSON to stdout instead of the console report. Still read-only \u2014 nothing is written."
+    }
+  },
+  "required": []
+}

package/src/generators/entity/schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "id": "Entity",
+  "title": "Scaffold a new FSD entity slice",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Slice name in kebab-case (e.g. \"user\") — becomes <app>/src/entities/<name>. Invalid values are refused with a report, not thrown"
+    },
+    "publicApiName": {
+      "type": "string",
+      "description": "Exported stub function name. Defaults to the camelCase form of name"
+    },
+    "segments": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Extra segments to start the slice with, each as <segment>/index.ts (e.g. ui,api). model always exists — it holds the stub. Names are by purpose: ui, api, lib, config … (components/hooks/utils/types are refused)"
+    },
+    "project": {
+      "type": "string",
+      "description": "The frontend app whose source root holds the FSD layers (run add-fsd-lite first). Omitted: the workspace's one frontend application; with more than one, the run is refused with the candidates listed"
+    },
+    "locale": {
+      "type": "string",
+      "enum": ["ko", "en"],
+      "description": "Generated content language. Defaults to toolkit.config.json's locale, else en"
+    },
+    "dryRun": {
+      "type": "boolean",
+      "default": false,
+      "description": "Print the files that would be generated without writing anything"
+    }
+  },
+  "required": ["name"]
+}