Skip to content

Add instance management commands and easy setup#98

Merged
clavery merged 8 commits intomainfrom
feature/instance-management
Feb 12, 2026
Merged

Add instance management commands and easy setup#98
clavery merged 8 commits intomainfrom
feature/instance-management

Conversation

@clavery
Copy link
Copy Markdown
Collaborator

@clavery clavery commented Jan 31, 2026

TODO: setup cli or something for initial setup (perhaps trigger when no config can be sourced and setup is run 🤔 )

Summary

  • Rename setup configsetup inspect (with backward-compatible alias)
  • Add setup instance list to view all configured instances
  • Add setup instance create with interactive prompts for creating instance configs
  • Add setup instance remove to delete instance configurations
  • Add setup instance set-active to set the default instance

setup instance create improvements

  • Accepts a full URL or plain hostname (auto-extracts hostname from URLs)
  • Auth choices renamed for clarity: "WebDAV (username/password or access key)" and "API Client (OAuth client credentials)"
  • Password prompt includes a link to the Business Manager access keys page
  • Client secret is optional (supports user auth / implicit flow)
  • Auto-detects active code version via OCAPI when OAuth credentials are provided, offered as default
  • Prompts for code version after auth collection (so detection can use credentials)

setup instance set-active improvements

  • Name argument is now optional; when omitted, shows a searchable instance picker
  • Current active instance sorts to the top of the list

Architecture

Two Capabilities Model

The design separates two distinct capabilities that config sources can provide:

Capability Purpose Example Sources
Instance Source Stores full instance config (hostname, name, code-version) dw.json, global registry, cloud config
Credential Source Stores secrets only, linked by instance name Keychain plugin, Vault plugin

At resolution time, values merge: dw.json provides hostname + keychain provides password.

ConfigSource Interface Extension

Sources can now implement optional instance management methods:

interface ConfigSource {
  // Existing
  name: string;
  priority?: number;
  load(options: ResolveConfigOptions): ConfigLoadResult | undefined;

  // Instance Management (for dw.json-style sources)
  listInstances?(options?: ResolveConfigOptions): InstanceInfo[];
  createInstance?(options: CreateInstanceOptions & ResolveConfigOptions): void;
  removeInstance?(name: string, options?: ResolveConfigOptions): void;
  setActiveInstance?(name: string, options?: ResolveConfigOptions): void;

  // Credential Storage (for keychain-style sources)
  credentialFields?: (keyof NormalizedConfig)[];
  storeCredential?(instanceName: string, field: keyof NormalizedConfig, value: string, options?: ResolveConfigOptions): void;
  removeCredential?(instanceName: string, field: keyof NormalizedConfig, options?: ResolveConfigOptions): void;
}

Plugin Extensibility

Plugins can implement these methods to:

  1. Provide instance storage - Store instances in alternative locations (cloud config, global registry)
  2. Provide credential storage - Securely store secrets in keychains, vaults, etc.
  3. Aggregate across sources - InstanceManager class aggregates listInstances() from all sources

Example plugin implementation:

// A keychain plugin can implement:
class KeychainSource implements ConfigSource {
  name = 'keychain';
  credentialFields = ['password', 'clientSecret'];
  
  storeCredential(instanceName, field, value) {
    // Store in OS keychain keyed by instance name
  }
  
  load(options) {
    // Load credentials from keychain for the requested instance
  }
}

This PR implements DwJsonSource as the first instance source. The InstanceManager service aggregates instances from all sources that implement listInstances().

Implementation

  • Extended ConfigSource interface with optional instance management and credential storage methods
  • Implemented CRUD operations in DwJsonSource for managing the configs[] array in dw.json
  • Added InstanceManager service class to aggregate across multiple sources
  • Added mapNormalizedConfigToDwJson() function for reverse mapping
  • Exported DwJsonSource class for direct use by plugins

Test plan

  • Unit tests for dw-json CRUD functions
  • Unit tests for DwJsonSource instance methods
  • Existing tests updated for rename (setup config → setup inspect)
  • Manual testing of CLI commands:
    b2c setup inspect
    b2c setup instance list
    b2c setup instance create staging --hostname staging.example.com
    b2c setup instance set-active staging
    b2c setup instance remove staging --force

- Rename `setup config` to `setup inspect`
- Add `setup instance list` to view configured instances
- Add `setup instance create` with interactive prompts
- Add `setup instance remove` to delete instances
- Add `setup instance set-active` to set default instance

Extends ConfigSource interface with optional instance management
methods and implements CRUD operations in DwJsonSource for
managing the dw.json configs array.
@clavery clavery changed the title Add instance management commands Add instance management commands and easy setup Jan 31, 2026
- Update b2c-config skill with new command name and instance management docs
- Fix reference in b2c-custom-api-development skill
Add documentation for the new optional ConfigSource methods:
- listInstances, createInstance, removeInstance, setActiveInstance
- credentialFields, storeCredential, removeCredential

These enable plugins to provide custom instance storage (cloud config,
global registry) and secure credential storage (keychain, vault).
…gement

# Conflicts:
#	packages/b2c-cli/src/commands/setup/inspect.ts
#	packages/b2c-cli/test/commands/setup/inspect.test.ts
#	packages/b2c-tooling-sdk/test/config/dw-json.test.ts
#	plugins/b2c/skills/b2c-custom-api-development/SKILL.md
#	skills/b2c-cli/skills/b2c-config/SKILL.md
- Accept URL or hostname in create command (auto-extracts hostname)
- Rename auth choices: WebDAV, API Client; show access key URL
- Make client secret optional (supports user auth flow)
- Auto-detect active code version via OCAPI when OAuth is configured
- Add searchable instance picker to set-active when name omitted
@clavery clavery marked this pull request as ready for review February 12, 2026 22:10
@clavery clavery merged commit 91593f2 into main Feb 12, 2026
3 checks passed
@clavery clavery deleted the feature/instance-management branch February 12, 2026 22:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant