Merge branch 'main' into mdonnalley/tap-format

.github/workflows/create-github-release.yml

@@ -6,12 +6,12 @@ on:
       - main
       - prerelease/**
     tags-ignore:
-      - "*"
+      - '*'
   workflow_dispatch:
     inputs:
       prerelease:
         type: string
-        description: "Name to use for the prerelease: beta, dev, etc. NOTE: If this is already set in the package.json, it does not need to be passed in here."
+        description: 'Name to use for the prerelease: beta, dev, etc. NOTE: If this is already set in the package.json, it does not need to be passed in here.'
 
 jobs:
   release:
@@ -23,10 +23,10 @@ jobs:
       # However, if this is a manual release (workflow_dispatch), then we want to disable skip-on-empty
       # This helps recover from forgetting to add semantic commits ('fix:', 'feat:', etc.)
       skip-on-empty: ${{ github.event_name == 'push' }}
-  # docs:
-  #   # Most repos won't use this
-  #   # Depends on the 'release' job to avoid git collisions, not for any functionality reason
-  #   needs: release
-  #   secrets: inherit
-  #   if: ${{ github.ref_name == 'main' }}
-  #   uses: salesforcecli/github-workflows/.github/workflows/publishTypedoc.yml@main
+  docs:
+    # Most repos won't use this
+    # Depends on the 'release' job to avoid git collisions, not for any functionality reason
+    needs: release
+    secrets: inherit
+    if: ${{ github.ref_name == 'main' }}
+    uses: salesforcecli/github-workflows/.github/workflows/publishTypedoc.yml@main

CHANGELOG.md

@@ -1,165 +1,122 @@
-## [0.4.2](https://github.com/forcedotcom/agents/compare/0.4.1...0.4.2) (2024-12-10)
-
+## [0.4.5](https://github.com/forcedotcom/agents/compare/0.4.4...0.4.5) (2024-12-14)
 
 ### Bug Fixes
 
-* retrieve GenAiPlugins too ([1d461a2](https://github.com/forcedotcom/agents/commit/1d461a27a713212bb2f033046a71d47d3be21204))
+- **deps:** bump @salesforce/source-deploy-retrieve ([a282749](https://github.com/forcedotcom/agents/commit/a28274962414ee576e9da3e3ba8df21eab3ab9ad))
 
+## [0.4.4](https://github.com/forcedotcom/agents/compare/0.4.3...0.4.4) (2024-12-13)
 
+## [0.4.3](https://github.com/forcedotcom/agents/compare/0.4.2...0.4.3) (2024-12-13)
 
-## [0.4.1](https://github.com/forcedotcom/agents/compare/0.4.0...0.4.1) (2024-12-10)
-
+## [0.4.2](https://github.com/forcedotcom/agents/compare/0.4.1...0.4.2) (2024-12-10)
 
 ### Bug Fixes
 
-* agent create working ([1a57a90](https://github.com/forcedotcom/agents/commit/1a57a90630a043ad6294a9895145fa4fd7442330))
-* agent.create WIP ([836f6db](https://github.com/forcedotcom/agents/commit/836f6db06cd529d0482b9fa9630b9314892b799f))
-* emit lifecycle events ([c3bba31](https://github.com/forcedotcom/agents/commit/c3bba3100f953a320efb4542f0ecc031a5d41179))
+- retrieve GenAiPlugins too ([1d461a2](https://github.com/forcedotcom/agents/commit/1d461a27a713212bb2f033046a71d47d3be21204))
+
+## [0.4.1](https://github.com/forcedotcom/agents/compare/0.4.0...0.4.1) (2024-12-10)
 
+### Bug Fixes
 
+- agent create working ([1a57a90](https://github.com/forcedotcom/agents/commit/1a57a90630a043ad6294a9895145fa4fd7442330))
+- agent.create WIP ([836f6db](https://github.com/forcedotcom/agents/commit/836f6db06cd529d0482b9fa9630b9314892b799f))
+- emit lifecycle events ([c3bba31](https://github.com/forcedotcom/agents/commit/c3bba3100f953a320efb4542f0ecc031a5d41179))
 
 # [0.4.0](https://github.com/forcedotcom/agents/compare/0.3.1...0.4.0) (2024-12-10)
 
-
 ### Features
 
-* junit result formatter ([42ff64b](https://github.com/forcedotcom/agents/commit/42ff64bd855d4de5e4f6585ab5c141816d1bccf3))
-
-
+- junit result formatter ([42ff64b](https://github.com/forcedotcom/agents/commit/42ff64bd855d4de5e4f6585ab5c141816d1bccf3))
 
 ## [0.3.1](https://github.com/forcedotcom/agents/compare/0.3.0...0.3.1) (2024-12-07)
 
-
 ### Bug Fixes
 
-* **deps:** bump @oclif/table from 0.3.3 to 0.3.5 ([49ce6d5](https://github.com/forcedotcom/agents/commit/49ce6d58fe3a433a14bad20d38240180aaff864f))
-
-
+- **deps:** bump @oclif/table from 0.3.3 to 0.3.5 ([49ce6d5](https://github.com/forcedotcom/agents/commit/49ce6d58fe3a433a14bad20d38240180aaff864f))
 
 # [0.3.0](https://github.com/forcedotcom/agents/compare/0.2.4...0.3.0) (2024-12-05)
 
-
 ### Features
 
-* export test formatters ([b5f26df](https://github.com/forcedotcom/agents/commit/b5f26df835c3a08e9065f327afc4a6bc1997c9ab))
-
-
+- export test formatters ([b5f26df](https://github.com/forcedotcom/agents/commit/b5f26df835c3a08e9065f327afc4a6bc1997c9ab))
 
 ## [0.2.4](https://github.com/forcedotcom/agents/compare/0.2.3...0.2.4) (2024-12-03)
 
-
 ### Bug Fixes
 
-* add doc for agent class ([5208345](https://github.com/forcedotcom/agents/commit/52083450e7eff71e1cc3caf570abd18939317d9a))
-
-
+- add doc for agent class ([5208345](https://github.com/forcedotcom/agents/commit/52083450e7eff71e1cc3caf570abd18939317d9a))
 
 ## [0.2.3](https://github.com/forcedotcom/agents/compare/0.2.2...0.2.3) (2024-12-03)
 
-
-
 ## [0.2.2](https://github.com/forcedotcom/agents/compare/0.2.1...0.2.2) (2024-12-02)
 
-
 ### Bug Fixes
 
-* export more types ([0a1d408](https://github.com/forcedotcom/agents/commit/0a1d408dd0d815b36509d5b5fe343e7e0817d1a2))
-
-
+- export more types ([0a1d408](https://github.com/forcedotcom/agents/commit/0a1d408dd0d815b36509d5b5fe343e7e0817d1a2))
 
 ## [0.2.1](https://github.com/forcedotcom/agents/compare/0.2.0...0.2.1) (2024-12-02)
 
-
 ### Bug Fixes
 
-* update return type on start ([c14e8c4](https://github.com/forcedotcom/agents/commit/c14e8c41c3180dad1df807a3531e944b89cce229))
-
-
+- update return type on start ([c14e8c4](https://github.com/forcedotcom/agents/commit/c14e8c41c3180dad1df807a3531e944b89cce229))
 
 # [0.2.0](https://github.com/forcedotcom/agents/compare/0.1.6...0.2.0) (2024-12-02)
 
-
 ### Bug Fixes
 
-* add polling lifecycle events ([695fd08](https://github.com/forcedotcom/agents/commit/695fd086865c60850d53aa2753686ea5aeef2d4a))
-* use sf-plugins-core for making table ([97eaa63](https://github.com/forcedotcom/agents/commit/97eaa633fd739c214029ce0fb1dbd521f220c5ae))
-
+- add polling lifecycle events ([695fd08](https://github.com/forcedotcom/agents/commit/695fd086865c60850d53aa2753686ea5aeef2d4a))
+- use sf-plugins-core for making table ([97eaa63](https://github.com/forcedotcom/agents/commit/97eaa633fd739c214029ce0fb1dbd521f220c5ae))
 
 ### Features
 
-* add cancel method ([8371f9f](https://github.com/forcedotcom/agents/commit/8371f9fd735bfd7e12dd4a95419e321bb34cf465))
-* mock agent testing ([8df61a9](https://github.com/forcedotcom/agents/commit/8df61a9fba8005d0823bba5ce5f14d3ab5a5c12e))
-* mocked agent testing ([334988d](https://github.com/forcedotcom/agents/commit/334988d753f942fbfecdaa776e2285c51b81ebf5))
-* poll both status and details ([61b03dc](https://github.com/forcedotcom/agents/commit/61b03dcba132ed07df194953c850595771f3ccff))
-
-
+- add cancel method ([8371f9f](https://github.com/forcedotcom/agents/commit/8371f9fd735bfd7e12dd4a95419e321bb34cf465))
+- mock agent testing ([8df61a9](https://github.com/forcedotcom/agents/commit/8df61a9fba8005d0823bba5ce5f14d3ab5a5c12e))
+- mocked agent testing ([334988d](https://github.com/forcedotcom/agents/commit/334988d753f942fbfecdaa776e2285c51b81ebf5))
+- poll both status and details ([61b03dc](https://github.com/forcedotcom/agents/commit/61b03dcba132ed07df194953c850595771f3ccff))
 
 ## [0.1.6](https://github.com/forcedotcom/agents/compare/0.1.5...0.1.6) (2024-11-16)
 
-
 ### Bug Fixes
 
-* **deps:** bump cross-spawn from 7.0.3 to 7.0.5 ([7f43cc7](https://github.com/forcedotcom/agents/commit/7f43cc706b848fd54c88d04bee2c0b7b632d7e76))
-
-
+- **deps:** bump cross-spawn from 7.0.3 to 7.0.5 ([7f43cc7](https://github.com/forcedotcom/agents/commit/7f43cc706b848fd54c88d04bee2c0b7b632d7e76))
 
 ## [0.1.5](https://github.com/forcedotcom/agents/compare/0.1.4...0.1.5) (2024-11-16)
 
-
 ### Bug Fixes
 
-* **deps:** bump @salesforce/core from 8.6.3 to 8.8.0 ([193237b](https://github.com/forcedotcom/agents/commit/193237b5dbbe7ce1ee596a3b7305b5602d0883f8))
-
-
+- **deps:** bump @salesforce/core from 8.6.3 to 8.8.0 ([193237b](https://github.com/forcedotcom/agents/commit/193237b5dbbe7ce1ee596a3b7305b5602d0883f8))
 
 ## [0.1.4](https://github.com/forcedotcom/agents/compare/0.1.3...0.1.4) (2024-11-12)
 
-
 ### Bug Fixes
 
-* do not append spec in name ([284d5d5](https://github.com/forcedotcom/agents/commit/284d5d56ed99c67b93a65904a00fdb00a2552a0e))
-
-
+- do not append spec in name ([284d5d5](https://github.com/forcedotcom/agents/commit/284d5d56ed99c67b93a65904a00fdb00a2552a0e))
 
 ## [0.1.3](https://github.com/forcedotcom/agents/compare/0.1.2...0.1.3) (2024-11-12)
 
-
 ### Bug Fixes
 
-* use latest ([92ecbba](https://github.com/forcedotcom/agents/commit/92ecbbabc403fe57bf4069f9928b029d23db7a16))
-
-
+- use latest ([92ecbba](https://github.com/forcedotcom/agents/commit/92ecbbabc403fe57bf4069f9928b029d23db7a16))
 
 ## [0.1.2](https://github.com/forcedotcom/agents/compare/0.1.1...0.1.2) (2024-11-12)
 
-
 ### Bug Fixes
 
-* publish to preview ([3f5ccb6](https://github.com/forcedotcom/agents/commit/3f5ccb687017186eb29b8b18c7fdce33daee1f70))
-
-
+- publish to preview ([3f5ccb6](https://github.com/forcedotcom/agents/commit/3f5ccb687017186eb29b8b18c7fdce33daee1f70))
 
 ## [0.1.1](https://github.com/forcedotcom/agents/compare/0.1.0...0.1.1) (2024-11-10)
 
-
 ### Bug Fixes
 
-* export Agent class ([6c42b63](https://github.com/forcedotcom/agents/commit/6c42b63bbe9a5a5cf6fa0cea8f5649d07aaa6adc))
-
-
+- export Agent class ([6c42b63](https://github.com/forcedotcom/agents/commit/6c42b63bbe9a5a5cf6fa0cea8f5649d07aaa6adc))
 
 # [0.1.0](https://github.com/forcedotcom/agents/compare/0c5d8d6ab9e9a8470c7192a56350567882a3017b...0.1.0) (2024-11-09)
 
-
 ### Bug Fixes
 
-* improve types and linting ([d5a6cb3](https://github.com/forcedotcom/agents/commit/d5a6cb3348e63d52e10540e99cf509be64a26649))
-* revise readme and version ([f690b7f](https://github.com/forcedotcom/agents/commit/f690b7f8a911315f467f00f5f533e22e92c69a9e))
-
+- improve types and linting ([d5a6cb3](https://github.com/forcedotcom/agents/commit/d5a6cb3348e63d52e10540e99cf509be64a26649))
+- revise readme and version ([f690b7f](https://github.com/forcedotcom/agents/commit/f690b7f8a911315f467f00f5f533e22e92c69a9e))
 
 ### Features
 
-* add initial agent job spec create and mock ([0c5d8d6](https://github.com/forcedotcom/agents/commit/0c5d8d6ab9e9a8470c7192a56350567882a3017b))
-
-
-
+- add initial agent job spec create and mock ([0c5d8d6](https://github.com/forcedotcom/agents/commit/0c5d8d6ab9e9a8470c7192a56350567882a3017b))

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+## Contributing
+
+1. Familiarize yourself with the codebase by reading the docs, in
+   particular the [developing](./contributing/developing.md) doc.
+1. Create a new issue before starting your project so that we can keep track of
+   what you're trying to add/fix. That way, we can also offer suggestions or
+   let you know if there is already an effort in progress.
+1. Fork this repository.
+1. Set up your environment using the information in the [developing](./contributing/developing.md) doc.
+1. Create a _topic_ branch in your fork based on the correct branch (usually the **develop** branch, see [Branches section](./contributing/developing.md)). Note: this step is recommended but technically not required if contributing using a fork.
+1. Edit the code in your fork.
+1. Sign the CLA (see [CLA](#cla)).
+1. Send us a pull request when you're done. We'll review your code, suggest any
+   needed changes, and merge it in.
+
+## Pull Requests
+
+### Committing
+
+We enforce commit message format. We recommend using [commitizen](https://github.com/commitizen/cz-cli) by installing it with `npm install -g commitizen` and running `npm run commit-init`. When you commit, we recommend that you use `npm run commit`, which prompts you with a series of questions to format the commit message. Or you can use our VS Code Task `Commit`.
+
+The commit message format that we expect is: `type: commit message`. Valid types are: feat, fix, improvement, docs, style, refactor, perf, test, build, ci, chore and revert.
+
+Before commit and push, Husky runs several hooks to ensure the commit message is in the correct format and that everything lints and compiles properly.
+
+### CLA
+
+External contributors are required to sign a Contributor's License
+Agreement. You can do so by going to <https://cla.salesforce.com/sign-cla>.
+
+### Merging Pull Requests
+
+Pull request merging is restricted to squash and merge only.
+
+## Helpful Resources
+
+- All of the files in the [contributing](./contributing) folder have useful information, particularly the previously-mentioned [developing](./contributing/developing.md) doc.
+- The [Source-Deploy-Retrieve Handbook](./HANDBOOK.md) contains an overview of all of the code in this project. This easy-to-read document can serve as an introduction and overview of the code and concepts, or as a reference for what a given module accomplishes and why it was designed.
+- The [API documentation](https://forcedotcom.github.io/source-deploy-retrieve/) has details on using the classes and methods.

DEVELOPING.md

@@ -0,0 +1,59 @@
+# Developing
+
+## Getting Started
+
+Clone the project and `cd` into it:
+
+```
+git clone [email protected]:forcedotcom/agents.git
+cd agents
+```
+
+Ensure you have [Yarn](https://yarnpkg.com/) installed, then run:
+
+```
+yarn install
+yarn build
+```
+
+## Branches
+
+- Our released (_production_) branch is `main`
+- Our work happens in _topic_ branches (feature and/or bug fix)
+  - These branches are based on `main` and can live in forks for external contributors or within this repository for authors
+  - Be sure to prefix branches in this repository with `<developer-name>/`
+  - Be sure to keep branches up-to-date using `rebase`
+
+## Testing
+
+### Running the test suite
+
+Runs the suite and output code coverage as a text summary:
+
+```
+yarn test
+```
+
+Utilize the `Run Tests` VS Code debugger configuration to run the test suite with the debugger enabled.
+
+### Testing in another package
+
+To test the library in another local package, you can link it to such module so any changes that are built will be automatically present without reinstalling:
+
+```
+yarn local:link /path/to/other/project
+```
+
+to unlink the library:
+
+```
+yarn local:unlink /path/to/other/project
+```
+
+### Testing with the NPM artifact
+
+The library can also be installed to another local project as a regular NPM module. This is useful for manually testing the package that will be deployed to NPM. Use this instead of the linking process that's described under Development to QA changes before they are published:
+
+```
+yarn local:install /path/to/other/package
+```

README.md

@@ -1,13 +1,40 @@
-# Salesforce Agents - UNDER DEVELOPMENT
+# Salesforce Agents
 
-### THIS LIBRARY IS UNDER DEVELOPMENT AND IS NOT MEANT FOR PRODUCTION USAGE.
+---
+
+### :warning: THIS LIBRARY IS UNDER DEVELOPMENT AND IS NOT MEANT FOR PRODUCTION USAGE. :warning:
+
+---
 
 [![NPM](https://img.shields.io/npm/v/@salesforce/agents.svg?label=@salesforce/agents)](https://www.npmjs.com/package/@salesforce/agents) [![Downloads/week](https://img.shields.io/npm/dw/@salesforce/agents.svg)](https://npmjs.org/package/@salesforce/agents) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/forcedotcom/agents/main/LICENSE.txt)
 
-## Description
+## Introduction
+
+A Typescript toolkit for working with Salesforce Agentforce Agents. Built to support the Salesforce CLI, VSCode Extensions, DevOps Center, and any other node/typescript projects aimed at Agents.
 
-A TypeScript library for working with Salesforce Agents.
+## Features
+
+- Create Agents
+- Create Agent Specs
+- Interact with Agents
+- Run Agent Tests
 
 ## Usage
 
-TBD
+Install the package:
+
+```
+npm install @salesforce/agents
+```
+
+See [API Docs](https://forcedotcom.github.io/agents)
+
+## Contributing
+
+See [CONTRIBUTING](./CONTRIBUTING.md) for details on how to contribute to the library.
+
+See [DEVELOPING](./DEVELOPING.md) for details on building and testing the library locally.
+
+## Publishing
+
+`@salesforce/agents` publishes when changes are merged into `main`. The version is bumped per the rules of the release orb and [standard-version](https://github.com/conventional-changelog/standard-version).

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/agents",
   "description": "Client side APIs for working with Salesforce agents",
-  "version": "0.4.2",
+  "version": "0.4.5",
   "license": "BSD-3-Clause",
   "author": "Salesforce",
   "main": "lib/index",
@@ -15,7 +15,7 @@
     "@salesforce/core": "^8.8.0",
     "@salesforce/kit": "^3.2.3",
     "@salesforce/sf-plugins-core": "^12.1.0",
-    "@salesforce/source-deploy-retrieve": "^12.10.2",
+    "@salesforce/source-deploy-retrieve": "^12.10.3",
     "fast-xml-parser": "^4",
     "nock": "^13.5.6"
   },