@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/audit-dev-api/cli/audit-dev-api/index.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+//
+// audit-dev-api / index.ts — Entry point.
+//
+// Detects controller / pagespec drift (DEV-API-010/011) and serves as the
+// Phase 2 gate of /ba-develop. Mirrors the contract of
+// audit-dev-frontend/cli/audit-dev-frontend/index.ts so the orchestrator
+// can chain both gates uniformly.
+//
+// Usage (read-only diagnostic, safe to run on any project):
+//
+//   npx tsx skills/development/audit-dev-api/cli/audit-dev-api/index.ts \
+//     --project-path  "<backend-root>" \
+//     --module-path   ".smartstack/ba/<APP>/<MODULE>" \
+//     --module-code   "<MODULE>" \
+//     --app-code      "<APP>" \
+//     --mode audit
+//
+// Exit code: 0 when no `err` findings, 1 otherwise.
+import { Command } from 'commander'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { validateArgs } from './validate.js'
+import { audit, reportPath } from './audit.js'
+import type { AuditDevApiOutput, Finding } from './types.js'
+
+const program = new Command()
+
+program
+  .name('audit-dev-api')
+  .description('Audit controller ↔ pagespec alignment (DEV-API-010/011). Phase 2 gate of /ba-develop.')
+  .requiredOption('--project-path <path>', 'Absolute path to the .NET backend root (src/<Ns>.Api/Controllers/**)')
+  .requiredOption('--module-path <path>', 'Absolute path to .smartstack/ba/<APP>/<MODULE>')
+  .requiredOption('--module-code <code>', 'Active module code (PRD scope)')
+  .requiredOption('--app-code <code>', 'Active application code (PRD scope)')
+  .option('--mode <mode>', 'audit | apply (apply is a stub in MVP)', 'audit')
+  .option('--rules <list>', 'Comma-separated rule codes (e.g. DEV-API-010). Default = all implemented rules')
+  .option('--no-write-report', 'Skip writing _audit/dev-api-<module>.md (stdout only)')
+  .parse(process.argv)
+
+const opts = program.opts()
+
+const raw = {
+  backendPath: opts.projectPath as string,
+  modulePath: opts.modulePath as string,
+  moduleCode: opts.moduleCode as string,
+  appCode: opts.appCode as string,
+  mode: opts.mode as string,
+  rules: typeof opts.rules === 'string'
+    ? opts.rules.split(',').map((s: string) => s.trim()).filter(Boolean)
+    : [],
+}
+const writeReport = opts.writeReport !== false
+
+const validation = validateArgs(raw)
+if (!validation.valid || !validation.args) {
+  const output: AuditDevApiOutput = {
+    success: false,
+    command: 'audit-dev-api',
+    data: { mode: (raw.mode as 'audit' | 'apply') ?? 'audit', rulesRun: [], valid: false },
+    report: null,
+    auditReport: null,
+    filesModified: [],
+    errors: validation.errors,
+    warnings: [],
+    nextSteps: ['Fix the CLI arguments and retry.'],
+  }
+  console.log(JSON.stringify(output, null, 2))
+  process.exit(1)
+}
+
+const args = validation.args
+
+async function main(): Promise<void> {
+  try {
+    const report = await audit(args)
+
+    if (writeReport) {
+      const dest = reportPath(args.backendPath, args.moduleCode)
+      await mkdir(path.dirname(dest), { recursive: true })
+      await writeFile(dest, report.markdown, 'utf8')
+    }
+
+    const valid = report.counts.errors === 0
+    const rulesRun = args.rules.length > 0 ? args.rules : Object.keys(report.byRule)
+
+    const stripped = report.findings.map((f: Finding) => ({
+      dimension: f.dimension,
+      code: f.code,
+      severity: f.severity,
+      label: f.label,
+      params: f.params,
+      solution: f.solution,
+      fixSkill: f.fixSkill,
+      fixPhaseKey: f.fixPhaseKey,
+    }))
+
+    const nextSteps: string[] = []
+    if (report.counts.errors > 0) {
+      nextSteps.push(`${report.counts.errors} ERROR finding(s) — blocking Phase 2 gate of /ba-develop.`)
+      nextSteps.push('Re-run /ba-develop after fixing the pagespec ↔ controller drift listed above.')
+    }
+
+    const output: AuditDevApiOutput = {
+      success: true,
+      command: 'audit-dev-api',
+      data: { mode: args.mode, rulesRun, valid },
+      report,
+      auditReport: {
+        scope: 'devApi',
+        applicationCode: args.appCode,
+        moduleCode: args.moduleCode,
+        findings: stripped,
+      },
+      filesModified: [],
+      errors: [],
+      warnings: [],
+      nextSteps,
+    }
+    console.log(JSON.stringify(output, null, 2))
+    process.exit(valid ? 0 : 1)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    const output: AuditDevApiOutput = {
+      success: false,
+      command: 'audit-dev-api',
+      data: { mode: args.mode, rulesRun: [], valid: false },
+      report: null,
+      auditReport: null,
+      filesModified: [],
+      errors: [`Unexpected error: ${message}`],
+      warnings: [],
+      nextSteps: ['Review the error and retry.'],
+    }
+    console.log(JSON.stringify(output, null, 2))
+    process.exit(1)
+  }
+}
+
+void main()

