@copado/agentia-cli 0.95.0-alpha.0 → 0.97.0-alpha.0

package/dist/lib/setup-templates.js

@@ -52,6 +52,149 @@ echo ## Running LWC tests
 npx sfdx-lwc-jest --
 if errorlevel 1 exit /b %errorlevel%
 `;
+/** Bundled AGENTS.md template (mirrors docs/AGENTS.sample.md). Used when DEFAULT_AGENTS_MD_URL is unset or download fails. */
+export const BUNDLED_AGENTS_MD = `# Agentia CLI for AI Agents
+
+Use Agentia to manage Copado user stories end-to-end: pick work, prepare a git branch, push changes, submit for review, and promote.
+
+**Prefer the Agentia MCP server when it is available.** If tools such as \`agentia_work_list\`, \`agentia_work_set\`, \`agentia_work_commit\`, \`agentia_work_push\`, and \`agentia_work_submit\` are registered, call those instead of shelling out to the \`agentia\` CLI. Fall back to CLI commands only when MCP is not configured.
+
+When using the CLI, prefer \`--json\` on every command so you can parse structured output instead of terminal tables.
+
+Authentication must already be configured (\`agentia auth set\` / keychain, or local gateway mode). Run from a git repository that is a Copado-managed project.
+
+## Typical workflow
+
+\`\`\`text
+list → get → set → (implement & commit or cloud commit) → push → submit [--done]
+\`\`\`
+
+| Step | MCP tool (preferred) | CLI fallback | Purpose |
+| --- | --- | --- | --- |
+| 1 | \`agentia_work_list\` (\`assignedToMe: true\`) | \`agentia cicd work list --assigned-to-me --json\` | Show user stories assigned to you |
+| 2 | \`agentia_work_get\` | \`agentia cicd work get [id] --json\` | Read user story details (omit id after \`work set\`) |
+| 3 | \`agentia_work_set\` | \`agentia cicd work set <id> --json\` | Mark in progress and prepare the feature branch |
+| 4 | *(your edits + \`git commit\`)* or \`agentia_work_commit\` | *(your edits + \`git commit\`)* or \`agentia cicd work commit --cloud --json\` | Implement the story or create a Copado cloud metadata commit |
+| 5 | \`agentia_work_push\` | \`agentia cicd work push --json\` | Push local Git commits and register them with Copado |
+| 6 | \`agentia_work_submit\` | \`agentia cicd work submit --json\` | Flag ready for review (pipeline quality gates / validation) |
+| 7 | \`agentia_work_submit\` (\`done: true\`) | \`agentia cicd work submit --done --json\` | Promote and deploy to the next stage (Copado UI Submit promote) |
+
+Do not skip \`work set\` before coding. Later steps expect a \`feature/<user-story-name>\` branch and a recorded base branch from \`work set\`.
+
+---
+
+## Commands
+
+CLI examples below are the fallback when MCP is unavailable. MCP tool names and arguments mirror these commands (camelCase args instead of flags).
+
+### \`agentia cicd work list\`
+
+Show user stories. For “assigned to me”, always use:
+
+\`\`\`sh
+agentia cicd work list --assigned-to-me --json
+\`\`\`
+
+Useful filters: \`--status\`, \`--project-name\`, \`--name\`, \`--owned-by-me\`. Do not combine \`--assigned-to-me\` with \`--owned-by-me\` or \`--assignee-id\`.
+
+### \`agentia cicd work get [id]\`
+
+Read full details for one user story. After \`work set\`, omit the ID to use the active work item:
+
+\`\`\`sh
+agentia cicd work get --json
+agentia cicd work get a0SKC000000CmZ2AU --json
+\`\`\`
+
+Use this before starting work to understand title, status, acceptance criteria, and related fields.
+
+### \`agentia cicd work set <id>\`
+
+Flag the user story as the active work item (in progress) and prepare the correct git branch:
+
+\`\`\`sh
+agentia cicd work set a0SKC000000CmZ2AU --json
+# or by name:
+agentia cicd work set US-0001 --json
+\`\`\`
+
+What it does:
+
+1. Calls Copado to set the work item and resolve the base branch
+2. Requires a **clean tracked working tree** (stash or commit first if dirty)
+3. Fetches \`origin/<base-branch>\`
+4. Creates or checks out \`feature/<user-story-name>\`
+5. Records the last work item ID, name, and base branch for later commands
+
+Optional: \`--base-branch <name>\` overrides the base branch from the API.
+
+After success, stay on that feature branch for all implementation commits.
+
+### \`agentia cicd work push\`
+
+Push committed changes to git and register them with Copado:
+
+\`\`\`sh
+agentia cicd work push --json
+\`\`\`
+
+Prerequisites:
+
+- Current branch is \`feature/US-XXXX\` (from \`work set\`)
+- No uncommitted tracked changes (commit first)
+- \`work set\` was run so a base branch is recorded
+
+Locks the tip commit, runs \`git push origin <branch>\`, then registers the commits with Copado.
+
+### \`agentia cicd work commit --cloud\`
+
+Create a Copado cloud commit job for selected metadata:
+
+\`\`\`sh
+agentia cicd work commit --cloud --message "Commit AccountService" --metadata-name AccountService --metadata-type ApexClass --metadata-category SFDX --json
+agentia cicd work commit a0SKC000000CmZ2AU --cloud --file commit-request.json --json
+\`\`\`
+
+Use this when the metadata commit should be performed by Copado rather than by local Git. The command preflights the user story, submits the commit request, and waits for the job by default. For bundled metadata with \`SelectiveCommit\`, include \`--selection\` values for the files inside the bundle. MCP uses camelCase fields such as \`metadataName\`, \`metadataType\`, \`metadataCategory\`, \`selection\`, and \`wait\`. For Salesforce metadata, always set \`--metadata-category SFDX\` or MCP \`metadataCategory: "SFDX"\` (maps to change field \`c\`). Without \`c:SFDX\`, Copado SFDX deploy logs "Salesforce changes not found." and skips the deploy.
+
+### \`agentia cicd work test --local\`
+
+Run local project quality gates without submitting:
+
+\`\`\`sh
+agentia cicd work test --local --json
+agentia cicd work test --local --apex-test-classes=MyTest,OtherTest --json
+\`\`\`
+
+If the project root contains \`${QUALITY_GATES_SCRIPT_UNIX}\` (macOS/Linux) or \`${QUALITY_GATES_SCRIPT_WINDOWS}\` (Windows), that script runs and the command stops on failure. Only \`--local\` is supported for now. Optional \`--apex-test-classes=class1,class2\` is passed to the script as \`AGENTIA_APEX_TEST_CLASSES\` (MCP: \`apexTestClasses\`).
+
+### \`agentia cicd work submit\`
+
+Flag the user story as ready for review. Runs local project quality gates (when present), then pipeline quality gates and validation:
+
+\`\`\`sh
+agentia cicd work submit --json
+agentia cicd work submit --apex-test-classes=MyTest,OtherTest --json
+agentia cicd work submit --skip-local-tests --json
+agentia cicd work submit --done --json
+agentia cicd work submit --done --skip-nested-metadata-detection --json
+\`\`\`
+
+Same branch/clean-tree rules as \`work push\`. If the project root contains \`${QUALITY_GATES_SCRIPT_UNIX}\` (macOS/Linux) or \`${QUALITY_GATES_SCRIPT_WINDOWS}\` (Windows), that script runs first and submit stops on failure (same local gates as \`work test --local\`). Use \`--apex-test-classes=class1,class2\` to pass Apex test classes to the script as \`AGENTIA_APEX_TEST_CLASSES\` (MCP: \`apexTestClasses\`). Use \`--skip-local-tests\` to skip local gates. After that, submit counts commits since \`lastBaseBranch\` before checking origin. No commits is an error unless the Story has a \`Data Set - Salesforce\` or \`Data Template - Salesforce\` deployment step. When commits exist, unpushed work is still pushed even if those data steps are present, then submit continues. With \`--done\` (MCP: \`done\`), submit matches Copado UI Submit when promoting (validate=false / headless work/done) and honors \`--skip-nested-metadata-detection\`. Prefer \`submit --done\` over the compatibility alias \`cicd work done\`.
+
+---
+
+## Agent rules
+
+1. **Prefer MCP over CLI.** When Agentia MCP tools are available, use them instead of running \`agentia\` in the shell.
+2. **Discover before acting.** List assigned stories, then \`get\` the chosen ID, then \`set\` before editing files.
+3. **One story, one feature branch.** Do not mix unrelated commits on the same \`feature/US-XXXX\` branch.
+4. **Choose the right commit path.** Use normal \`git add\` / \`git commit\` followed by \`agentia_work_push\` for local Git work. Use \`agentia_work_commit\` / \`agentia cicd work commit --cloud\` for Copado cloud metadata commits.
+5. **Keep the tree clean** before \`set\`, \`push\`, and \`submit\`. Those steps fail if tracked changes are pending.
+6. **Prefer structured results.** MCP returns JSON; for CLI, use \`--json\` and do not scrape human table output.
+7. **Order matters.** \`set\` → local commit or cloud commit → \`push\` when local Git commits exist → \`submit\` (optionally \`--done\`). \`submit\` counts commits since \`lastBaseBranch\` before checking origin; it auto-pushes only when that range is non-empty and origin is behind. A Data Set or Data Template deployment step can waive the empty-history error, but not push validation when commits exist. \`set\` is still required first.
+8. **Confirm intent for \`submit --done\`.** Promotion deploys to the next stage; do not run it unless the user asked to promote/deploy.
+`;
 export function qualityGatesExplanation(bin = 'agentia') {
     return [
         'Local quality gates:',

package/dist/lib/setup-templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup-templates.js","sourceRoot":"","sources":["../../src/lib/setup-templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,yBAAyB,EAAE,4BAA4B,EAAC,MAAM,0BAA0B,CAAA;AAEhG,MAAM,CAAC,MAAM,uBAAuB,GAAG,2BAA2B,CAAA;AAClE,MAAM,CAAC,MAAM,2BAA2B,GAAG,gCAAgC,CAAA;AAC3E,MAAM,CAAC,MAAM,yBAAyB,GAAG,8BAA8B,CAAA;AAEvE,iGAAiG;AACjG,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,CAAU,CAAA;AAE1G,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuBxC,CAAA;AAED,MAAM,CAAC,MAAM,4BAA4B,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuB3C,CAAA;AAED,MAAM,UAAU,uBAAuB,CAAC,GAAG,GAAG,SAAS;IACrD,OAAO;QACL,sBAAsB;QACtB,OAAO,yBAAyB,yBAAyB,4BAA4B,cAAc;QACnG,OAAO,GAAG,0BAA0B,GAAG,uEAAuE;QAC9G,WAAW,GAAG,qEAAqE;QACnF,mFAAmF;QACnF,8GAA8G;KAC/G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC"}
+{"version":3,"file":"setup-templates.js","sourceRoot":"","sources":["../../src/lib/setup-templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,yBAAyB,EAAE,4BAA4B,EAAC,MAAM,0BAA0B,CAAA;AAEhG,MAAM,CAAC,MAAM,uBAAuB,GAAG,2BAA2B,CAAA;AAClE,MAAM,CAAC,MAAM,2BAA2B,GAAG,gCAAgC,CAAA;AAC3E,MAAM,CAAC,MAAM,yBAAyB,GAAG,8BAA8B,CAAA;AAEvE,iGAAiG;AACjG,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,CAAU,CAAA;AAE1G,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuBxC,CAAA;AAED,MAAM,CAAC,MAAM,4BAA4B,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuB3C,CAAA;AAED,8HAA8H;AAC9H,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAiHA,yBAAyB,yBAAyB,4BAA4B;;;;;;;;;;;;;;gFAc/B,yBAAyB,yBAAyB,4BAA4B;;;;;;;;;;;;;;CAc7J,CAAA;AAED,MAAM,UAAU,uBAAuB,CAAC,GAAG,GAAG,SAAS;IACrD,OAAO;QACL,sBAAsB;QACtB,OAAO,yBAAyB,yBAAyB,4BAA4B,cAAc;QACnG,OAAO,GAAG,0BAA0B,GAAG,uEAAuE;QAC9G,WAAW,GAAG,qEAAqE;QACnF,mFAAmF;QACnF,8GAA8G;KAC/G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC"}