gswd 0.1.0

package/lib/specify-roles.ts

@@ -0,0 +1,122 @@
+/**
+ * GSWD Specify Roles Module — Roles & permissions checkpoint
+ *
+ * Collects roles and permissions from the founder before journey mapping.
+ * In --auto mode, returns sensible defaults (single admin for v1 MVP).
+ *
+ * Schema: GSWD_SPEC.md Section 8.3 step 1
+ */
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface Role {
+  /** Role name (e.g., 'admin', 'viewer') */
+  name: string;
+  /** What this role can do */
+  description: string;
+  /** High-level permission descriptions */
+  permissions: string[];
+}
+
+export interface RolesConfig {
+  /** Defined roles */
+  roles: Role[];
+  /** Permission model type */
+  permissionModel: 'simple' | 'rbac' | 'abac';
+  /** Additional notes about the roles setup */
+  notes: string;
+}
+
+// ─── Default Configuration ───────────────────────────────────────────────────
+
+/**
+ * Sensible v1 MVP default: single admin role with full permissions.
+ */
+export function defaultRolesConfig(): RolesConfig {
+  return {
+    roles: [
+      {
+        name: 'admin',
+        description: 'Full access to all features and settings',
+        permissions: ['create', 'read', 'update', 'delete', 'manage_settings'],
+      },
+    ],
+    permissionModel: 'simple',
+    notes: 'Single admin role for v1 MVP — expand when multi-user is needed',
+  };
+}
+
+// ─── Roles Collection ────────────────────────────────────────────────────────
+
+export interface CollectRolesOptions {
+  /** If true, skip checkpoint and return defaults */
+  auto: boolean;
+}
+
+/**
+ * Collect roles & permissions configuration.
+ *
+ * In auto mode: returns default config immediately (no interaction).
+ * In interactive mode: would render checkpoint box for user input.
+ * (Interactive mode deferred to Phase 6 — auto is the primary path for now.)
+ */
+export async function collectRoles(options: CollectRolesOptions): Promise<RolesConfig> {
+  if (options.auto) {
+    return defaultRolesConfig();
+  }
+
+  // Interactive mode: return default with note about deferral
+  // Full interactive collection deferred to Phase 6 (Bootstrap + Auto)
+  return {
+    ...defaultRolesConfig(),
+    notes: 'Deferred — using admin-only for now',
+  };
+}
+
+// ─── Formatting ──────────────────────────────────────────────────────────────
+
+/**
+ * Format RolesConfig for insertion into SPEC.md "## Roles & Permissions" section.
+ *
+ * Produces a markdown table of roles with permissions.
+ */
+export function formatRolesForSpec(config: RolesConfig): string {
+  const lines: string[] = [];
+
+  // Permission model description
+  lines.push(`**Permission Model:** ${formatPermissionModel(config.permissionModel)}`);
+  lines.push('');
+
+  // Roles table
+  lines.push('| Role | Description | Permissions |');
+  lines.push('|------|-------------|-------------|');
+
+  for (const role of config.roles) {
+    const perms = role.permissions.join(', ');
+    lines.push(`| ${role.name} | ${role.description} | ${perms} |`);
+  }
+
+  // Notes
+  if (config.notes) {
+    lines.push('');
+    lines.push(`> ${config.notes}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format permission model name for display.
+ */
+function formatPermissionModel(model: 'simple' | 'rbac' | 'abac'): string {
+  switch (model) {
+    case 'simple':
+      return 'Simple (single role or flat permissions)';
+    case 'rbac':
+      return 'RBAC (Role-Based Access Control)';
+    case 'abac':
+      return 'ABAC (Attribute-Based Access Control)';
+    default:
+      return model;
+  }
+}