package/templates/skills/development/audit-dev-api/cli/audit-dev-api/types.ts

@@ -0,0 +1,158 @@
+/**
+ * audit-dev-api / types.ts — CLI args + finding + report shapes.
+ *
+ * MVP scope: this CLI implements the pagespec ↔ controller cross-check rules
+ * (DEV-API-010 / DEV-API-011) only — those that need deterministic execution
+ * because they serve as the Phase 2 gate of `/ba-develop`. The other rules
+ * (DEV-API-001..009) remain conversational (Claude reads / greps via the
+ * skill SKILL.md verbatim).
+ *
+ * Output envelope shape mirrors `audit-dev-frontend/cli/audit-dev-frontend/types.ts`
+ * so the Studio audit-reports UI can render both audits with the same renderer.
+ */
+import { z } from 'zod'
+
+export const AuditDevApiModeSchema = z.enum(['audit', 'apply'])
+export type AuditDevApiMode = z.infer<typeof AuditDevApiModeSchema>
+
+export const AuditDevApiArgsSchema = z.object({
+  /** Absolute path to the .NET backend root (holds src/<Ns>.Api/Controllers/**). */
+  backendPath: z.string().min(1),
+  /**
+   * Absolute path to the module folder inside `.smartstack/ba/<APP>/<MODULE>`.
+   * The CLI loads every `pagespecs/*.md` directly under this folder.
+   */
+  modulePath: z.string().min(1),
+  /** `audit` = report only ; `apply` is a stub for parity with frontend (no-op in MVP). */
+  mode: AuditDevApiModeSchema.default('audit'),
+  /** Active module code (PRD scope). */
+  moduleCode: z.string().min(1),
+  /** Active application code (PRD scope). */
+  appCode: z.string().min(1),
+  /** Subset of rule codes to run (e.g. ['DEV-API-010']). Empty = all implemented rules. */
+  rules: z.array(z.string()).default([]),
+})
+
+export type AuditDevApiArgs = z.infer<typeof AuditDevApiArgsSchema>
+
+// ─── Finding (mirrors audit-dev-frontend shape) ──────────────────────────
+
+export type Severity = 'err' | 'warn' | 'ok'
+
+export interface Finding {
+  /** Always 'devApi' for this skill. */
+  dimension: 'devApi'
+  /** Rule code, e.g. 'DEV-API-010'. */
+  code: string
+  severity: Severity
+  /** Display label, e.g. 'DEV_API_010_err'. */
+  label: string
+  /** Rule-specific data (rendered into the solution / UI). */
+  params: Record<string, unknown>
+  /** Mandatory on err/warn — user-facing remediation. */
+  solution: string
+  /** Optional skill name to delegate the fix to. */
+  fixSkill?: string
+  /** Optional phase key to re-run. */
+  fixPhaseKey?: string
+  /** Optional file path (relative to backendPath) for orchestrator UI navigation. */
+  file?: string
+}
+
+// ─── Internal inventory shapes ───────────────────────────────────────────
+
+/** One pagespec action of `kind:"api"` after normalisation. */
+export interface PageActionEntry {
+  file: string
+  entity: string
+  module: string
+  section: string
+  code: string
+  /** kebab-case URL segment — the source of truth. */
+  endpoint: string
+  httpMethod: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  scope: 'row' | 'bulk' | 'header'
+  ucReference?: string
+}
+
+/** A `[HttpVerb("...")]` declaration on a `*Controller.cs`. */
+export interface ControllerEndpointEntry {
+  /** Lowercase verb: `get` / `post` / `put` / `patch` / `delete`. */
+  verb: string
+  /** Route path relative to the controller mount, normalised. */
+  routePath: string
+  /** Controller file path relative to backendPath. */
+  file: string
+  /** Inferred entity (from `I<Entity>Service` field, fallback singularize(filename)). */
+  entity: string
+  /** Strata: 'integration' (under Controllers/{Module}/) or 'screens' (under Controllers/{Module}/Screens/). */
+  stratum: 'integration' | 'screens'
+  /** Class-level mount route (from [Route(...)] on the class). Used to disambiguate
+   *  shared verb+path pairs across strata that share an entity. */
+  classRoute: string
+  /** Injected service interface name (e.g. "IOpportunityService"). Used by DEV-API-014
+   *  to detect cross-strata service mismatch. */
+  injectedService: string | null
+}
+
+/** One pagespec read by the screen-driven matcher (DEV-API-012). Records the
+ *  view + the entity so the rule can verify a matching endpoint exists on
+ *  the corresponding `{EntityPlural}ScreenController.cs`. */
+export interface PageScreenEntry {
+  file: string
+  entity: string
+  module: string
+  section: string
+  view: 'list' | 'detail' | 'form' | 'dashboard' | 'kanban' | 'card' | 'app-home' | 'module-home' | 'section-home'
+  screenCode: string
+}
+
+/** A `// TODO[SCREEN-<screenCode>]:` marker found in a screen controller (DEV-API-013). */
+export interface ScreenTodoEntry {
+  file: string
+  line: number
+  marker: string
+}
+
+// ─── Reports ─────────────────────────────────────────────────────────────
+
+export interface AuditReport {
+  scope: 'devApi'
+  applicationCode: string
+  moduleCode: string
+  modulePath: string
+  backendPath: string
+  filesInspected: number
+  findings: Finding[]
+  counts: { errors: number; warnings: number; oks: number }
+  byRule: Record<string, number>
+  /** Markdown rendering, written to disk and embedded in stdout when requested. */
+  markdown: string
+}
+
+export interface AuditDevApiOutput {
+  success: boolean
+  command: 'audit-dev-api'
+  data: {
+    mode: AuditDevApiMode
+    rulesRun: string[]
+    valid: boolean
+  }
+  report: AuditReport | null
+  auditReport: {
+    scope: 'devApi'
+    applicationCode: string
+    moduleCode: string
+    findings: Array<Pick<Finding, 'dimension' | 'code' | 'severity' | 'label' | 'params' | 'solution' | 'fixSkill' | 'fixPhaseKey'>>
+  } | null
+  filesModified: string[]
+  errors: string[]
+  warnings: string[]
+  nextSteps: string[]
+}
+
+export interface ArgsValidationResult {
+  valid: boolean
+  args: AuditDevApiArgs | null
+  errors: string[]
+}

