directus-template-cli 0.7.8 → 0.8.0

package/dist/lib/extract/extract-relations.js

@@ -2,12 +2,13 @@ import { readFields, readRelations } from '@directus/sdk';
 import { ux } from '@oclif/core';
 import { DIRECTUS_PINK } from '../constants.js';
 import { api } from '../sdk.js';
+import { includesRelation } from '../template-plan/index.js';
 import catchError from '../utils/catch-error.js';
 import writeToFile from '../utils/write-to-file.js';
 /**
  * Extract relations from the Directus instance
  */
-export default async function extractRelations(dir) {
+export default async function extractRelations(dir, plan) {
     ux.action.start(ux.colorize(DIRECTUS_PINK, 'Extracting relations'));
     try {
         const response = await api.client.request(readRelations());
@@ -16,9 +17,10 @@ export default async function extractRelations(dir) {
         const customFields = fields.filter((i) => !i.meta?.system);
         const relations = response
             // Filter out relations where the collection starts with 'directus_' && the field is not within the customFields array
-            .filter((i) => !i.collection.startsWith('directus_', 0)
-            || customFields.some((f) => f.collection === i.collection && f.field === i.field))
-            .map(i => {
+            .filter((i) => !i.collection.startsWith('directus_', 0) ||
+            customFields.some((f) => f.collection === i.collection && f.field === i.field))
+            .filter((i) => includesRelation(i.collection, i.related_collection, plan))
+            .map((i) => {
             delete i.meta.id;
             return i;
         });

package/dist/lib/extract/index.d.ts

@@ -1 +1,2 @@
-export default function extract(dir: string): Promise<{}>;
+import { type TemplatePlan } from '../template-plan/index.js';
+export default function extract(dir: string, plan?: TemplatePlan): Promise<{}>;

package/dist/lib/extract/index.js

@@ -1,5 +1,9 @@
 import { ux } from '@oclif/core';
-import fs from 'node:fs';
+import fs from 'node:fs/promises';
+import { buildTemplatePlan, writeTemplateMetadata, } from '../template-plan/index.js';
+import catchError from '../utils/catch-error.js';
+import { expandDeepPlan } from './expand-deep-plan.js';
+import { expandSchemaPlan } from './expand-schema-plan.js';
 import extractAccess from './extract-access.js';
 import { downloadAllFiles } from './extract-assets.js';
 import extractCollections from './extract-collections.js';
@@ -19,34 +23,68 @@ import extractSchema from './extract-schema.js';
 import extractSettings from './extract-settings.js';
 import extractTranslations from './extract-translations.js';
 import extractUsers from './extract-users.js';
-export default async function extract(dir) {
-    // Get the destination directory for the actual files
+export default async function extract(dir, plan = buildTemplatePlan()) {
     const destination = `${dir}/src`;
-    // Check if directory exists, if not, then create it.
-    if (!fs.existsSync(destination)) {
-        ux.stdout(`Attempting to create directory at: ${destination}`);
-        fs.mkdirSync(destination, { recursive: true });
-    }
-    await extractSchema(destination);
-    await extractCollections(destination);
-    await extractFields(destination);
-    await extractRelations(destination);
-    await extractFolders(destination);
-    await extractFiles(destination);
-    await extractUsers(destination);
-    await extractRoles(destination);
-    await extractPermissions(destination);
-    await extractPolicies(destination);
-    await extractAccess(destination);
-    await extractPresets(destination);
-    await extractTranslations(destination);
-    await extractFlows(destination);
-    await extractOperations(destination);
-    await extractDashboards(destination);
-    await extractPanels(destination);
-    await extractSettings(destination);
-    await extractExtensions(destination);
-    await extractContent(destination);
-    await downloadAllFiles(destination);
+    const schemaPlan = await expandSchemaPlan(plan);
+    const effectivePlan = await expandDeepPlan(schemaPlan);
+    try {
+        await fs.mkdir(destination, { recursive: true });
+    }
+    catch (error) {
+        catchError(error, { context: { destination }, fatal: true });
+    }
+    if (effectivePlan.components.schema) {
+        await extractSchema(destination);
+        await extractCollections(destination, effectivePlan);
+        await extractFields(destination, effectivePlan);
+        await extractRelations(destination, effectivePlan);
+    }
+    if (effectivePlan.components.files) {
+        await extractFolders(destination);
+        await extractFiles(destination);
+        await downloadAllFiles(destination);
+    }
+    if (effectivePlan.components.users || effectivePlan.components.permissions) {
+        await extractRoles(destination);
+        await extractPermissions(destination);
+        await extractPolicies(destination);
+        if (effectivePlan.components.users) {
+            await extractUsers(destination);
+        }
+        await extractAccess(destination);
+    }
+    if (effectivePlan.components.settings) {
+        await extractPresets(destination);
+        await extractTranslations(destination);
+        await extractSettings(destination);
+    }
+    if (effectivePlan.components.flows) {
+        await extractFlows(destination);
+        await extractOperations(destination);
+    }
+    if (effectivePlan.components.dashboards) {
+        await extractDashboards(destination);
+        await extractPanels(destination);
+    }
+    if (effectivePlan.components.extensions) {
+        await extractExtensions(destination);
+    }
+    const warnings = [];
+    if (effectivePlan.components.content) {
+        const contentWarnings = await extractContent(destination, effectivePlan);
+        warnings.push(...contentWarnings);
+    }
+    for (const warning of warnings) {
+        ux.warn(`Excluded relation: ${warning.collection}.${warning.field} -> ${warning.relatedCollection} (${warning.count} records)`);
+    }
+    try {
+        await writeTemplateMetadata(destination, effectivePlan, warnings);
+    }
+    catch (error) {
+        catchError(error, {
+            context: { function: 'writeTemplateMetadata' },
+            fatal: true,
+        });
+    }
     return {};
 }

package/dist/lib/init/index.d.ts

@@ -1,4 +1,5 @@
 import { type DownloadTemplateResult } from 'giget';
+import { type PackageManager } from 'nypm';
 import type { InitFlags } from '../../commands/init.js';
 export declare function init({ dir, flags }: {
     dir: string;
@@ -8,3 +9,17 @@ export declare function init({ dir, flags }: {
     frontendDir: string;
     template: DownloadTemplateResult;
 }>;
+type DependencyInstaller = (options: {
+    cwd: string;
+    packageManager?: PackageManager;
+    silent: boolean;
+}) => Promise<unknown>;
+type InstallFrontendDependenciesOptions = {
+    frontendDir: string;
+    install?: DependencyInstaller;
+    onSkip?: () => void;
+    packageManager: null | PackageManager;
+    warn?: (message: string) => void;
+};
+export declare function installFrontendDependencies({ frontendDir, install, onSkip, packageManager, warn, }: InstallFrontendDependenciesOptions): Promise<boolean>;
+export {};

package/dist/lib/init/index.js

@@ -133,21 +133,18 @@ export async function init({ dir, flags }) {
         // Install dependencies if requested
         if (flags.installDeps) {
             const s = spinner();
+            let dependenciesInstalled = true;
             s.start('Installing dependencies');
-            try {
-                if (fs.existsSync(frontendDir)) {
-                    await installDependencies({
-                        cwd: frontendDir,
-                        packageManager,
-                        silent: true,
-                    });
-                }
+            if (fs.existsSync(frontendDir)) {
+                dependenciesInstalled = await installFrontendDependencies({
+                    frontendDir,
+                    onSkip: () => s.stop('Dependency installation skipped'),
+                    packageManager,
+                });
             }
-            catch (error) {
-                ux.warn('Failed to install dependencies');
-                throw error;
+            if (dependenciesInstalled) {
+                s.stop('Dependencies installed!');
             }
-            s.stop('Dependencies installed!');
         }
         // Initialize Git repo
         if (flags.gitInit) {
@@ -165,7 +162,7 @@ export async function init({ dir, flags }) {
             : `- Complete the onboarding form at ${pinkText(directusInfo.url || 'http://localhost:8055')} to create your admin account. \n`;
         const frontendText = flags.frontend ? `- To start the frontend, run ${pinkText(`cd ${flags.frontend}`)} and then ${pinkText(`${packageManager?.name} run dev`)}. \n` : '';
         const projectText = `- Navigate to your project directory using ${pinkText(`cd ${relativeDir}`)}. \n`;
-        const readmeText = '- Review the \`./README.md\` file for more information and next steps.';
+        const readmeText = '- Review the `./README.md` file for more information and next steps.';
         const nextSteps = `${directusText}${directusLoginText}${projectText}${frontendText}${readmeText}`;
         note(nextSteps, 'Next Steps');
         clackLog.warn(BSL_LICENSE_HEADLINE);
@@ -203,3 +200,22 @@ async function initGit(targetDir) {
         });
     }
 }
+export async function installFrontendDependencies({ frontendDir, install = installDependencies, onSkip, packageManager, warn = ux.warn, }) {
+    try {
+        await install({
+            cwd: frontendDir,
+            packageManager: packageManager ?? undefined,
+            silent: true,
+        });
+        return true;
+    }
+    catch {
+        onSkip?.();
+        warn('Failed to install dependencies');
+        if (packageManager?.name === 'pnpm') {
+            warn('This starter uses pnpm. From the frontend directory, try running: corepack enable && pnpm install');
+        }
+        warn('You can install dependencies manually and continue using the generated project.');
+        return false;
+    }
+}

package/dist/lib/load/apply-flags.d.ts

@@ -1,16 +1,21 @@
 export interface ApplyFlags {
+    allowBrokenRelations?: boolean;
+    collections?: string;
     content: boolean;
     dashboards: boolean;
     directusToken: string;
     directusUrl: string;
     disableTelemetry?: boolean;
+    excludeCollections?: string;
     extensions: boolean;
     files: boolean;
     flows: boolean;
+    noAssets?: boolean;
     noExit?: boolean;
     partial: boolean;
     permissions: boolean;
     programmatic: boolean;
+    relationStrategy?: 'deep' | 'empty' | 'preserve';
     schema: boolean;
     settings: boolean;
     templateLocation: string;
@@ -19,6 +24,4 @@ export interface ApplyFlags {
     userPassword: string;
     users?: boolean;
 }
-export declare const loadFlags: readonly ["content", "dashboards", "extensions", "files", "flows", "permissions", "schema", "settings", "users"];
 export declare function validateProgrammaticFlags(flags: ApplyFlags): ApplyFlags;
-export declare function validateInteractiveFlags(flags: ApplyFlags): ApplyFlags;

package/dist/lib/load/apply-flags.js

@@ -1,16 +1,4 @@
 import { ux } from '@oclif/core';
-import catchError from '../utils/catch-error.js';
-export const loadFlags = [
-    'content',
-    'dashboards',
-    'extensions',
-    'files',
-    'flows',
-    'permissions',
-    'schema',
-    'settings',
-    'users',
-];
 export function validateProgrammaticFlags(flags) {
     const { directusToken, directusUrl, templateLocation, userEmail, userPassword } = flags;
     if (!directusUrl)
@@ -19,43 +7,5 @@ export function validateProgrammaticFlags(flags) {
         ux.error('Either Directus token or email and password are required for programmatic mode.');
     if (!templateLocation)
         ux.error('Template location is required for programmatic mode.');
-    return flags.partial ? handlePartialFlags(flags) : setAllFlagsTrue(flags);
-}
-export function validateInteractiveFlags(flags) {
-    return flags.partial ? handlePartialFlags(flags) : setAllFlagsTrue(flags);
-}
-function handlePartialFlags(flags) {
-    const enabledFlags = loadFlags.filter(flag => flags[flag] === true);
-    const disabledFlags = loadFlags.filter(flag => flags[flag] === false);
-    if (enabledFlags.length > 0) {
-        for (const flag of loadFlags)
-            flags[flag] = enabledFlags.includes(flag);
-    }
-    else if (disabledFlags.length > 0) {
-        for (const flag of loadFlags)
-            flags[flag] = !disabledFlags.includes(flag);
-    }
-    else {
-        setAllFlagsTrue(flags);
-    }
-    handleDependencies(flags);
-    if (!loadFlags.some(flag => flags[flag])) {
-        catchError(new Error('When using --partial, at least one component must be loaded.'), { fatal: true });
-    }
-    return flags;
-}
-function handleDependencies(flags) {
-    if (flags.content && (!flags.schema || !flags.files)) {
-        flags.schema = flags.files = true;
-        ux.warn('Content loading requires schema and files. Enabling schema and files flags.');
-    }
-    if (flags.users && !flags.permissions) {
-        flags.permissions = true;
-        ux.warn('User loading requires permissions. Enabling permissions flag.');
-    }
-}
-function setAllFlagsTrue(flags) {
-    for (const flag of loadFlags)
-        flags[flag] = true;
     return flags;
 }

package/dist/lib/load/finalize-collections.d.ts

@@ -0,0 +1,2 @@
+import { type TemplatePlan } from '../template-plan/index.js';
+export default function finalizeCollections(dir: string, plan?: TemplatePlan): Promise<void>;

package/dist/lib/load/finalize-collections.js

@@ -0,0 +1,28 @@
+import { updateCollection } from '@directus/sdk';
+import { ux } from '@oclif/core';
+import { DIRECTUS_PINK } from '../constants.js';
+import { api } from '../sdk.js';
+import { includesSchemaCollection } from '../template-plan/index.js';
+import catchError from '../utils/catch-error.js';
+import readFile from '../utils/read-file.js';
+export default async function finalizeCollections(dir, plan) {
+    const collections = readFile('collections', dir)
+        .filter((collection) => includesSchemaCollection(collection.collection, plan))
+        .filter((collection) => !collection.collection.startsWith('directus_'));
+    ux.action.start(ux.colorize(DIRECTUS_PINK, `Finalizing metadata for ${collections.length} collections`));
+    const collectionNames = new Set(collections.map((collection) => collection.collection));
+    for await (const collection of collections) {
+        const meta = { ...collection.meta };
+        if (meta.group && !collectionNames.has(meta.group)) {
+            ux.warn(`Skipping missing group "${meta.group}" for collection "${collection.collection}"`);
+            delete meta.group;
+        }
+        try {
+            await api.client.request(updateCollection(collection.collection, { meta }));
+        }
+        catch (error) {
+            catchError(error, { context: { collection: collection.collection, group: meta.group } });
+        }
+    }
+    ux.action.stop();
+}

package/dist/lib/load/finalize-fields.d.ts

@@ -0,0 +1,2 @@
+import { type TemplatePlan } from '../template-plan/index.js';
+export default function finalizeFields(dir: string, plan?: TemplatePlan): Promise<void>;

package/dist/lib/load/finalize-fields.js

@@ -0,0 +1,25 @@
+import { updateField } from '@directus/sdk';
+import { ux } from '@oclif/core';
+import { DIRECTUS_PINK } from '../constants.js';
+import { api } from '../sdk.js';
+import { includesSchemaCollection } from '../template-plan/index.js';
+import catchError from '../utils/catch-error.js';
+import readFile from '../utils/read-file.js';
+export default async function finalizeFields(dir, plan) {
+    const fields = readFile('fields', dir)
+        .filter((field) => includesSchemaCollection(field.collection, plan))
+        .filter((field) => field.schema);
+    ux.action.start(ux.colorize(DIRECTUS_PINK, `Finalizing metadata for ${fields.length} fields`));
+    for await (const field of fields) {
+        try {
+            await api.client.request(updateField(field.collection, field.field, {
+                meta: field.meta ? { ...field.meta } : undefined,
+                schema: field.schema ? { ...field.schema } : undefined,
+            }));
+        }
+        catch (error) {
+            catchError(error, { context: { collection: field.collection, field: field.field } });
+        }
+    }
+    ux.action.stop();
+}

package/dist/lib/load/index.js

@@ -1,5 +1,8 @@
 import { ux } from '@oclif/core';
+import { applyMetadataToPlan, buildTemplatePlan, readTemplateMetadata } from '../template-plan/index.js';
 import checkTemplate from '../utils/check-template.js';
+import finalizeCollections from './finalize-collections.js';
+import finalizeFields from './finalize-fields.js';
 import loadAccess from './load-access.js';
 import loadCollections from './load-collections.js';
 import loadDashboards from './load-dashboards.js';
@@ -16,48 +19,65 @@ import loadRoles from './load-roles.js';
 import loadSettings from './load-settings.js';
 import loadTranslations from './load-translations.js';
 import loadUsers from './load-users.js';
-import updateRequiredFields from './update-required-fields.js';
 export default async function apply(dir, flags) {
     const source = `${dir}/src`;
-    const isTemplateOk = await checkTemplate(source);
-    if (!isTemplateOk) {
-        ux.error('The template is missing the collections, fields, or relations files. Older templates are not supported in v0.4 of directus-template-cli. Try using v0.3 to load older templates npx directus-template-cli@0.3 apply or extract the template using latest version before applying. Exiting...');
+    const metadata = readTemplateMetadata(source);
+    const requestedPlan = buildTemplatePlan(flags);
+    const effectivePlan = applyMetadataToPlan(requestedPlan, metadata);
+    const { components } = effectivePlan;
+    if (!metadata) {
+        ux.warn('No template-meta.json found. Treating as a full template — relation integrity check skipped.');
     }
-    if (flags.schema) {
-        await loadCollections(source);
-        await loadRelations(source);
+    else if (metadata.partial) {
+        ux.warn('Template metadata indicates this is a partial template.');
     }
-    if (flags.permissions || flags.users) {
+    const brokenRelationWarnings = metadata?.warnings?.filter((warning) => warning.type === 'excluded_relation') || [];
+    if (components.content && brokenRelationWarnings.length > 0 && !effectivePlan.allowBrokenRelations) {
+        ux.error('This partial template contains excluded relation references. Re-run with --allow-broken-relations to apply anyway.');
+    }
+    if (!metadata || components.schema) {
+        const isTemplateOk = await checkTemplate(source);
+        if (!isTemplateOk) {
+            ux.error('The template is missing the collections, fields, or relations files. Older templates are not supported in v0.4 of directus-template-cli. Try using v0.3 to load older templates npx directus-template-cli@0.3 apply or extract the template using latest version before applying. Exiting...');
+        }
+    }
+    if (components.schema) {
+        await loadCollections(source, effectivePlan);
+        await loadRelations(source, effectivePlan);
+        await finalizeCollections(source, effectivePlan);
+    }
+    if (components.permissions || components.users) {
         await loadRoles(source);
         await loadPolicies(source);
         await loadPermissions(source);
-        if (flags.users) {
+        if (components.users) {
             await loadUsers(source);
         }
         await loadAccess(source);
     }
-    if (flags.files) {
+    if (components.files) {
         await loadFolders(source);
         await loadFiles(source);
     }
-    if (flags.content) {
-        await loadData(source);
+    if (components.content) {
+        await loadData(source, effectivePlan);
     }
-    if (flags.schema) {
-        await updateRequiredFields(source);
+    if (components.schema) {
+        // Finalize fields after data loading because skeleton records rely on relaxed constraints.
+        await finalizeFields(source, effectivePlan);
     }
-    if (flags.dashboards) {
+    if (components.dashboards) {
         await loadDashboards(source);
     }
-    if (flags.flows) {
+    if (components.flows) {
         await loadFlows(source);
     }
-    if (flags.settings) {
+    if (components.settings) {
         await loadSettings(source);
         await loadTranslations(source);
         await loadPresets(source);
     }
-    if (flags.extensions) {
+    if (components.extensions) {
         await loadExtensions(source);
     }
     return {};

package/dist/lib/load/load-collections.d.ts

@@ -1,6 +1,7 @@
+import { type TemplatePlan } from '../template-plan/index.js';
 /**
  * Load collections into the Directus instance
  * @param dir - The directory to read the collections and fields from
  * @returns {Promise<void>} - Returns nothing
  */
-export default function loadCollections(dir: string): Promise<void>;
+export default function loadCollections(dir: string, plan?: TemplatePlan): Promise<void>;

package/dist/lib/load/load-collections.js

@@ -1,7 +1,8 @@
-import { createCollection, createField, readCollections, readFields, updateCollection, } from '@directus/sdk';
+import { createCollection, createField, readCollections, readFields } from '@directus/sdk';
 import { ux } from '@oclif/core';
 import { DIRECTUS_PINK } from '../constants.js';
 import { api } from '../sdk.js';
+import { includesSchemaCollection } from '../template-plan/index.js';
 import catchError from '../utils/catch-error.js';
 import readFile from '../utils/read-file.js';
 /**
@@ -9,12 +10,11 @@ import readFile from '../utils/read-file.js';
  * @param dir - The directory to read the collections and fields from
  * @returns {Promise<void>} - Returns nothing
  */
-export default async function loadCollections(dir) {
-    const collectionsToAdd = readFile('collections', dir);
-    const fieldsToAdd = readFile('fields', dir);
+export default async function loadCollections(dir, plan) {
+    const collectionsToAdd = readFile('collections', dir).filter((collection) => includesSchemaCollection(collection.collection, plan));
+    const fieldsToAdd = readFile('fields', dir).filter((field) => includesSchemaCollection(field.collection, plan));
     ux.action.start(ux.colorize(DIRECTUS_PINK, `Loading ${collectionsToAdd.length} collections and ${fieldsToAdd.length} fields`));
     await processCollections(collectionsToAdd, fieldsToAdd);
-    await updateCollections(collectionsToAdd);
     await addCustomFieldsOnSystemCollections(fieldsToAdd);
     ux.action.stop();
 }
@@ -24,10 +24,12 @@ async function processCollections(collectionsToAdd, fieldsToAdd) {
     for await (const collection of collectionsToAdd) {
         try {
             const existingCollection = existingCollections.find((c) => c.collection === collection.collection);
-            await (existingCollection ? addNewFieldsToExistingCollection(collection.collection, fieldsToAdd, existingFields) : addNewCollectionWithFields(collection, fieldsToAdd));
+            await (existingCollection
+                ? addNewFieldsToExistingCollection(collection.collection, fieldsToAdd, existingFields)
+                : addNewCollectionWithFields(collection, fieldsToAdd));
         }
         catch (error) {
-            catchError(error);
+            catchError(error, { context: { collection: collection.collection } });
         }
     }
 }
@@ -44,8 +46,9 @@ const removeRequiredorIsNullable = (field) => {
     return field;
 };
 async function addNewCollectionWithFields(collection, allFields) {
-    const collectionFields = allFields.filter(field => field.collection === collection.collection)
-        .map(field => removeRequiredorIsNullable(field));
+    const collectionFields = allFields
+        .filter((field) => field.collection === collection.collection)
+        .map((field) => removeRequiredorIsNullable(field));
     const collectionWithoutGroup = {
         ...collection,
         fields: collectionFields,
@@ -55,8 +58,9 @@ async function addNewCollectionWithFields(collection, allFields) {
     await api.client.request(createCollection(collectionWithoutGroup));
 }
 async function addNewFieldsToExistingCollection(collectionName, fieldsToAdd, existingFields) {
-    const collectionFieldsToAdd = fieldsToAdd.filter(field => field.collection === collectionName)
-        .map(field => removeRequiredorIsNullable(field));
+    const collectionFieldsToAdd = fieldsToAdd
+        .filter((field) => field.collection === collectionName)
+        .map((field) => removeRequiredorIsNullable(field));
     const existingCollectionFields = existingFields.filter((field) => field.collection === collectionName);
     for await (const field of collectionFieldsToAdd) {
         if (!existingCollectionFields.some((existingField) => existingField.field === field.field)) {
@@ -65,28 +69,11 @@ async function addNewFieldsToExistingCollection(collectionName, fieldsToAdd, exi
                 await api.client.request(createField(collectionName, field));
             }
             catch (error) {
-                catchError(error);
+                catchError(error, { context: { collection: collectionName, field: field.field } });
             }
         }
     }
 }
-async function updateCollections(collections) {
-    for await (const collection of collections) {
-        try {
-            if (collection.meta.group) {
-                const pl = {
-                    meta: {
-                        group: collection.meta.group,
-                    },
-                };
-                await api.client.request(updateCollection(collection.collection, pl));
-            }
-        }
-        catch (error) {
-            catchError(error);
-        }
-    }
-}
 async function addCustomFieldsOnSystemCollections(fields) {
     const customFields = fields.filter((field) => field.collection.startsWith('directus_'));
     const existingFields = await api.client.request(readFields());
@@ -99,7 +86,7 @@ async function addCustomFieldsOnSystemCollections(fields) {
             }
         }
         catch (error) {
-            catchError(error);
+            catchError(error, { context: { collection: field.collection, field: field.field } });
         }
     }
 }

package/dist/lib/load/load-data.d.ts

@@ -1 +1,3 @@
-export default function loadData(dir: string): Promise<void>;
+import { type TemplatePlan } from '../template-plan/index.js';
+export default function loadData(dir: string, plan?: TemplatePlan): Promise<void>;
+export declare function getUserCollections(dir: string, plan?: TemplatePlan): any[];