From e72deb6b504a58a1a2b1f7be8731023fa221e1ef Mon Sep 17 00:00:00 2001 From: Kevin Date: Fri, 12 Jun 2026 11:23:06 -0400 Subject: [PATCH] PROD-2195/PROD-2196: fix hidden CLI flags in --help and correct README - Remove self-referencing yargs aliases (sourceGuid, targetGuid, overwrite, force, autoPublish) which caused yargs to hide those options from --help - Decouple --reset from --update: "reset" was declared as an alias of update, colliding with the separate reset option, hiding it from help and overwriting update's description - Remove dead targetGuid override in push builder (it was silently reverted by the ...systemArgs spread; requirement is enforced in validateCommand after .env priming so AGILITY_TARGET_GUID keeps working) - README: document conflict-scoped --overwrite behavior, correct --models-with-deps to include pages, mark pull --sourceGuid optional with AGILITY_GUID fallback, add Sitemaps to --elements default, and document missing flags (--channel, --preview, --dryRun, --contentIDs, --pageIDs, --insecure, --legacyFolders, --baseUrl, --token, --force, --reset, dev modes) Co-Authored-By: Claude Fable 5 --- README.md | 97 +++++++++++++++++++++++++++-------------- src/core/system-args.ts | 16 ++++--- src/index.ts | 10 ++--- 3 files changed, 76 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 3484f26..1eb936e 100644 --- a/README.md +++ b/README.md @@ -27,29 +27,41 @@ agility pull [options] **Core Instance Options:** -| Option | Type | Default | Description | -| -------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------- | -| `--sourceGuid` | string | _(empty)_ | Source instance GUID (required for sync, can be from .env for pull) | -| `--locales` | string | _(empty)_ | Comma-separated list of locales to operate on. If not specified, locales are automatically pulled from the instance | +| Option | Type | Default | Description | +| -------------- | ------- | --------- | -------------------------------------------------------------------------------------------------------------------- | +| `--sourceGuid` | string | _(empty)_ | Source instance GUID. Optional — falls back to `AGILITY_GUID` from your `.env` file if not provided | +| `--locales` | string | _(empty)_ | Comma-separated list of locales to operate on. If not specified, locales are automatically pulled from the instance | +| `--channel` | string | `website` | Channel for the operation. Falls back to `AGILITY_WEBSITE` from your `.env` file if not provided | +| `--preview` | boolean | `true` | Use preview environment data. Set to `false` to use live environment data | **Content Selection Options:** -| Option | Type | Default | Description | -| ------------ | ------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------- | -| `--elements` | string | `Models,Galleries,Assets,Containers,Content,Templates,Pages` | Comma-separated list of elements to process | -| `--models` | string | _(empty)_ | Comma-separated list of model reference names to sync (only syncs the specified models) | +| Option | Type | Default | Description | +| ------------ | ------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| `--elements` | string | `Models,Galleries,Assets,Containers,Content,Templates,Pages,Sitemaps` | Comma-separated list of elements to process | +| `--models` | string | _(empty)_ | Comma-separated list of model reference names to sync (only syncs the specified models) | **File System Options:** -| Option | Type | Default | Description | -| ------------ | ------ | --------------- | ------------------------------ | -| `--rootPath` | string | `agility-files` | Root directory for local files | +| Option | Type | Default | Description | +| ----------------- | ------- | --------------- | -------------------------------------------------------------------- | +| `--rootPath` | string | `agility-files` | Root directory for local files | +| `--legacyFolders` | boolean | `false` | Use the legacy folder structure (all files in root `agility-files`) | **Operation Control Options:** -| Option | Type | Default | Description | -| ---------- | ------- | ------- | ------------------------------------------- | -| `--update` | boolean | `false` | Set to `true` to force updating source data | +| Option | Type | Default | Description | +| ---------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `--update` | boolean | `false` | Set to `true` to force download/overwrite existing local files and clear sync tokens for a complete refresh (default skips existing files) | +| `--reset` | boolean | `false` | Nuclear option: completely delete the instance GUID folder (including sync tokens), forcing a full fresh download | + +**Network & Authentication Options:** + +| Option | Type | Default | Description | +| ------------ | ------- | --------- | --------------------------------------------------------------------------------------------------------- | +| `--token` | string | _(empty)_ | Personal Access Token for headless/CI authentication. Falls back to `AGILITY_TOKEN` from your `.env` file | +| `--insecure` | boolean | `false` | Disable SSL certificate verification | +| `--baseUrl` | string | _(empty)_ | Override the base URL for the Agility API, if different from the default | **UI & Output Options:** @@ -90,32 +102,48 @@ agility sync [options] | Option | Type | Default | Description | | -------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--sourceGuid` | string | _(empty)_ | Source instance GUID (required for sync) | -| `--targetGuid` | string | _(empty)_ | Target instance GUID (required for sync) | +| `--sourceGuid` | string | _(empty)_ | Source instance GUID (required for sync — falls back to `AGILITY_GUID` from your `.env` file) | +| `--targetGuid` | string | _(empty)_ | Target instance GUID (required for sync — falls back to `AGILITY_TARGET_GUID` from your `.env` file) | | `--locales` | string | _(empty)_ | Comma-separated list of locales to operate on. If not specified, locales are automatically pulled from the source instance. **Note:** For sync operations, if locales are not specified, the target instance must have all the same locales set up, or the sync will error. You can selectively sync only specific locales (e.g., `--locales="en-us"`) to avoid requiring all locales to be set up in the target instance | +| `--channel` | string | `website` | Channel for the operation. Falls back to `AGILITY_WEBSITE` from your `.env` file if not provided | +| `--preview` | boolean | `true` | Use preview environment data. Set to `false` to use live environment data | **Content Selection Options:** | Option | Type | Default | Description | | -------------------- | ------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--elements` | string | `Models,Galleries,Assets,Containers,Content,Templates,Pages` | Comma-separated list of elements to process | -| `--models` | string | _(empty)_ | Comma-separated list of model reference names to sync (only syncs the specified models) | -| `--models-with-deps` | string | _(empty)_ | Comma-separated list of model reference names to sync with dependencies (includes content, assets, galleries, containers, and lists, but not pages) | +| `--elements` | string | `Models,Galleries,Assets,Containers,Content,Templates,Pages,Sitemaps` | Comma-separated list of elements to process | +| `--models` | string | _(empty)_ | Comma-separated list of model reference names to sync (only syncs the specified models) | +| `--models-with-deps` | string | _(empty)_ | Comma-separated list of model reference names to sync with their full dependency tree (includes content, pages, assets, galleries, templates, and containers) | **File System Options:** -| Option | Type | Default | Description | -| ------------ | ------ | --------------- | ------------------------------ | -| `--rootPath` | string | `agility-files` | Root directory for local files | +| Option | Type | Default | Description | +| ----------------- | ------- | --------------- | ------------------------------------------------------------------- | +| `--rootPath` | string | `agility-files` | Root directory for local files | +| `--legacyFolders` | boolean | `false` | Use the legacy folder structure (all files in root `agility-files`) | **Operation Control Options:** -| Option | Type | Default | Description | -| --------------- | ------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Option | Type | Default | Description | +| --------------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--update` | boolean | `false` | Download fresh data from source instance before operations, if left false, incremental sync is performed to only get changed data. | -| `--overwrite` | boolean | `false` | Force update existing items in target instance instead of creating new items with -1 IDs. Default: false (Warning: may cause duplicate items in lists, overwriting existing content) | +| `--overwrite` | boolean | `false` | Overwrite target items that are in **conflict** with the source (e.g. the item already exists or has changed in the target). By default, conflicting target items are left as-is and skipped — safer behavior to prevent overwriting existing content | +| `--force` | boolean | `false` | Override target safety conflicts: when the target instance has changes AND the change delta has updates, apply sync changes anyway. Default is the safer behavior to prevent data loss | +| `--reset` | boolean | `false` | Nuclear option: completely delete the instance GUID folder (including sync tokens), forcing a full fresh download | +| `--dryRun` | boolean | `false` | Show what items would be processed without executing the operation | +| `--contentIDs` | string | _(empty)_ | Comma-separated list of target content IDs to process, bypassing the mappings lookup (e.g., `--contentIDs=121,1221,345`) | +| `--pageIDs` | string | _(empty)_ | Comma-separated list of target page IDs to process, bypassing the mappings lookup (e.g., `--pageIDs=12,11,45`) | | `--autoPublish` | string | _(disabled)_ | Automatically publish synced items that were published in the source instance. Values: `content`, `pages`, `both`. If flag is provided without a value, defaults to `both`. Items that are only in staging (not published) in the source are skipped. | +**Network & Authentication Options:** + +| Option | Type | Default | Description | +| ------------ | ------- | --------- | ---------------------------------------------------------------------------------------------------------- | +| `--token` | string | _(empty)_ | Personal Access Token for headless/CI authentication. Falls back to `AGILITY_TOKEN` from your `.env` file | +| `--insecure` | boolean | `false` | Disable SSL certificate verification | +| `--baseUrl` | string | _(empty)_ | Override the base URL for the Agility API, if different from the default | + **UI & Output Options:** | Option | Type | Default | Description | @@ -123,6 +151,10 @@ agility sync [options] | `--headless` | boolean | `false` | Disable logging and console/terminal output, log to file only (CI/CD) | | `--verbose` | boolean | `true` | Detailed console output | +**Developer Options:** + +The CLI also accepts `--dev`, `--local`, `--preprod`, and `--test` flags. These point the CLI at non-production Agility environments or enable analysis-only test mode, and are intended for Agility developers — they are not needed for normal use. + #### Sync Examples ```bash @@ -135,13 +167,13 @@ agility sync --sourceGuid="abc123" --targetGuid="def456" --locales="en-us" # Sync specific elements only agility sync --sourceGuid="abc123" --targetGuid="def456" --elements="Assets" -# Force update existing items +# Overwrite target items that conflict with the source agility sync --sourceGuid="abc123" --targetGuid="def456" --overwrite # Sync only specified models (models only, no dependencies) agility sync --sourceGuid="abc123" --targetGuid="def456" --models="BlogPost,BlogCategory" -# Sync models with dependencies (includes content, assets, galleries, containers, lists, but not pages) +# Sync models with dependencies (includes content, pages, assets, galleries, templates, and containers) agility sync --sourceGuid="abc123" --targetGuid="def456" --models-with-deps="BlogPost,BlogCategory" # Sync and auto-publish everything that was published in source @@ -213,18 +245,17 @@ agility sync --sourceGuid="abc123" --targetGuid="def456" --models="BlogPost,Blog #### --models-with-deps -The `--models-with-deps` parameter syncs the specified models **plus their dependencies**. It includes: +The `--models-with-deps` parameter syncs the specified models **plus their full dependency tree**. It includes: - Content items based on those models +- Pages that use the content - Assets referenced by the content - Galleries referenced by the content +- Templates - Containers -- Lists - -**Note:** Pages are **not** included when using `--models-with-deps`. ```bash -# Sync models with all dependencies (except pages) +# Sync models with all dependencies (including pages) agility sync --sourceGuid="abc123" --targetGuid="def456" --models-with-deps="BlogPost,BlogCategory" ``` @@ -234,7 +265,7 @@ agility sync --sourceGuid="abc123" --targetGuid="def456" --models-with-deps="Blo # Sync only models (no dependencies) agility sync --sourceGuid="abc123" --targetGuid="def456" --models="BlogPost,BlogCategory" -# Sync models with dependencies (content, assets, galleries, containers, lists - but not pages) +# Sync models with dependencies (content, pages, assets, galleries, templates, and containers) agility sync --sourceGuid="abc123" --targetGuid="def456" --models-with-deps="Product,ProductCategory,ProductReview" ``` diff --git a/src/core/system-args.ts b/src/core/system-args.ts index 90e1b33..b1de2bb 100644 --- a/src/core/system-args.ts +++ b/src/core/system-args.ts @@ -159,9 +159,9 @@ export const systemArgs = { sourceGuid: { describe: "Provide the source instance GUID(s). Comma-separated for multiple instances (e.g., 'guid1,guid2,guid3'). If not provided, will use AGILITY_GUID from .env file if available.", + // NOTE: an alias matching the option key itself causes yargs to hide the option from --help alias: [ "source-guid", - "sourceGuid", "sourceguid", "source", "SourceGuid", @@ -178,10 +178,9 @@ export const systemArgs = { }, targetGuid: { describe: - "Provide the target instance GUID(s) for sync operations. Comma-separated for multiple instances (e.g., 'guid1,guid2,guid3').", + "Provide the target instance GUID(s) for push/sync operations. Comma-separated for multiple instances (e.g., 'guid1,guid2,guid3'). If not provided, will use AGILITY_TARGET_GUID from .env file if available.", alias: [ "target-guid", - "targetGuid", "targetguid", "target", "TargetGuid", @@ -202,27 +201,30 @@ export const systemArgs = { describe: "For sync commands only: force update existing items in target instance instead of creating new items with -1 IDs. Default: false (safer behavior to prevent overwriting existing content).", type: "boolean" as const, - alias: ["overwrite", "Overwrite", "OVERWRITE"], + alias: ["Overwrite", "OVERWRITE"], default: false, }, force: { describe: "Override target safety conflicts during sync operations. When target instance has changes AND change delta has updates, --force will apply sync changes anyway. Default: false (safer behavior to prevent data loss).", type: "boolean" as const, - alias: ["force", "Force", "FORCE"], + alias: ["Force", "FORCE"], default: false, }, update: { describe: "Controls file downloading behavior. --update=false (default): Skip existing files during download (normal efficient behavior). --update=true: Force download/overwrite existing files and clear sync tokens for complete refresh.", type: "boolean" as const, - alias: ["reset", "Reset", "RESET", "forceUpdate", "ForceUpdate", "FORCEUPDATE"], + // "reset" must not be an alias here — it collides with the separate `reset` option below, + // which hides --reset from --help and overwrites this option's description + alias: ["forceUpdate", "ForceUpdate", "FORCEUPDATE"], default: false, }, reset: { describe: "Nuclear reset option: completely delete instance GUID folder including sync tokens. Forces full fresh download for all SDKs. To reset only Content Sync SDK: manually delete agility-files/GUID/locale/preview/state folder. Default: false.", type: "boolean" as const, + alias: ["Reset", "RESET"], default: false, }, @@ -231,7 +233,7 @@ export const systemArgs = { describe: "Automatically publish content and/or pages after sync completes. Options: 'content' (publish only content), 'pages' (publish only pages), 'both' (publish content and pages). Default: both when flag is provided.", demandOption: false, - alias: ["auto-publish", "autoPublish", "AutoPublish", "AUTO_PUBLISH", "autopublish"], + alias: ["auto-publish", "AutoPublish", "AUTO_PUBLISH", "autopublish"], type: "string" as const, coerce: (value: string | boolean) => { // Handle --autoPublish without value (defaults to 'both') diff --git a/src/index.ts b/src/index.ts index 4c41fdd..8e378e4 100644 --- a/src/index.ts +++ b/src/index.ts @@ -166,14 +166,10 @@ yargs.command({ aliases: ["sync"], describe: "Push your instance using the new 2-pass dependency system.", builder: { - // Override targetGuid to be required for push - targetGuid: { - describe: "Provide the target instance GUID to push your instance to.", - demandOption: true, - type: "string", - }, - // System args (commonly repeated across commands) + // targetGuid is required for push/sync, but is enforced in auth.validateCommand() after + // .env priming so the AGILITY_TARGET_GUID fallback keeps working (yargs demandOption + // would reject the command before the handler can read the .env file) ...systemArgs, }, handler: async function (argv) {