package/templates/skills/development/audit-dev-api/cli/audit-dev-api/validate.ts

@@ -0,0 +1,45 @@
+/**
+ * audit-dev-api / validate.ts — Args validation (Zod + filesystem sanity).
+ */
+import { existsSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { AuditDevApiArgsSchema, type ArgsValidationResult } from './types.js'
+
+export function validateArgs(raw: unknown): ArgsValidationResult {
+  const parsed = AuditDevApiArgsSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      valid: false,
+      args: null,
+      errors: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+    }
+  }
+
+  const args = parsed.data
+  const errors: string[] = []
+
+  // backendPath must exist as a directory.
+  const beAbs = path.resolve(args.backendPath)
+  if (!existsSync(beAbs)) {
+    errors.push(`backendPath does not exist: ${beAbs}`)
+  } else if (!statSync(beAbs).isDirectory()) {
+    errors.push(`backendPath is not a directory: ${beAbs}`)
+  }
+
+  // modulePath must exist as a directory.
+  const mpAbs = path.resolve(args.modulePath)
+  if (!existsSync(mpAbs)) {
+    errors.push(`modulePath does not exist: ${mpAbs}`)
+  } else if (!statSync(mpAbs).isDirectory()) {
+    errors.push(`modulePath is not a directory: ${mpAbs}`)
+  }
+
+  // Rule codes must look like DEV-API-NNN.
+  for (const ruleId of args.rules) {
+    if (!/^DEV-API-\d{3}$/.test(ruleId)) {
+      errors.push(`rule id "${ruleId}" must match /^DEV-API-\\d{3}$/ (e.g. "DEV-API-010")`)
+    }
+  }
+
+  return { valid: errors.length === 0, args, errors }
+}

