Merge pull request #204 from tractr/next

feat: add CLI flags for policy management

Author: EdouardDem

.cursor/rules/project-overview.mdc

@@ -3,3 +3,4 @@
 node_modules/
 dist/
 .env
+.claude/

.gitignore

@@ -0,0 +1,56 @@
+# Repository Overview
+
+Monorepo providing a Directus endpoint extension, a CLI for syncing schema/data, an e2e test harness, and documentation.
+
+## High-level flow
+
+- The CLI connects to a Directus instance and orchestrates pull/diff/push/seed/specs operations.
+- The API extension exposes endpoints used by the CLI for SyncID↔LocalID mapping and helpers.
+- E2E tests spin up a Directus server locally and validate the full flow (CLI + extension) end-to-end.
+
+## Packages
+
+### `packages/api` — Directus endpoint extension
+- Exposes `/directus-extension-sync` routes for SyncID mapping and helpers (e.g., permissions deduplication).
+- Uses Express-style router via Directus SDK, Zod validation, and Knex for a small mapping table.
+- Key files: `src/index.ts` (routes), `src/api/*` (middleware/helpers), `src/database/*` (IdMapper, Permissions).
+
+### `packages/cli` — Directus Sync CLI
+- Orchestrates schema and system collections synchronization; supports seed data and API specifications dump.
+- Structure:
+  - `services/config`: options resolution (defaults → config file → CLI flags), Zod validation.
+  - `services/collections`: per-collection pull/diff/push with id mapping.
+  - `services/snapshot`: schema snapshot pull/diff/push.
+  - `services/seed`: seed files loader/differ/pusher with dynamic id mapping.
+  - `services/specifications`: GraphQL/OpenAPI dump.
+  - `services/*-client.ts`: Directus SDK client, extension HTTP client, health checks.
+  - `commands` + `program.ts`: command wiring and execution.
+- Technologies: TypeScript, typedi (DI), pino (logging), Zod, @directus/sdk.
+
+### `packages/e2e` — End-to-end tests
+- Jasmine-based tests against a locally started Directus server.
+- Helpers start the server, create a Directus client, and run CLI commands programmatically, asserting logs and state.
+- See `spec/helpers/sdk/*`, `spec/pull-diff-push/*`.
+
+### `website` — Documentation
+- Docusaurus site documenting installation, features, and how the sync works.
+- When updating the CLI help outputs, build the whole project (`npm run build` at the root), then run `npm run update-help-outputs` to update the help outputs in the website.
+
+## Other top-level
+
+- `docker/`: build/publish scripts and Dockerfile for distributing Directus with the extension.
+- `lerna.json`: monorepo management.
+- `DOCUMENTATION.md`, `CHANGELOG.md`, etc.: project docs and changelog.
+
+## Conventions
+
+- TypeScript across packages; DI via `typedi`; logging via `pino`; validation via `zod`.
+- Keep business logic in services; commands/endpoints orchestrate only.
+- Follow per-package rules under `.cursor/rules/` for detailed guidance.
+
+## Checks
+
+- Before committing, run `npm run lint` to run the linter and fix any issues.
+- Before pushing, run `npm run test` to run the tests and fix any issues.
+- Before pushing, run `npm run build` to build the project and fix any issues.
+- Before pushing, run `npm run docs:update` to update the help outputs in the website.

CLAUDE.md

