docs: rewrite package READMEs#452
Conversation
Reworks the Vlocode VS Code extension README to lead with a feature overview and Marketplace-friendly raw image URLs, with deeper sections following. Adds READMEs for @vlocode/core, @vlocode/salesforce and @vlocode/util, expands the stub READMEs for @vlocode/vlocity and @vlocode/omniscript, and cleans up typos and structure in the existing ones. The monorepo root README gets a consolidated package table. https://claude.ai/code/session_016d7mmn49VLtmX3E2CWUAT9
There was a problem hiding this comment.
Pull request overview
Documentation-focused update that refreshes the monorepo and package READMEs to better explain Vlocode’s VS Code extension and the underlying @vlocode/* libraries, with more structured sections and Marketplace-friendly image URLs.
Changes:
- Rewrites the VS Code extension README to lead with a clearer feature overview and raw GitHub image URLs suitable for the Marketplace.
- Adds/expands package-level READMEs across the monorepo (new READMEs for core/util/salesforce; expanded stubs for others).
- Updates the root README with a consolidated packages table and refreshed setup/testing/release notes.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Refreshes monorepo landing page, package table, and contributor setup/testing/release docs. |
| packages/vscode-webviews/README.md | Clarifies purpose of the internal Angular webviews package and its build outputs. |
| packages/vscode-extension/README.md | Major rewrite for Marketplace/readability: highlights features, workflows, screenshots, and settings. |
| packages/vlocity/README.md | Expands package overview for shared Vlocity/OmniStudio domain layer. |
| packages/vlocity-deploy/README.md | Reworks library README to emphasize differentiators, quick start, options, and extensibility hooks. |
| packages/util/README.md | Introduces a new README describing utilities plus a few usage examples. |
| packages/sass/README.md | Updates README to describe the SCSS/SESS transpiler and provide an example. |
| packages/salesforce/README.md | Introduces a new README describing the high-level Salesforce client and examples. |
| packages/omniscript/README.md | Expands README for the OmniScript → LWC compiler with examples. |
| packages/core/README.md | Introduces a new README for IoC/logging/filesystem foundation package with examples. |
| packages/cli/README.md | Reworks CLI README with installation, quick start, command help, and updated FAQ. |
| packages/apex/README.md | Updates README for the ANTLR-based APEX/SOQL parser with corrected examples and structure. |
| ## Setup development environment | ||
|
|
||
| Vlocode uses `pnpm` as package manager and lerna release manager. To setup a developer environment for Vlocode you should always use the latest LTS version of node with corepack. VScode is the preferred IDE for developing and debugging. | ||
| Vlocode uses `pnpm` as package manager and `lerna-lite` for releases. Use the latest LTS version of Node with corepack. VS Code is the preferred IDE. |
|
|
||
| The foundation that the rest of the `@vlocode/*` libraries (and the Vlocode VS Code extension) are built on. It bundles a small dependency-injection container, a configurable logging framework and a minimal filesystem abstraction that works both inside VS Code and in plain Node.js. | ||
|
|
||
| `@vlocode/core` has a single peer dependency on the matching version of [`@vlocode/util`](../util). |
| import { SalesforceService } from '@vlocode/salesforce'; | ||
|
|
||
| const result = await salesforce.executeAnonymous(` | ||
| List<Account> accs = [SELECT Id, Name FROM Account LIMIT 5]; | ||
| for (Account a : accs) System.debug(a.Name); | ||
| `); |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cbb08a9fdf
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| await sf.connect({ sfdxUsername: 'my-scratch-alias' }); | ||
|
|
||
| const accounts = await sf.query<{ Id: string; Name: string }>( | ||
| 'SELECT Id, Name FROM Account WHERE Industry = :industry LIMIT 10', | ||
| { industry: 'Technology' } |
There was a problem hiding this comment.
This query example cannot be copied into a consumer project: SalesforceService is constructed from an injected SalesforceConnectionProvider and does not expose a connect() method, and its query() method only accepts the query object/string (no bind-variables argument). Users following this SFDX-alias example will hit TypeScript/runtime failures before they can run a query, so the README should show the actual provider/DI setup and query signature.
Useful? React with 👍 / 👎.
| import { SalesforceDeployService, PackageBuilder } from '@vlocode/salesforce'; | ||
|
|
||
| const pkg = new PackageBuilder({ apiVersion: '60.0' }) | ||
| .addFiles(['./force-app/main/default/classes/MyClass.cls']) | ||
| .build(); |
There was a problem hiding this comment.
The metadata-deploy example imports PackageBuilder, but the package exports SalesforcePackageBuilder, and addFiles()/build() are async methods rather than a synchronous chain. As written, anyone following this README gets an unexported symbol plus a Promise where the example expects a package, so the snippet should be updated to the actual SalesforcePackageBuilder flow.
Useful? React with 👍 / 👎.
| const bundle = await compiler.compile({ | ||
| type: 'Account', | ||
| subType: 'Onboarding', | ||
| language: 'English', | ||
| definition, // OmniScript definition JSON |
There was a problem hiding this comment.
OmniScriptLwcCompiler.compile() takes a full OmniScriptDefinition as its first argument and reads fields such as propSetMap, bpType, bpSubType, and bpLang; it does not accept a wrapper object with type, subType, language, and definition. Following this example will throw the compiler's missing-propSetMap error instead of generating an LWC.
Useful? React with 👍 / 👎.
| await activator.activate({ | ||
| connection, // @vlocode/salesforce connection | ||
| filter: 'Account/Onboarding/*', // type/subType/language wildcard | ||
| parallel: 4, |
There was a problem hiding this comment.
OmniScriptActivator.activate() activates one script identified by an id or { type, subType, language } plus an options object; it does not accept a connection/filter/parallel job object. A user copying this bulk-activation example will pass none of the fields used by OmniScriptAccess.find() and fail to find the intended script, so the README should either show the single-script API or point users to the CLI for wildcard/parallel activation.
Useful? React with 👍 / 👎.
| ```ts | ||
| import { sfdx } from '@vlocode/util'; | ||
|
|
||
| const connection = await sfdx.getConnection('my-scratch-alias'); |
There was a problem hiding this comment.
The sfdx namespace does not export getConnection; the available helpers in packages/util/src/sfdx.ts are things like getOrg() and the deprecated getSfdxForceConnection(). This is the only SFDX connection example in the util README, so consumers following it will immediately get Property 'getConnection' does not exist instead of a working connection.
Useful? React with 👍 / 👎.
| const compiler = new SassCompiler(); | ||
| const css = await compiler.compileFile('./templates/MyTemplate/style.scss'); |
There was a problem hiding this comment.
SassCompiler is an abstract interface with only compile(source, options), and there is no compileFile() implementation in this package. This example therefore cannot compile or run as written; it should instantiate/use a concrete implementation (or the DI-provided compiler) and pass the file contents to compile().
Useful? React with 👍 / 👎.
CLI README now documents all seven commands (deploy, activate, export, bulk-export, convert, build-export-definitions, impacted-tests) with their full option set, and pulls the shared global / Salesforce connection options into one table so they are not repeated per command. Extension README gets a few polish passes: clearer additive-to-SFDX framing, the SFDX-auth advantage promoted into "Why Vlocode?", re-ordered images so each demo matches the section it sits under, a new REST-from-.sfhttp example, and more conspicuous screenshot placeholders for the OmniScript LWC and visual-editor sections. https://claude.ai/code/session_016d7mmn49VLtmX3E2CWUAT9
|
Reworks the Vlocode VS Code extension README to lead with a feature
overview and Marketplace-friendly raw image URLs, with deeper sections
following. Adds READMEs for @vlocode/core, @vlocode/salesforce and
@vlocode/util, expands the stub READMEs for @vlocode/vlocity and
@vlocode/omniscript, and cleans up typos and structure in the existing
ones. The monorepo root README gets a consolidated package table.
https://claude.ai/code/session_016d7mmn49VLtmX3E2CWUAT9