package/templates/skills/development/audit-dev-core/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: audit-dev-core
+description: Audit code generated by Phase 0 (Core Foundation Seed) — every PRD module must have nav + roles + permissions in the 5 Core providers, DI registration must be in place, and the providers must be deterministic (no hand-edits).
+group: D
+phase: devCore
+kind: audit
+audit_only: true
+section_label: 'AUDIT-DEV-CORE (rules to apply against the 5 Core/*SeedDataProvider.cs files generated by scaffold-core-seed)'
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# audit-dev-core — Phase 0 Code-vs-PRD Audit
+
+## Context
+
+You are auditing the output of Phase 0 (Core Foundation Seed) of
+`ba-develop`. This phase invokes the deterministic
+`scaffold-core-seed` CLI to write 5 `IClientSeedDataProvider` classes
+under `src/{AppCode}.Infrastructure/Persistence/Seeding/Core/`:
+
+- `CoreNavigationSeedDataProvider.cs` — Application + every Module + every Section + every Resource
+- `CoreRolesSeedDataProvider.cs` — One Role per actor × applicationCode
+- `CorePermissionsSeedDataProvider.cs` — One NavigationPermission per `structured.permissions[]`
+- `CoreRolePermissionsSeedDataProvider.cs` — Role → permission mappings
+- `CoreTestUsersSeedDataProvider.cs` — Dev test users (gated by `IHostEnvironment.IsDevelopment()`)
+
+You receive in the system prompt:
+
+- `--- BA MODULES (expected) ---` — Markdown listing every module code declared in the BA tables for the active analysis (the `coreExpectation.modules` set the runtime gate uses).
+- `--- BA APPLICATION CODE ---` — the lowercase application code (e.g. `crm`).
+- `--- PROJECT INVENTORY (core) ---` — deterministic scan listing every existing `Core/*SeedDataProvider.cs` file path.
+- `--- FILES TOUCHED THIS PHASE ---` — files modified during the current run.
+
+You may use `Read` / `Glob` / `Grep` on the project to verify rule checks.
+**No `Edit` / `Write` / `Bash`** — you are read-only.
+
+Apply every rule below across the whole app scope. Emit `ok` findings for
+passing rules so the UI shows green checks. Emit `err` findings only when
+the spec is unambiguous and the code is clearly wrong (missing module nav,
+empty roles, < 2 permissions per module). Use `warn` for optional artefacts
+(missing test users, DI marker block formatting drift) that the user should
+review but won't block by themselves.
+
+## Rules
+
+### DEV-CORE-001 — All 5 Core providers exist
+- **Severity**: err (if any of the 5 missing), ok (if all present)
+- Check: under `src/{AppCode}.Infrastructure/Persistence/Seeding/Core/`,
+  the 5 files must be present:
+  - `CoreNavigationSeedDataProvider.cs`
+  - `CoreRolesSeedDataProvider.cs`
+  - `CorePermissionsSeedDataProvider.cs`
+  - `CoreRolePermissionsSeedDataProvider.cs`
+  - `CoreTestUsersSeedDataProvider.cs`
+- **ok**: label=`DEV_CORE_001_ok`, params=`{ count: 5 }`
+- **err**: label=`DEV_CORE_001_err`, params=`{ missing: "<comma-separated file names>" }`
+- **fixSkill**: `backend-core-seed`, **fixPhaseKey**: `core`
+- **solution** (mandatory on err): "Re-run Phase 0. Invoke
+  `scaffold-core-seed --spec-file <path> --outdir <project>` with the
+  spec file built by the orchestrator. Do NOT hand-edit the providers."
+
+### DEV-CORE-002 — Every BA module appears in CoreNavigationSeedDataProvider
+- **Severity**: err (if any module missing nav), ok (if all covered)
+- Check: for each module code in `--- BA MODULES (expected) ---`,
+  `Grep` `CoreNavigationSeedDataProvider.cs` for a line matching
+  `NavigationModule.Create\s*\(\s*[^)]*code\s*:\s*"<moduleCode>"`.
+  This is the regression that the Budget-empty bug exhibited in
+  TestV2/ba-002: 9 entities + 2 controllers but `SeedNavigationAsync`
+  returned `Task.CompletedTask`.
+- **ok**: label=`DEV_CORE_002_ok`, params=`{ count: <number> }`
+- **err**: label=`DEV_CORE_002_err`, params=`{ missing: "<comma-separated module codes>" }`
+- **fixSkill**: `backend-core-seed`, **fixPhaseKey**: `core`
+- **solution** (mandatory on err): "The CoreSeedSpec built upstream is
+  missing these modules. Verify the BA `applications/modules` tables
+  include them, then rebuild the spec and re-run scaffold-core-seed."
+
+### DEV-CORE-003 — At least one role for the application
+- **Severity**: err (if no roles), ok (if ≥ 1 role)
+- Check: `Grep` `CoreRolesSeedDataProvider.cs` for a line matching
+  `Role\.Create\s*\([^)]*<PascalApplicationCode>ApplicationId`. Without
+  any role, every login resolves to zero permissions.
+- **ok**: label=`DEV_CORE_003_ok`, params=`{ count: <number> }`
+- **err**: label=`DEV_CORE_003_err`, params=`{ applicationCode: "<value>" }`
+- **fixSkill**: `backend-core-seed`, **fixPhaseKey**: `core`
+- **solution** (mandatory on err): "The BA `actors` table for this
+  analysis is empty. Run `create-actors` to declare at least one actor
+  per application before re-running Phase 0."
+
+### DEV-CORE-004 — Every BA module has ≥ 2 permissions
+- **Severity**: err (if any module < 2 permissions), ok (if all ≥ 2)
+- Check: `Read` `CorePermissionsSeedDataProvider.cs` and parse the
+  permission tuples `("{app}.{module}.{section}.{action}", "...", "...")`.
+  Group by `module` segment (the second `.` part of the path). Each
+  module declared in `--- BA MODULES (expected) ---` must have ≥ 2
+  permission rows (access + read floor).
+- **ok**: label=`DEV_CORE_004_ok`
+- **err**: label=`DEV_CORE_004_err`, params=`{ underCovered: "<module:count list>" }`
+- **fixSkill**: `create-rbac`, **fixPhaseKey**: `permissions`
+- **solution** (mandatory on err): "Re-run `create-rbac` for the
+  under-covered modules. Each module needs at minimum the `access` and
+  `read` permissions on its first section. Then rebuild the CoreSeedSpec
+  and re-run Phase 0."
+
+### DEV-CORE-005 — DI registration block present and well-formed
+- **Severity**: err (if no DI block), warn (if marker block is malformed), ok (if 5 lines between markers)
+- Check: locate `DependencyInjection.cs` under `src/{AppCode}.Infrastructure/`
+  (or `ServiceCollectionExtensions.cs` / `*Module.cs`). `Grep` for the
+  literal markers `<<< CORE-SEED-DI BEGIN >>>` and `<<< CORE-SEED-DI END >>>`.
+  Between them, count lines matching
+  `services\.AddScoped<IClientSeedDataProvider,\s*Core\w+SeedDataProvider>\(\)`.
+  - 5 lines → ok
+  - 1-4 lines → warn (manual edit between markers)
+  - 0 lines or no markers → err
+- **ok**: label=`DEV_CORE_005_ok`
+- **warn**: label=`DEV_CORE_005_warn`, params=`{ found: <number> }`
+- **err**: label=`DEV_CORE_005_err`
+- **fixSkill**: `backend-core-seed`, **fixPhaseKey**: `core`
+- **solution** (mandatory on err): "Re-run scaffold-core-seed. The CLI
+  patches DependencyInjection.cs idempotently between
+  `<<< CORE-SEED-DI BEGIN/END >>>` markers. Without the registrations,
+  the providers compile but never run at startup."
+
+### DEV-CORE-006 — Test users present (one per role)
+- **Severity**: warn (if zero or < roles count), ok (if at least one)
+- Check: `Read` `CoreTestUsersSeedDataProvider.cs` and count
+  `EnsureTestUserAsync` calls. Compare against role count in
+  `CoreRolesSeedDataProvider.cs`. Phase 5 UI tests need at least one
+  user per role to validate RBAC; missing users surface as 401s in
+  test runs.
+- **ok**: label=`DEV_CORE_006_ok`
+- **warn**: label=`DEV_CORE_006_warn`, params=`{ users: <number>, roles: <number> }`
+- **fixSkill**: `backend-core-seed`, **fixPhaseKey**: `core`
+- **solution** (mandatory on warn): "The CoreSeedSpec.testUsers[] is
+  short. Add one entry per actor (default: emailLocalPart = roleCode)
+  and re-run scaffold-core-seed."
+
+### DEV-CORE-007 — Providers are deterministic (no hand-edits)
+- **Severity**: warn (if any provider modified outside the documented
+  shape), ok (if pristine)
+- Check: each Core provider should contain ONLY the methods documented
+  in the SKILL (`SeedNavigationAsync` / `SeedRolesAsync` /
+  `SeedPermissionsAsync` / `SeedRolePermissionsAsync`) and a single
+  `Order` property. `Grep` for any extra public method or property
+  declaration; warn if found. Hand-edits will be lost on the next
+  Phase 0 re-run.
+- **ok**: label=`DEV_CORE_007_ok`
+- **warn**: label=`DEV_CORE_007_warn`, params=`{ files: "<file:extra-members list>" }`
+- **solution** (mandatory on warn): "Move custom logic out of the Core
+  providers into a SEPARATE module-scoped seed under
+  `Persistence/Seeding/Modules/{ModuleCode}/`. The Core providers are
+  regenerated on every Phase 0 run; any addition there will disappear."
+
+## Output
+
+Emit EXACTLY ONE JSON code block matching the standard `auditReport`
+envelope. Set `dimension` to `devCore` on every finding. Include one
+`ok` finding per passing rule (so the UI lights up green) and one
+finding per failing rule.
+
+```json
+{
+  "auditReport": {
+    "scope": "devCore",
+    "applicationCode": "<from BA APPLICATION CODE>",
+    "moduleCode": null,
+    "findings": [
+      {
+        "dimension": "devCore",
+        "code": "DEV-CORE-002",
+        "severity": "err",
+        "label": "DEV_CORE_002_err",
+        "params": { "missing": "budgeting" },
+        "solution": "The CoreSeedSpec built upstream is missing this module. Verify BA tables and rebuild.",
+        "fixSkill": "backend-core-seed",
+        "fixPhaseKey": "core"
+      }
+    ]
+  }
+}
+```
+
+Stop immediately after the JSON block. Do not narrate.