@@ -26,6 +26,9 @@ function cleanProgramOptions(programOptions: Record<string, unknown>) {
  * Remove some default values from the command options that overrides the config file
  */
 function cleanCommandOptions(commandOptions: Record<string, unknown>) {
+  if (commandOptions.collections === true) {
+    delete commandOptions.collections;
+  }
   if (commandOptions.snapshot === true) {
     delete commandOptions.snapshot;
   }
@@ -35,6 +38,9 @@ function cleanCommandOptions(commandOptions: Record<string, unknown>) {
   if (commandOptions.specs === true) {
     delete commandOptions.specs;
   }
+  if (commandOptions.syncPolicyRoles === true) {
+    delete commandOptions.syncPolicyRoles;
+  }
   return commandOptions;
 }
 
@@ -139,6 +145,10 @@ export function createProgram() {
     '--no-collections',
     `should pull and push the collections (default "${DefaultConfig.collections}")`,
   );
+  const noSyncPolicyRolesOption = new Option(
+    '--no-sync-policy-roles',
+    `should sync the role ↔ policy attachments (directus_access entries linking roles and policies). Disable to leave existing role-policy assignments on the target untouched (default "${DefaultConfig.syncPolicyRoles}")`,
+  );
   const preserveIdsOption = new Option(
     '--preserve-ids <preserveIds>',
     `comma separated list of collections that preserve their original ids (default to none). Use "*" or "all" to preserve all ids, if applicable.`,
@@ -194,6 +204,7 @@ export function createProgram() {
     .addOption(excludeCollectionsOption)
     .addOption(onlyCollectionsOption)
     .addOption(noCollectionsOption)
+    .addOption(noSyncPolicyRolesOption)
     .addOption(preserveIdsOption)
     .addOption(snapshotPathOption)
     .addOption(noSnapshotOption)
@@ -212,6 +223,7 @@ export function createProgram() {
     .addOption(excludeCollectionsOption)
     .addOption(onlyCollectionsOption)
     .addOption(noCollectionsOption)
+    .addOption(noSyncPolicyRolesOption)
     .addOption(snapshotPathOption)
     .addOption(noSnapshotOption)
     .addOption(noSplitOption)
@@ -227,6 +239,7 @@ export function createProgram() {
     .addOption(excludeCollectionsOption)
     .addOption(onlyCollectionsOption)
     .addOption(noCollectionsOption)
+    .addOption(noSyncPolicyRolesOption)
     .addOption(preserveIdsOption)
     .addOption(snapshotPathOption)
     .addOption(noSnapshotOption)

packages/cli/src/lib/program.ts

@@ -17,10 +17,15 @@ import {
 import { LoggerService } from '../../logger';
 import { POLICIES_COLLECTION } from './constants';
 import deepmerge from 'deepmerge';
+import { ConfigService } from '../../config';
 
 @Service()
 export class PoliciesDataClient extends DataClient<DirectusPolicy> {
-  constructor(loggerService: LoggerService, migrationClient: MigrationClient) {
+  constructor(
+    loggerService: LoggerService,
+    migrationClient: MigrationClient,
+    protected readonly config: ConfigService,
+  ) {
     super(loggerService.getChild(POLICIES_COLLECTION), migrationClient);
   }
 
@@ -33,9 +38,15 @@ export class PoliciesDataClient extends DataClient<DirectusPolicy> {
   }
 
   protected getQueryCommand(query: Query<DirectusPolicy>) {
+    // When role-policy attachments sync is disabled, omit the roles fields
+    // entirely from the dump so they are neither tracked nor diffed.
+    // See https://github.com/tractr/directus-sync/issues/199
+    const extraFields = this.config.shouldSyncPolicyRoles()
+      ? ['*', 'roles.role', 'roles.sort']
+      : ['*'];
     return readPolicies(
       deepmerge<Query<BaseDirectusPolicy>>(query, {
-        fields: ['*', 'roles.role', 'roles.sort'],
+        fields: extraFields,
       }),
     );
   }
@@ -44,6 +55,13 @@ export class PoliciesDataClient extends DataClient<DirectusPolicy> {
     itemId: string,
     diffItem: Partial<WithoutIdAndSyncId<DirectusPolicy>>,
   ) {
+    // When role-policy attachments sync is disabled, drop the roles diff
+    // entirely so existing attachments on the target are left untouched.
+    // See https://github.com/tractr/directus-sync/issues/199
+    if (!this.config.shouldSyncPolicyRoles() && diffItem.roles) {
+      const { roles: _ignored, ...rest } = diffItem as Partial<DirectusPolicy>;
+      diffItem = rest as Partial<WithoutIdAndSyncId<DirectusPolicy>>;
+    }
     // Explicit update of the roles field (many-to-many relation)
     // Issue : https://github.com/tractr/directus-sync/issues/148
     if (diffItem.roles) {

packages/cli/src/lib/services/collections/policies/data-client.ts

@@ -4,18 +4,27 @@ import { LoggerService } from '../../logger';
 import { POLICIES_COLLECTION } from './constants';
 import { DirectusPolicy } from './interfaces';
 import { RolesIdMapperClient } from '../roles';
+import { ConfigService } from '../../config';
 
 @Service()
 export class PoliciesDataMapper extends DataMapper<DirectusPolicy> {
-  protected fieldsToIgnore: Field<DirectusPolicy>[] = ['users', 'permissions'];
-  protected idMappers: IdMappers<DirectusPolicy> = {
-    roles: {
-      // @ts-expect-error TODO: Bad SDK Typing
-      role: Container.get(RolesIdMapperClient),
-    },
-  };
+  protected fieldsToIgnore: Field<DirectusPolicy>[];
+  protected idMappers: IdMappers<DirectusPolicy>;
 
-  constructor(loggerService: LoggerService) {
+  constructor(loggerService: LoggerService, config: ConfigService) {
     super(loggerService.getChild(POLICIES_COLLECTION));
+
+    if (config.shouldSyncPolicyRoles()) {
+      this.fieldsToIgnore = ['users', 'permissions'];
+      this.idMappers = {
+        roles: {
+          // @ts-expect-error TODO: Bad SDK Typing
+          role: Container.get(RolesIdMapperClient),
+        },
+      };
+    } else {
+      this.fieldsToIgnore = ['users', 'permissions', 'roles'];
+      this.idMappers = {};
+    }
   }
 }

packages/cli/src/lib/services/collections/policies/data-mapper.ts

@@ -177,6 +177,11 @@ export class ConfigService {
     return list.filter((collection) => !exclude.includes(collection));
   }
 
+  @Cacheable()
+  shouldSyncPolicyRoles() {
+    return this.requireOptions('syncPolicyRoles');
+  }
+
   @Cacheable()
   shouldPreserveIds(collection: CollectionPreservableIdName) {
     const preserveIds = this.requireOptions('preserveIds');

packages/cli/src/lib/services/config/config.ts

@@ -17,6 +17,7 @@ export const DefaultConfig: Pick<
   | 'excludeCollections'
   | 'onlyCollections'
   | 'collections'
+  | 'syncPolicyRoles'
   | 'preserveIds'
   | 'snapshotPath'
   | 'snapshot'
@@ -42,6 +43,7 @@ export const DefaultConfig: Pick<
   excludeCollections: [],
   onlyCollections: [],
   collections: true,
+  syncPolicyRoles: true,
   preserveIds: [],
   // Snapshot
   snapshotPath: 'snapshot',

packages/cli/src/lib/services/config/default-config.ts

@@ -106,6 +106,7 @@ export const OptionsFields = {
   excludeCollections: z.array(CollectionEnum).optional(),
   onlyCollections: z.array(CollectionEnum).optional(),
   collections: z.boolean(),
+  syncPolicyRoles: z.boolean(),
   preserveIds: z.union([
     z.array(CollectionPreservableIdEnum).optional(),
     z.enum(['all', '*']),
@@ -162,6 +163,7 @@ export const ConfigFileOptionsSchema = z.object({
   excludeCollections: OptionsFields.excludeCollections.optional(),
   onlyCollections: OptionsFields.onlyCollections.optional(),
   collections: OptionsFields.collections.optional(),
+  syncPolicyRoles: OptionsFields.syncPolicyRoles.optional(),
   preserveIds: OptionsFields.preserveIds.optional(),
   // Snapshot config
   snapshotPath: OptionsFields.snapshotPath.optional(),

packages/cli/src/lib/services/config/schema.ts

@@ -0,0 +1,3 @@
+module.exports = {
+  collections: false,
+};