@agility/create-next-app 1.0.0-beta.2

package/dist/utils/validation.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateProjectName = validateProjectName;
+exports.checkDirectoryExists = checkDirectoryExists;
+exports.isDirectoryEmpty = isDirectoryEmpty;
+exports.validateProjectPath = validateProjectPath;
+exports.isGitInstalled = isGitInstalled;
+exports.displayValidationError = displayValidationError;
+exports.checkDiskSpace = checkDiskSpace;
+exports.validateNodeVersion = validateNodeVersion;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Reserved names that cannot be used as project names
+ */
+const RESERVED_NAMES = [
+    'node_modules',
+    'package.json',
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'bun.lockb',
+    '.git',
+    '.env',
+    '.env.local',
+    'dist',
+    'build',
+    'out',
+    'test',
+    'tests',
+    '__tests__',
+    'public',
+    'static',
+    'src',
+    'lib',
+    'components',
+    'app',
+    'pages',
+];
+/**
+ * Validates a project name
+ */
+function validateProjectName(projectName) {
+    // Check if empty
+    if (!projectName || projectName.trim().length === 0) {
+        return {
+            valid: false,
+            message: 'Project name cannot be empty',
+        };
+    }
+    // Check for valid characters (lowercase letters, numbers, hyphens, underscores)
+    if (!/^[a-z0-9-_]+$/i.test(projectName)) {
+        return {
+            valid: false,
+            message: 'Project name can only contain letters, numbers, hyphens (-), and underscores (_)',
+        };
+    }
+    // Check if it starts with a dot
+    if (projectName.startsWith('.')) {
+        return {
+            valid: false,
+            message: 'Project name cannot start with a dot (.)',
+        };
+    }
+    // Check if it starts with a number
+    if (/^\d/.test(projectName)) {
+        return {
+            valid: false,
+            message: 'Project name cannot start with a number',
+        };
+    }
+    // Check for reserved names
+    if (RESERVED_NAMES.includes(projectName.toLowerCase())) {
+        return {
+            valid: false,
+            message: `"${projectName}" is a reserved name and cannot be used`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Checks if a directory already exists
+ */
+function checkDirectoryExists(projectPath) {
+    return fs_1.default.existsSync(projectPath);
+}
+/**
+ * Checks if directory is empty
+ */
+function isDirectoryEmpty(projectPath) {
+    if (!fs_1.default.existsSync(projectPath)) {
+        return true;
+    }
+    const files = fs_1.default.readdirSync(projectPath);
+    return files.length === 0 || files.every(file => file === '.git');
+}
+/**
+ * Validates that we can create a project at the given path
+ */
+function validateProjectPath(projectPath) {
+    const exists = checkDirectoryExists(projectPath);
+    if (exists) {
+        const isEmpty = isDirectoryEmpty(projectPath);
+        if (!isEmpty) {
+            return {
+                valid: false,
+                message: `Directory "${path_1.default.basename(projectPath)}" already exists and is not empty.\nPlease choose a different project name or remove the existing directory.`,
+            };
+        }
+    }
+    // Check write permissions of parent directory
+    const parentDir = path_1.default.dirname(projectPath);
+    try {
+        fs_1.default.accessSync(parentDir, fs_1.default.constants.W_OK);
+    }
+    catch (error) {
+        return {
+            valid: false,
+            message: `No write permission in directory "${parentDir}".\nPlease check your permissions or choose a different location.`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Check if git is installed
+ */
+function isGitInstalled() {
+    try {
+        const { execSync } = require('child_process');
+        execSync('git --version', { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Displays validation error with helpful formatting
+ */
+function displayValidationError(message) {
+    console.error('\n' + chalk_1.default.red('✖') + ' ' + chalk_1.default.red.bold('Validation Error'));
+    console.error(chalk_1.default.red(message));
+    console.error();
+}
+/**
+ * Check available disk space (basic check)
+ */
+function checkDiskSpace() {
+    try {
+        const os = require('os');
+        // Basic check - Next.js projects typically need at least 500MB
+        const REQUIRED_SPACE_MB = 500;
+        const tmpdir = os.tmpdir();
+        // This is a rough check - not perfect but better than nothing
+        return { hasSpace: true };
+    }
+    catch {
+        // If we can't check, assume it's okay
+        return { hasSpace: true };
+    }
+}
+/**
+ * Validate Node.js version
+ */
+function validateNodeVersion() {
+    const currentVersion = process.version;
+    const majorVersion = parseInt(currentVersion.split('.')[0].slice(1), 10);
+    if (majorVersion < 18) {
+        return {
+            valid: false,
+            message: `Node.js 18.0.0 or higher is required. You are using ${currentVersion}.\nPlease upgrade Node.js: https://nodejs.org/`,
+        };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=validation.js.map

package/dist/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@agility/create-next-app",
+  "version": "1.0.0-beta.2",
+  "description": "Create a new Next.js project with Agility CMS integration",
+  "main": "dist/cli/index.js",
+  "bin": {
+    "create-agility-app": "./bin/create-agility-app.js"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "dev": "tsx src/cli/index.ts",
+    "test": "tsx src/cli/index.ts test-app --typescript --tailwind",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "nextjs",
+    "agility",
+    "cms",
+    "cli",
+    "scaffold"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@agility/content-fetch": "^2.0.9",
+    "boxen": "^8.0.1",
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "inquirer": "^9.2.15",
+    "open": "^10.1.0",
+    "ora": "^8.0.1",
+    "update-notifier": "^7.3.1"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^20.0.0",
+    "@types/update-notifier": "^6.0.8",
+    "tsx": "^4.7.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/agility/api-keys/generateApiKeys.ts

@@ -0,0 +1,100 @@
+import ora from 'ora';
+import chalk from 'chalk';
+import type { ApiKeys } from '../../types';
+import { getMgmtOAuthUrl } from '../utils/getMgmtAPIUrl';
+
+/**
+ * Gets API keys for an Agility instance
+ * @param accessToken - OAuth access token
+ * @param instanceGuid - Instance GUID
+ * @returns Object with fetch and preview API keys
+ */
+export async function generateApiKeys(accessToken: string, instanceGuid: string): Promise<ApiKeys> {
+  const spinner = ora('Fetching API keys...').start();
+
+  try {
+    const oauthBaseUrl = getMgmtOAuthUrl({ guid: instanceGuid });
+
+    // Get Fetch API Key
+    const fetchKeyUrl = `${oauthBaseUrl}GetFetchKey?guid=${instanceGuid}`;
+    const fetchKeyResponse = await fetch(fetchKeyUrl, {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!fetchKeyResponse.ok) {
+      const errorText = await fetchKeyResponse.text();
+      let errorMessage = `Failed to get Fetch Key: ${fetchKeyResponse.status} ${fetchKeyResponse.statusText}`;
+      try {
+        const errorJson = JSON.parse(errorText);
+        if (errorJson.message) {
+          errorMessage += ` - ${errorJson.message}`;
+        } else {
+          errorMessage += ` - ${errorText}`;
+        }
+      } catch {
+        errorMessage += ` - ${errorText}`;
+      }
+      throw new Error(errorMessage);
+    }
+
+    const fetchKey = await fetchKeyResponse.text();
+    if (!fetchKey) {
+      throw new Error('No Fetch Key received from API');
+    }
+
+    // Get Preview API Key
+    const previewKeyUrl = `${oauthBaseUrl}GetPreviewKey?guid=${instanceGuid}`;
+
+    const previewKeyResponse = await fetch(previewKeyUrl, {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!previewKeyResponse.ok) {
+      const errorText = await previewKeyResponse.text();
+      let errorMessage = `Failed to get Preview Key: ${previewKeyResponse.status} ${previewKeyResponse.statusText}`;
+      try {
+        const errorJson = JSON.parse(errorText);
+        if (errorJson.message) {
+          errorMessage += ` - ${errorJson.message}`;
+        } else {
+          errorMessage += ` - ${errorText}`;
+        }
+      } catch {
+        errorMessage += ` - ${errorText}`;
+      }
+      throw new Error(errorMessage);
+    }
+
+    const previewKey = await previewKeyResponse.text();
+    if (!previewKey) {
+      throw new Error('No Preview Key received from API');
+    }
+
+    spinner.succeed('API keys retrieved');
+
+    return {
+      fetchKey,
+      previewKey,
+      securityKey: '' // Security key is typically not needed for basic setup
+    };
+  } catch (error) {
+    spinner.fail('Failed to get API keys');
+    if (error instanceof Error) {
+      console.error(chalk.red(`Error: ${error.message}`));
+      // Log additional details if available
+      if (error instanceof Error && 'cause' in error) {
+        console.error(chalk.gray(`Details: ${JSON.stringify(error.cause)}`));
+      }
+    }
+    throw error;
+  }
+}
+

package/src/agility/api-keys/getApiKeys.ts

@@ -0,0 +1,13 @@
+import type { ApiKeys } from '../../types';
+import { generateApiKeys } from './generateApiKeys';
+
+/**
+ * Gets API keys for an existing instance
+ * @param accessToken - OAuth access token
+ * @param instanceGuid - Instance GUID
+ * @returns Object with fetch and preview API keys
+ */
+export async function getApiKeys(accessToken: string, instanceGuid: string): Promise<ApiKeys> {
+  return generateApiKeys(accessToken, instanceGuid);
+}
+

package/src/agility/index.ts

@@ -0,0 +1,3 @@
+export { manageInstance } from './instance/manageInstance';
+export { getApiKeys } from './api-keys/getApiKeys';
+

package/src/agility/instance/createNewInstance.ts

@@ -0,0 +1,67 @@
+import inquirer from 'inquirer';
+import ora from 'ora';
+import type { InstanceData } from '../../types';
+import { generateApiKeys } from '../api-keys/generateApiKeys';
+
+/**
+ * Creates a new blank Agility instance
+ * @param accessToken - OAuth access token
+ * @returns Instance data with GUID and API keys
+ */
+export async function createNewInstance(accessToken: string): Promise<InstanceData> {
+  const spinner = ora('Creating new Agility instance...').start();
+
+  try {
+    // Prompt for instance name
+    const answers = await inquirer.prompt<{ instanceName: string }>([
+      {
+        type: 'input',
+        name: 'instanceName',
+        message: 'Enter a name for your new instance:',
+        default: 'My Agility Instance',
+        validate: (input: string) => {
+          if (!input || input.trim().length === 0) {
+            return 'Instance name is required';
+          }
+          return true;
+        }
+      }
+    ]);
+
+    spinner.text = 'Creating instance...';
+
+    // In a real implementation, this would call Agility's API to create an instance
+    // For now, we'll use a placeholder that would need to be implemented
+    // const instance = await createAgilityInstance(accessToken, answers.instanceName);
+
+    // For now, we'll prompt for the instance GUID manually
+    const guidAnswer = await inquirer.prompt<{ instanceGuid: string }>([
+      {
+        type: 'input',
+        name: 'instanceGuid',
+        message: 'Enter the instance GUID (you can find this in Agility CMS):',
+        validate: (input: string) => {
+          if (!input || input.trim().length === 0) {
+            return 'Instance GUID is required';
+          }
+          return true;
+        }
+      }
+    ]);
+
+    spinner.succeed('Instance ready');
+
+    // Generate API keys
+    const apiKeys = await generateApiKeys(accessToken, guidAnswer.instanceGuid);
+
+    return {
+      guid: guidAnswer.instanceGuid,
+      name: answers.instanceName,
+      apiKeys
+    };
+  } catch (error) {
+    spinner.fail('Failed to create instance');
+    throw error;
+  }
+}
+

package/src/agility/instance/getAvailableInstances.ts

@@ -0,0 +1,49 @@
+import chalk from 'chalk';
+import type { Instance } from '../../types';
+import { getMgmtAPIUrl } from '../utils/getMgmtAPIUrl';
+
+/**
+ * Gets available Agility instances for the authenticated user
+ * @param accessToken - OAuth access token
+ * @returns Array of instances
+ */
+export async function getAvailableInstances(accessToken: string): Promise<Instance[]> {
+  try {
+    // Use the Agility Management API to get current user and their instances
+    // Note: We don't have a GUID yet, so we use the default URL
+    const apiBaseUrl = getMgmtAPIUrl();
+    const response = await fetch(`${apiBaseUrl}users/me`, {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to get user info: ${response.status} ${response.statusText}`);
+    }
+
+    const userData = await response.json() as {
+      websiteAccess?: Array<{
+        websiteName: string;
+        displayName: string;
+        guid: string;
+        orgName?: string;
+      }>;
+    };
+
+    // Convert websiteAccess to instances
+    const instances: Instance[] = (userData.websiteAccess || []).map(access => ({
+      name: access.displayName || access.websiteName,
+      guid: access.guid,
+      org: access.orgName,
+    }));
+
+    return instances;
+  } catch (error) {
+    console.warn(chalk.yellow('Could not fetch instances from API'));
+    throw error;
+  }
+}
+

package/src/agility/instance/manageInstance.ts

@@ -0,0 +1,90 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import ora from 'ora';
+import type { InstanceData, CliOptions } from '../../types';
+import { getAvailableInstances } from './getAvailableInstances';
+import { generateApiKeys } from '../api-keys/generateApiKeys';
+
+/**
+ * Manages Agility CMS instance selection from existing instances
+ * @param accessToken - OAuth access token
+ * @param options - CLI options
+ * @returns Instance data with GUID and API keys
+ */
+export async function manageInstance(accessToken: string, options: CliOptions): Promise<InstanceData> {
+  const spinner = ora('Fetching Agility instances...').start();
+
+  try {
+    // Fetch available instances using the Management API
+    const instances = await getAvailableInstances(accessToken);
+
+    spinner.succeed(`Found ${instances.length} instance(s)`);
+
+    if (instances.length === 0) {
+      throw new Error('No Agility CMS instances found. Please create an instance in Agility CMS first, or skip the connection for now.');
+    }
+
+    // Group instances by organization
+    const instancesByOrg = new Map<string, typeof instances>();
+    for (const inst of instances) {
+      const orgName = inst.org || 'No Organization';
+      if (!instancesByOrg.has(orgName)) {
+        instancesByOrg.set(orgName, []);
+      }
+      instancesByOrg.get(orgName)!.push(inst);
+    }
+
+    // Sort organizations alphabetically
+    const sortedOrgs = Array.from(instancesByOrg.keys()).sort();
+
+    // Build choices with organization grouping
+    const instanceChoices: Array<{ name: string; value: string } | inquirer.Separator> = [];
+
+    for (const orgName of sortedOrgs) {
+      // Add separator for organization (except for first one)
+      if (instanceChoices.length > 0) {
+        instanceChoices.push(new inquirer.Separator());
+      }
+
+      // Add organization header
+      instanceChoices.push(new inquirer.Separator(chalk.cyan(`  ${orgName}`)));
+
+      // Add instances for this organization
+      const orgInstances = instancesByOrg.get(orgName)!;
+      for (const inst of orgInstances) {
+        instanceChoices.push({
+          name: `  - ${inst.name} (${inst.guid})`,
+          value: inst.guid
+        });
+      }
+    }
+
+    const selected = await inquirer.prompt<{ instanceGuid: string }>([
+      {
+        type: 'list',
+        name: 'instanceGuid',
+        message: 'Select an instance:',
+        choices: instanceChoices
+      }
+    ]);
+
+    // Find the selected instance to get its name
+    const selectedInstance = instances.find(inst => inst.guid === selected.instanceGuid);
+    if (!selectedInstance) {
+      throw new Error('Selected instance not found');
+    }
+
+    // Generate API keys for selected instance
+    const apiKeys = await generateApiKeys(accessToken, selected.instanceGuid);
+
+    return {
+      guid: selected.instanceGuid,
+      name: selectedInstance.name,
+      apiKeys
+    };
+  } catch (error) {
+    spinner.fail('Failed to manage instance');
+    throw error;
+  }
+}
+

package/src/agility/utils/getMgmtAPIUrl.ts

@@ -0,0 +1,68 @@
+interface Props {
+	/**
+	 * The instance guid (optional - if not provided, uses default URL)
+	 */
+	guid?: string;
+}
+
+/**
+ * Gets the management API base URL based on the instance GUID
+ * @param guid - The instance GUID (optional - if not provided, uses default URL)
+ * @returns The base URL for the management API
+ */
+export const getMgmtAPIUrl = ({ guid }: Props = {}): string => {
+	const baseUrlSuffixes: { [key: string]: string } = {
+		u: '',
+		c: '-ca',
+		e: '-eu',
+		a: '-aus',
+		d: '-dev'
+	};
+
+	// If no GUID provided, use default URL
+	if (!guid || guid.length === 0) {
+		return `https://mgmt.aglty.io/api/v1/`;
+	}
+
+	const env = guid.substring(guid.length - 1);
+
+	// New format of guid
+	if (baseUrlSuffixes.hasOwnProperty(env)) {
+		return `https://mgmt${baseUrlSuffixes[env]}.aglty.io/api/v1/`;
+	} else {
+		// use default url
+		return `https://mgmt.aglty.io/api/v1/`;
+	}
+};
+
+/**
+ * Gets the management OAuth base URL based on the instance GUID
+ * @param guid - The instance GUID (optional - if not provided, uses default URL)
+ * @returns The base URL for the management OAuth endpoints
+ */
+export const getMgmtOAuthUrl = ({ guid }: Props = {}): string => {
+	const baseUrlSuffixes: { [key: string]: string } = {
+		u: '',
+		c: '-ca',
+		e: '-eu',
+		a: '-aus',
+		d: '-dev',
+		us2: 'usa2'
+	};
+
+	// If no GUID provided, use default URL
+	if (!guid || guid.length === 0) {
+		return `https://mgmt.aglty.io/oauth/`;
+	}
+
+	const env = guid.substring(guid.length - 1);
+
+	// New format of guid
+	if (baseUrlSuffixes.hasOwnProperty(env)) {
+		return `https://mgmt${baseUrlSuffixes[env]}.aglty.io/oauth/`;
+	} else {
+		// use default url
+		return `https://mgmt.aglty.io/oauth/`;
+	}
+};
+

package/src/auth/api-key/authenticateWithApiKey.ts

@@ -0,0 +1,24 @@
+import inquirer from 'inquirer';
+
+/**
+ * Alternative: Manual API key input if OAuth is not available
+ * @returns API key or access token
+ */
+export async function authenticateWithApiKey(): Promise<string> {
+  const answers = await inquirer.prompt<{ apiKey: string }>([
+    {
+      type: 'input',
+      name: 'apiKey',
+      message: 'Enter your Agility CMS API key:',
+      validate: (input: string) => {
+        if (!input || input.trim().length === 0) {
+          return 'API key is required';
+        }
+        return true;
+      }
+    }
+  ]);
+
+  return answers.apiKey;
+}
+

package/src/auth/index.ts

@@ -0,0 +1,3 @@
+export { authenticate } from './oauth/authenticate';
+export { authenticateWithApiKey } from './api-key/authenticateWithApiKey';
+