@team-codeme/crud-forge 0.0.0-stage → 1.0.1

package/src/generator/access-control-tools.js

@@ -0,0 +1,334 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+
+const PACK_REL = 'src/app/domains/admin/modules/apps/shared/access-control-tools';
+
+/**
+ * Ship PMB-style access-control-tools into every Fuse app so developers can
+ * stamp SCREEN / accessCtrl / QA ids on custom pages after generate.
+ */
+function applyAccessControlToolsPack({ outputDir, config, writeOrPreview }) {
+  if (!config.fuse?.enabled) {
+    return { applied: false, files: [] };
+  }
+
+  const srcRoot = path.join(__dirname, '..', 'templates', 'fuse-packs', 'access-control-tools');
+  const destRoot = path.join(outputDir, PACK_REL);
+  const files = [];
+
+  const copyTree = (fromDir, toDir) => {
+    if (!fs.existsSync(fromDir)) return;
+    for (const entry of fs.readdirSync(fromDir, { withFileTypes: true })) {
+      if (entry.name === 'output' && entry.isDirectory()) {
+        const outDir = path.join(toDir, 'output');
+        const keepme = path.join(outDir, '.gitkeep');
+        if (config.dryRun) {
+          writeOrPreview(keepme, '');
+        } else {
+          fs.ensureDirSync(outDir);
+          if (!fs.existsSync(keepme)) fs.writeFileSync(keepme, '');
+        }
+        files.push(path.relative(outputDir, keepme));
+        continue;
+      }
+      const from = path.join(fromDir, entry.name);
+      const to = path.join(toDir, entry.name);
+      if (entry.isDirectory()) {
+        copyTree(from, to);
+        continue;
+      }
+      const content = fs.readFileSync(from);
+      const text = entry.name.endsWith('.sh') || entry.name.endsWith('.js') || entry.name.endsWith('.md')
+        ? content.toString('utf8')
+        : content;
+      writeOrPreview(to, typeof text === 'string' ? text : content);
+      if (!config.dryRun && entry.name === 'run.sh') {
+        try {
+          fs.chmodSync(to, 0o755);
+        } catch {
+          // best-effort executable bit
+        }
+      }
+      files.push(path.relative(outputDir, to));
+    }
+  };
+
+  copyTree(srcRoot, destRoot);
+
+  // Human + agent docs (always overwrite from pack templates written below).
+  const readme = buildReadme();
+  const agentReadme = buildAgentReadme();
+  const agentMemory = buildAgentMemory();
+  const agentsMd = `# Agents — access-control-tools\n\nRead **[AGENT_MEMORY.md](./AGENT_MEMORY.md)** before changing anything in this folder.\n\nThen: [README.md](./README.md) → dry-run → apply via \`run.sh\`.\n`;
+
+  for (const [name, body] of [
+    ['README.md', readme],
+    ['AGENT_README.md', agentReadme],
+    ['AGENT_MEMORY.md', agentMemory],
+    ['AGENTS.md', agentsMd],
+  ]) {
+    const target = path.join(destRoot, name);
+    writeOrPreview(target, body);
+    files.push(path.relative(outputDir, target));
+  }
+
+  // npm scripts on the generated Fuse package.json
+  const pkgPath = path.join(outputDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkg = fs.readJsonSync(pkgPath);
+    pkg.scripts = pkg.scripts || {};
+    const run = `bash ${PACK_REL}/run.sh`;
+    pkg.scripts['access-control:sync'] = `${run} dry-run`;
+    pkg.scripts['access-control:apply'] = `${run} apply`;
+    pkg.scripts['access-control:all'] = `${run} all`;
+    writeOrPreview(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    files.push('package.json');
+  }
+
+  return { applied: true, files, dest: PACK_REL };
+}
+
+function buildReadme() {
+  return `# Access Control & Screen Component Registry
+
+Tools for RBAC component registration and stable QA element IDs in this Fuse app.
+
+**Agent handoff:** [AGENT_MEMORY.md](./AGENT_MEMORY.md) · [AGENT_README.md](./AGENT_README.md) · [AGENTS.md](./AGENTS.md)
+
+## What this is for
+
+CRUDForge generates entity + IAM screens with \`SCREEN\`, \`accessCtrl\`, and \`data-*\` stamps already.
+Use this pack when you add **custom pages** (or hand-edit templates) and need the same id conventions + CSV registry for Keycloak permission matrices.
+
+## Scan targets
+
+Under \`src/app/domains/admin/modules/apps/\` (skips \`shared\` / \`enums\`):
+
+- \`micro-functions/\` and \`microservice/\` — entity modules
+- \`pages/\` — custom screens
+
+## ID convention
+
+\`\`\`text
+SCREEN (TS)   = nav-aligned key     e.g. micro-functions/book  |  user-management
+componentId   = {verb}[-{noun}]     e.g. create, open-filter, toggle-view, open-columns
+qaId          = qa-{screenId}__{componentId}
+accessCtrl    = SCREEN | accessCtrl: '{componentId}'
+\`\`\`
+
+Semantic verbs (source: \`lib/id-rules.js\`):
+
+| UI action        | componentId     |
+|------------------|-----------------|
+| New / Add        | \`create\`        |
+| Filters          | \`open-filter\`   |
+| Table ↔ Card     | \`toggle-view\`   |
+| Column prefs     | \`open-columns\`  |
+| View / Edit / Del| \`view\` / \`edit\` / \`delete\` |
+
+Generated entity \`SCREEN\` values stay \`{folder}/{entity}\` so they match sidebar nav ACL.
+Legacy aliases (\`new\`↔\`create\`, \`filter\`↔\`open-filter\`, …) are accepted at runtime by \`AccessControlService\`.
+
+Optional override on any control:
+
+\`\`\`html
+<button data-action="approve-request" (click)="approve()">...</button>
+\`\`\`
+
+Lock a CSV description: prefix with \`[manual] \`.
+
+## Commands
+
+From the Fuse app root (preferred: \`run.sh\`):
+
+\`\`\`bash
+# Preview only (default)
+npm run access-control:sync
+# or
+bash src/app/domains/admin/modules/apps/shared/access-control-tools/run.sh dry-run
+
+# Apply after reviewing output/sync-report.json
+npm run access-control:apply
+
+# Dry-run then apply
+npm run access-control:all
+\`\`\`
+
+Env knobs:
+
+| Var | Default | Meaning |
+|-----|---------|---------|
+| \`MODE\` | \`dry-run\` | \`dry-run\` \\| \`apply\` \\| \`all\` |
+| \`FORCE_CONTENT_IDS\` | \`false\` | \`true\` = rebuild SCREEN from heading (custom pages) |
+| \`REWRITE_IDS\` | \`true\` | Normalize legacy noisy QA / component ids on apply |
+| \`PRUNE_CSV\` | \`false\` | Drop CSV rows not rediscovered |
+
+Keep generated entity SCREEN values: leave \`FORCE_CONTENT_IDS=false\` (default).
+For custom pages with heading-based ids: \`FORCE_CONTENT_IDS=true ./run.sh apply\`.
+
+## Outputs
+
+| Path | Role |
+|------|------|
+| \`output/screen-components.csv\` | Master registry |
+| \`output/screen-navigation-map.json\` | Page → embedded SCREEN hierarchy (AST + routes + templates) |
+| \`output/sync-report.json\` | Last dry-run / apply report (includes hierarchy + duplicate resolutions) |
+| \`public/assets/screen-components.csv\` | Runtime copy for Role/User matrices |
+| \`public/assets/screen-navigation-map.json\` | Runtime hierarchy for Role Permission Matrix + AccessControlService |
+| \`../screen-components.csv\` | Shared mirror next to tools |
+
+## Files
+
+| File | Role |
+|------|------|
+| \`access-control-sync.js\` | Unified scanner (accessCtrl + QA + CSV) |
+| \`lib/id-rules.js\` | Shared ID convention + semantic action map |
+| \`lib/html-scanner.js\` | HTML tag walker / injector |
+| \`lib/ts-component-index.js\` | TypeScript AST @Component index |
+| \`lib/hierarchy-scanner.js\` | Page → embed hierarchy discovery |
+| \`run.sh\` | Preferred runner |
+| \`inject-qa-ids.js\` / \`scan-access-control.js\` | Legacy wrappers |
+
+## Custom page checklist
+
+1. Add the Angular component under \`apps/pages/…\` (or an entity folder).
+2. Put interactive controls in the template (\`button\` / \`a\` / \`mat-*\`).
+3. Run \`npm run access-control:sync\` and inspect \`output/sync-report.json\`.
+4. Apply with \`npm run access-control:apply\`.
+5. Confirm CSV rows appear in the permission matrices UI.
+6. Do **not** hand-edit generated entity templates as source of truth — change CRUDForge \`src/templates/**/*.ejs\` and regenerate.
+
+Pipe used in Fuse: \`AccessCtrlPipe\` from \`@/app/core/auth\` (template name \`accessCtrl\`).
+`;
+}
+
+function buildAgentReadme() {
+  return `# AGENT_README — access-control-tools
+
+> **Generated by \`@crudforge/cli\`** (\`crudforge generate\`).
+
+Point agents here when stamping RBAC / QA ids on this Fuse app.
+
+## Mission
+
+Keep \`SCREEN\`, \`accessCtrl\`, \`data-screen-id\` / \`data-component-id\`, and \`qa-*\` ids consistent; keep \`screen-components.csv\` in sync for Keycloak matrices.
+
+## Do
+
+1. Read [AGENT_MEMORY.md](./AGENT_MEMORY.md) then [README.md](./README.md).
+2. Prefer \`run.sh\` / \`npm run access-control:*\` — always dry-run first.
+3. Keep generated entity SCREEN as \`{micro-functions\\|microservice}/{entity}\` (\`FORCE_CONTENT_IDS=false\`).
+4. Use semantic componentIds: \`create\`, \`open-filter\`, \`toggle-view\`, \`open-columns\`, …
+5. Edit CRUDForge generator templates for entity/IAM stamps — not only the testing-area copy.
+
+## Do not
+
+- Invent CSV rows by hand unless asked (except \`[manual] \` description locks).
+- Force content ids on generated entity lists (breaks nav ACL alignment).
+- Import PMB \`ScreenCtrlPipe\` — Fuse uses \`AccessCtrlPipe\` from \`@/app/core/auth\`.
+- Commit secrets or live \`.env\` files.
+
+## Quick commands
+
+\`\`\`bash
+npm run access-control:sync
+npm run access-control:apply
+FORCE_CONTENT_IDS=true npm run access-control:apply   # custom pages only
+\`\`\`
+`;
+}
+
+function buildAgentMemory() {
+  return `# Access-control-tools — agent memory
+
+**Point a new agent here:**  
+\`src/app/domains/admin/modules/apps/shared/access-control-tools/AGENT_MEMORY.md\`
+
+Human docs: [README.md](./README.md). Pack overview: [AGENT_README.md](./AGENT_README.md).
+
+---
+
+## Mission
+
+Keep screen / button RBAC ids and QA ids consistent across the admin UI, and keep the CSV registry in sync for Keycloak matrix seeding.
+
+Scan targets: all \`modules/apps/*\` trees except \`shared\` / \`enums\` (includes \`micro-functions\`, \`microservice\`, \`pages\`).
+
+Outputs:
+
+| Path | Role |
+|------|------|
+| \`output/screen-components.csv\` | Master registry |
+| \`output/sync-report.json\` | Last report |
+| \`public/assets/screen-components.csv\` | Runtime matrices |
+| \`../screen-components.csv\` | Shared mirror |
+
+---
+
+## Preferred commands
+
+\`\`\`bash
+bash src/app/domains/admin/modules/apps/shared/access-control-tools/run.sh dry-run
+bash …/run.sh apply
+bash …/run.sh all
+\`\`\`
+
+Or npm: \`access-control:sync\` / \`access-control:apply\` / \`access-control:all\`.
+
+| Var | Default | Meaning |
+|-----|---------|---------|
+| \`MODE\` | \`dry-run\` | \`dry-run\` \\| \`apply\` \\| \`all\` |
+| \`FORCE_CONTENT_IDS\` | \`false\` | Heading-based SCREEN rewrite |
+| \`REWRITE_IDS\` | \`true\` | Normalize legacy ids on apply |
+| \`PRUNE_CSV\` | \`false\` | Drop undiscovered CSV rows |
+
+---
+
+## ID rules (source: \`lib/id-rules.js\`)
+
+\`\`\`text
+SCREEN (TS)   = unique screen key          e.g. micro-functions/book
+componentId   = {verb}[-{noun}]            e.g. create, open-filter
+qaId          = qa-{screenId}__{componentId}
+accessCtrl    = SCREEN | accessCtrl: '{componentId}'
+\`\`\`
+
+CRUDForge entity paths resolve to \`{folder}/{entity}\` (nav-aligned).  
+Custom pages may use \`FORCE_CONTENT_IDS=true\` for heading + view ids.
+
+Aliases at runtime (\`AccessControlService\`): \`new\`↔\`create\`, \`filter\`↔\`open-filter\`, \`view-mode\`↔\`toggle-view\`, \`columns\`↔\`open-columns\`.
+
+---
+
+## Sync pipeline
+
+1. Resolve provisional screen ids (prefer existing SCREEN when not forcing content ids).
+2. Soft + hard disambiguate duplicate SCREEN ids (keep primary; module/path-prefix clones).
+3. Inject HTML (\`accessCtrl\`, QA attrs) + ensure TS \`SCREEN\` / \`AccessCtrlPipe\`.
+4. Build \`screen-navigation-map.json\` via TS AST + routes + recursive templates.
+5. Merge into CSV; on \`--write\` also write \`public/assets/screen-components.csv\` + navigation map.
+
+Hierarchy never invents SCREEN ids. Sensitive actions (Delete/Approve/Reject/Finalize) stay explicit in the matrix UI.
+
+### TS injection
+
+- Prefer \`readonly SCREEN = '…'\` on the \`@Component\` class.
+- Import \`AccessCtrlPipe\` from \`@/app/core/auth\` (not PMB ScreenCtrlPipe).
+- Getter + \`@Input() screenId\` cases: update Input default, do not inject a duplicate field.
+
+---
+
+## Source of truth
+
+- Tool pack templates: CRUDForge \`src/templates/fuse-packs/access-control-tools/\`
+- Entity/IAM stamps: CRUDForge \`src/templates/angular/**/*.ejs\` + \`src/generator/auth-pack.js\`
+- Regenerate the Fuse app after generator changes; do not treat testing-area as source.
+`;
+}
+
+module.exports = {
+  applyAccessControlToolsPack,
+  PACK_REL,
+};