DDS Plugin SDK
Install public DDS Plugin SDK 1.2 and use workflows, cache, tool streams, LSP and stable APIs.
User workspace examples below describe an explicitly connected, customer-controlled development host. Choose WSL, a container or a server as the standalone SDK host for these examples. The ordinary Digital Design Studio Windows app runs natively on Windows. The selected SDK host controls discovery, permissions and supported plugin capabilities; managed Cloud engine jobs use their own execution path.
1. Install the SDK
DDS Plugin SDK 1.2.1 provides JavaScript APIs, TypeScript declarations, language providers, themes, workspace tools and command jobs. Optional durable stores add job history, explicit retry and verified text/binary snapshots that survive source deletion and process restart. Use Node.js 22 or 24. Install the stable SDK release from the official GitHub release. For a standalone command plugin, use Development Tools after installation:
1.0.0 publishes the stable SDK API, 18 host conformance profiles, support/migration policy and measured combined-workload checks. New plugins use >=1.0.0 <2.0.0. These published results document API conformance and functional behavior of the standalone SDK.
0.13.0 adds six development templates, generated types and schemas, deterministic test scenarios and optional local diagnostics. The packed SDK and generated projects run outside the source tree; synthetic replay and loopback debugging are explicitly selected.
0.12.0 adds scoped typed settings and explicit migrations, execution-scoped secret references, structured command input/output, locale catalogs and accessibility metadata. Public SDK and independent examples check setting conflicts, invalid input, revoked authority and translation fallback. Use these features through the standalone SDK host APIs and independent examples.
0.11.0 adds signature help, lazy completion, bounded snippets, reviewed multi-file edits and rename, formatting/code actions, semantic tokens, folding, hints and hierarchical symbols. Proposals, review, current authority and conditional application remain separate, and stale document results cannot be displayed or applied. Use these public SDK features in a standalone host and the independent examples.
0.10.0 adds browser streaming downloads, selected-file uploads, a mixed transfer queue and Worker OPFS checkpoint recovery. Transfers check current authority, file identity and chunk/whole hashes while separating byte progress from verified storage. Run these public SDK examples with an explicitly selected host and browser storage destination.
0.9.0 adds scoped project trees, filename/text search and change observation for operator-selected local directories. Use them from the HTTP client or project helper while retaining edit snapshots and unsaved drafts. The project examples below cover creation, search, external changes and conflict handling.
mkdir hello-dds-plugin
cd hello-dds-plugin
npm init -y
npm install --ignore-scripts --save-exact "https://github.com/Altifigence/dds-plugin-sdk/releases/download/v1.2.1/altifigence-dds-plugin-sdk-1.2.1.tgz"
The first diagnostics example uses trusted code in a local test host. Themes use the existing DDS XML import. For existing tool integrations, see Plugins and Third-Party Tools.
2. Write Your First Plugin
Create plugin.mjs in the new project. This plugin checks plaintext documents and reports an informational diagnostic on each line containing NOTE.
plugin.mjs
import { createDiagnosticsResult, definePlugin } from '@altifigence/dds-plugin-sdk';
export default definePlugin({
manifestVersion: 1,
id: 'hello-diagnostics',
name: 'Hello Diagnostics',
publisher: 'example',
version: '0.1.0',
protocolVersion: 1,
entry: './plugin.mjs',
capabilities: ['diagnostics'],
permissions: ['document.read', 'diagnostics.publish'],
supportedHosts: ['test-host'],
license: 'Apache-2.0',
}, context => context.registerDiagnosticsProvider({languages: ['plaintext']}, {
provideDiagnostics(request, {signal}) {
signal.throwIfAborted();
const diagnostics = [];
const lines = request.snapshot.text.split(/\r\n|\n|\r/);
for (let line = 0; line < lines.length; line++) {
const character = lines[line].indexOf('NOTE');
if (character !== -1) diagnostics.push({
range: {start: {line, character}, end: {line, character: character + 4}},
severity: 'info',
code: 'todo',
source: 'hello-diagnostics',
message: 'Review this marked line before sharing the document.',
});
}
return createDiagnosticsResult(request, diagnostics);
},
}));
The manifest declares protocol version 1, the diagnostics capability, the test-host host, and the document.read and diagnostics.publish permissions. The provider receives a document snapshot and an AbortSignal. Diagnostic ranges use zero-based lines and UTF-16 character offsets.
3. Run It Locally
Create run.mjs beside plugin.mjs. Activate the plugin, provide a document and request diagnostics. Always dispose the host when finished.
run.mjs
import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';
const host = createTestHost();
try {
await host.activate(plugin);
host.setDocument({
uri: 'memory:///hello.txt',
languageId: 'plaintext',
modelVersion: 1,
workspaceRevision: 'example-1',
text: 'Hello, DDS!\nNOTE: write a plugin.\n',
});
const result = await host.requestDiagnostics();
console.log(`${plugin.manifest.name}: ${result.diagnostics.length} diagnostic`);
for (const diagnostic of result.diagnostics) {
console.log(`${diagnostic.severity} ${diagnostic.range.start.line + 1}:${diagnostic.range.start.character + 1} ${diagnostic.message}`);
}
} finally {
host.dispose();
}
node run.mjs
Expected output (the printed line and column are one-based):
Hello Diagnostics: 1 diagnostic
info 2:1 Review this marked line before sharing the document.
4. Test Your Plugin
Save this test as plugin.test.mjs. It checks the diagnostic range and confirms that editing the document clears the diagnostic.
plugin.test.mjs
import assert from 'node:assert/strict';
import test from 'node:test';
import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';
test('reports a NOTE and clears it after editing', async () => {
const host = createTestHost();
try {
await host.activate(plugin);
const document = {
uri: 'memory:///hello.txt',
languageId: 'plaintext',
modelVersion: 1,
workspaceRevision: 'test-1',
text: 'NOTE: write a plugin.\n',
};
host.setDocument(document);
const result = await host.requestDiagnostics();
assert.equal(result.diagnostics.length, 1);
assert.equal(result.diagnostics[0].code, 'todo');
assert.deepEqual(result.diagnostics[0].range, {
start: {line: 0, character: 0},
end: {line: 0, character: 4},
});
host.setDocument({...document, modelVersion: 2, text: 'Done.\n'});
assert.equal((await host.requestDiagnostics()).diagnostics.length, 0);
} finally {
host.dispose();
}
});
node --test plugin.test.mjs
The test should pass. Add fixtures for your own language, cancellation, invalid results and large documents. Keep the document version current so results from an earlier snapshot are rejected.
5. Create and Apply a Theme
Save this light/dark palette as theme.json. The six colors in each palette are required. Optional semantic tokens customize search, selections, HintsBox and the GDS canvas; omitted tokens use DDS defaults.
theme.json
{
"name": "Hello Ocean",
"colors": {
"light": {
"backdrop": "#dbe8ef",
"navigation": "#edf5f8",
"tool": "#f3f8fb",
"main": "#ffffff",
"text": "#183b4e",
"muted": "#486477"
},
"dark": {
"backdrop": "#0c1922",
"navigation": "#102430",
"tool": "#17303e",
"main": "#1c3949",
"text": "#e8f4fb",
"muted": "#adcadb"
},
"metrics": {
"panelRadius": 16,
"controlRadius": 8
}
}
}
Create export-theme.mjs beside it. parseTheme validates the color data and serializeThemeXml exports DDS XML version 2.
export-theme.mjs
import { readFile, writeFile } from 'node:fs/promises';
import { parseTheme, serializeThemeXml } from '@altifigence/dds-plugin-sdk/themes';
const theme = parseTheme(await readFile('./theme.json', 'utf8'));
await writeFile('./hello-theme.xml', serializeThemeXml(theme), 'utf8');
console.log('Created hello-theme.xml');
node export-theme.mjs
The command writes hello-theme.xml and prints Created hello-theme.xml. In DDS, open Plugins → Install theme…, select the XML, then choose Apply for Hello Ocean. Switch between light and dark appearance to see both palettes.
You can also use Settings → General → Appearance → Import XML. Save the current theme with Export XML before replacing it. This imports XML appearance data into the theme configuration.
The theme guide lists all supported tokens and metrics. The Hello Ocean example includes the full theme, ready-to-import XML and a local HTML preview.
Theme XML Reference
Download Hello Ocean XML and its editable JSON. The XML contains complete light and dark palettes, all 28 optional role colors in each mode, and four explicit metrics. Save the XML file locally before importing it. These original SDK examples use Apache-2.0; retain the notice when sharing them.
Start with Settings → General → Appearance → Export XML to back up your current theme. Import the downloaded XML, review the draft, then choose Apply. Discard changes keeps the applied theme. Switch light/dark appearance to review both palettes. To recover, choose a built-in theme or import your saved copy. A rejected import preserves the current theme.
DDS, ALcad, shared editors, project navigation, settings and popups use the shared workbench palette in that profile. The same theme format is used by Cloud and desktop; import it separately in each profile. gdsBackground controls the GDS canvas independently. Other design-canvas, layer and simulation colors can have their own settings. XML carries the palette and appearance metrics for this theme profile.
Element | Rule |
|---|---|
| One root; a trimmed name of 1–80 UTF-16 code units; at most 65,536 UTF-8 bytes for the whole XML. |
| Both required, each with the six colors below. |
| Optional v2 overrides. Omitted roles follow DDS defaults for that mode. |
| Optional v2 numeric overrides. |
Version 1 | Both palettes only. Existing v1 files remain supported; the SDK exporter emits v2. |
Required palette key | Use |
|---|---|
| Outer workspace background |
| Project navigation |
| Tool panels and controls |
| Main workspace and settings |
| Main text |
| Secondary text |
Optional role keys (28) | Use |
|---|---|
| Shared search background, text and placeholder |
| Compatibility field; current shared search fields are borderless |
| Selected rows and text |
| Editor tabs |
| Tool rails, panel boundaries and popups |
| Keyboard focus outline |
| Status colors and AI ball background |
| Suggestion and detail backgrounds |
| Suggestion, detail and secondary text |
| Keyboard-selected suggestion |
| Pointer-hovered suggestion |
| GDS viewer canvas background |
HintsBox is the shared code suggestion feature. Find its colors under Custom → Detailed colors and shape → HintsBox and the GDS background under Display. Edit all three search colors together for readable contrast. This fragment belongs inside a v2 theme; keep the two complete palettes:
XML v2 fragment
<tokens mode="dark">
<color key="search" value="#214556"/>
<color key="searchText" value="#e8f4fb"/>
<color key="searchPlaceholder" value="#adcadb"/>
</tokens>
Metric | Allowed values | Current DDS default |
|---|---|---|
| Integer 0–24 | 14 |
| Integer 0–16 | 6 |
| Integer 0–24 | 16 |
| Number 0.6–1 | 0.72 |
Write metrics as <number key="popoverOpacity" value="0.9"/> inside <metrics> without units. Radius values are pixels. The SDK leaves omitted metrics absent; the installed DDS release supplies its defaults. Set explicit values for consistent appearance. Hello Ocean deliberately sets 16, 8, 12 and 0.9. Reduced-transparency and forced-color settings can change the final rendering.
Every color must be six-digit #RRGGBB; alpha, CSS names, variables, URLs and styles are rejected. Duplicate keys or modes, unknown elements/attributes, namespaces, DTDs, entities and processing instructions are rejected. XML declarations and comments are allowed. If import fails, check file size, version, both complete palettes and supported values, then retry with your unchanged backup. Themes from other editors need conversion to this DDS format.
6. Run a Workspace in Your Environment
Run the host, SDK, plugins and tools in your own WSL, container or server environment. Project files stay under the root you choose. The standalone SDK client reads and edits them through the connection; it receives plugin metadata and command results while the plugin code runs in your environment.
In the SDK project created above, save this helper as copy-workspace-example.mjs. It copies the editable server, plugin, tool and sample project while preserving the example’s license file layout.
copy-workspace-example.mjs
import { cp, copyFile, mkdir } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';
const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await mkdir('./user-host/examples', {recursive: true});
await cp(path.join(sdkRoot, 'examples/user-workspace'), './user-host/examples/user-workspace', {
recursive: true, force: false, errorOnExist: true,
});
await copyFile(path.join(sdkRoot, 'LICENSE'), './user-host/LICENSE');
console.log('Created user-host');
node copy-workspace-example.mjs
The sample project is user-host/examples/user-workspace/project. Start the server in that environment using an explicit generated token:
WSL / Linux / container
export DDS_WORKSPACE_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
node user-host/examples/user-workspace/server.mjs
PowerShell
$env:DDS_WORKSPACE_TOKEN = node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))"
node user-host/examples/user-workspace/server.mjs
The server prints Workspace server: http://127.0.0.1:4777/dds/workspace/v1 plus a workspace ID and generation. Set DDS_WORKSPACE_TOKEN to the generated token in the client terminal. It is an operator credential, separate from a DDS Account token. Stop the sample server with Ctrl+C.
From another terminal in the same project, set DDS_WORKSPACE_TOKEN to the same secret and run the developer client:
node user-host/examples/user-workspace/client.mjs http://127.0.0.1:4777
The client lists the sample files and runs Inspect project file for design.sv. The JSON result includes tool: "module-counter" and modules: 1, produced by a real child process. Add --edit to the client command only when you want the example to append a note to the sample file.
To use your own project, pass its absolute directory as the final argument to server.mjs. Keep the server, plugin modules and installed tools in that same user environment. server.mjs explicitly imports the plugin and maps its named backend to a fixed executable and arguments:
server.mjs backend mapping
'module-counter': createProcessBackend({
executable: process.execPath,
args: [fileURLToPath(new URL('./tool.mjs', import.meta.url))],
cwd: root,
env: {},
})
Replace this mapping with your approved installed tool or custom backend. ctx.workspace.readFile and writeFile use paths relative to the selected root; ctx.backends.invoke("module-counter", input, {signal}) invokes only a configured backend name. The process adapter sends bounded JSON on stdin and expects JSON on stdout. It uses no request-supplied shell command and inherits no environment variables from the host.
For a remote server, use your own authenticated HTTPS endpoint or a private tunnel ending at local loopback. Configure container port mapping or TLS in your environment. The example binds loopback by default; changing its bind address does not add TLS. Trusted plugins and tools run with the OS authority of your host process.
See the user workspace example and workspace protocol for server configuration, origins, file revisions, cancellation and bounded results.
Language Features
SDK 0.7.0 provides completion, hover, definition, references and flat document symbols. Declare each feature in manifest v2 capabilities, plus document.read and language.provide permissions. The host must explicitly grant both permissions. Save this complete hover example as language-demo.mjs in the project created above:
language-demo.mjs
import { definePlugin, createLanguageResult, createPluginHost } from '@altifigence/dds-plugin-sdk';
const plugin = definePlugin({
manifestVersion: 2,
id: 'hello-hover', name: 'Hello Hover', publisher: 'example', version: '1.0.0',
protocolVersion: 1, entry: './language-demo.mjs', runtime: 'ui',
capabilities: ['hover'],
permissions: ['document.read', 'language.provide'],
supportedHosts: ['test-host'], license: 'Apache-2.0',
source: {visibility: 'open', licenseFile: 'LICENSE'},
}, context => context.registerLanguageProvider('hover', {languages: ['dds-demo']}, {
provide(request, {signal}) {
signal.throwIfAborted();
return createLanguageResult(request, {text: 'A local LED signal.'});
},
}));
const host = createPluginHost({grants: ['document.read', 'language.provide']});
try {
await host.activate(plugin);
host.setDocument({
uri: 'memory:///demo.dds', languageId: 'dds-demo',
modelVersion: 1, workspaceRevision: 'demo-1', text: 'led',
});
const result = await host.requestLanguage('hover', {position: {line: 0, character: 1}});
console.log(result.data.text);
} finally {
host.dispose();
}
node language-demo.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/hello-language/run.mjs
The first command prints A local LED signal. The bundled second example checks all five features using a tiny teaching language with let name = value; the example’s own provider implements that teaching language.
Feature | Request input | Result data |
|---|---|---|
|
| Up to 500 |
|
|
|
|
| Up to 500 workspace-relative |
|
| Up to 500 workspace-relative |
|
| Up to 500 flat |
Positions use zero-based lines and UTF-16 offsets. Completion insertion is literal text; hover and detail strings are plain text. A host must check target files and ranges before following a location. The result preserves request, project/session and document-version identity. Editing the snapshot, cancellation, timeout, unregistering or disposal ends pending requests and discards late results.
These APIs operate in the trusted SDK host. The standalone host invokes registered language providers; an LSP bridge uses its own explicit process configuration. Hosts older than 0.3.0 reject the new capabilities. Read Language features for selectors, limits and lifecycle behavior.
Project Edit Sessions
Import createWorkspaceProject and applyTextEdits from @altifigence/dds-plugin-sdk/workspace-client. After your host connects a createWorkspaceClient and reviews the workspace identity, notice and access, call createWorkspaceProject(client). The project keeps the exact connection binding. Reconnect requires a newly reviewed project, even when the same workspace ID and generation return.
API | Behavior |
|---|---|
| List one directory under the selected workspace root. |
| Read a file and retain its immutable content and revision in an edit session. |
| Create only when the file is absent, then return a session. |
| Read the last confirmed |
| Save only if the server revision still matches the retained revision. |
| Apply |
| Explicitly read the latest content and revision after a conflict or uncertain write. |
| Cancel owned work; disposing the project leaves the caller-owned client connected. |
Run the complete HTTP example in the installed package. It creates its own temporary sample workspace, tests editing, a conflicting second session, explicit reload, Unicode and reconnect, then closes its server and removes that temporary directory:
node node_modules/@altifigence/dds-plugin-sdk/examples/project-session/run.mjs
Expected output: Project session: HTTP edit, conflict, reload, Unicode and reconnect verified. The example source shows the full server/client setup and cleanup.
Options accept signal and timeoutMs. A failed write after an attempt leaves needs-reload; preserve any unsaved UI draft separately and explicitly reload before another save. The SDK does not merge or retry automatically. A timeout, cancellation or lost response can occur after a server has committed the write; cancelling a request leaves any committed changes in place. Each session allows one pending save or reload.
Text edits use the original snapshot, zero-based lines and UTF-16 offsets. Overlaps, split surrogate pairs and invalid ranges are rejected before saving. Projects allow at most 64 open or opening sessions and 500 edits per save. These helpers use unchanged workspace protocol v1, including SDK 0.2.x servers, and retain root, protected-path and read-only restrictions. Read Workspace projects for lifecycle and size limits.
API Reference
Import plugin APIs from @altifigence/dds-plugin-sdk. The package includes TypeScript declarations for the same exports.
API | Use |
|---|---|
| Validate the manifest and declare the activation function. |
| Register |
| Build a validated result using the request identity. |
| Register a language provider and construct a result with validated request identity. |
| Validate manifest version, identity, permissions, supported hosts and entry module. |
| Validate URI, language, model version, workspace revision and text. |
| Validate protocol, request, scope, document identity and diagnostic fields. |
| Read typed errors, resource limits and protocol version. |
Import the developer host from @altifigence/dds-plugin-sdk/testing:
Test host API | Use |
|---|---|
| Create a local host. Both options are optional; default grants allow document reading and diagnostics. |
| Activate the plugin and return a disposable activation. |
| Set the current document. Increase |
| Request diagnostics from a matching provider; both options are optional. |
| Request a declared language feature with explicit document.read and language.provide grants. |
| Remove registrations and cancel pending work; dispose the host when the test ends. |
Requests include requestId, project/session scope and a snapshot with uri, languageId, modelVersion, workspaceRevision and text. Use createDiagnosticsResult to preserve this identity. Results contain a diagnostics array and omit source text.
Errors expose a code, including invalid_contract, permission_denied, cancelled, stale_snapshot, provider_unavailable and budget_exceeded. The default request timeout is 5 seconds; accepted timeouts are 1–30,000 ms. A document is limited to 262,144 UTF-8 bytes and a result to 500 diagnostics. Read LIMITS for the complete limits.
SDK 1.0.0 also provides separate modules. Node-only workspace and packaging imports belong in the user environment:
Import | API |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Package and Publish Your Plugin
Start with the included publishable plugin. Save this helper in your SDK project to copy its files into a new my-plugin directory.
copy-publishable-example.mjs
import { cp } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';
const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await cp(path.join(sdkRoot, 'examples/publishable-plugin'), './my-plugin', {
recursive: true,
force: false,
errorOnExist: true,
});
console.log('Created my-plugin');
node copy-publishable-example.mjs
Edit plugin.json, plugin.mjs, disclosure.json and the license to describe your own plugin. The disclosure must match the manifest publisher, plugin ID, version, license and source visibility. List only the files you intend to distribute in dds-package.json:
dds-package.json
{
"schemaVersion": 1,
"files": [
"plugin.json",
"plugin.mjs",
"disclosure.json",
"LICENSE",
"NOTICE"
]
}
Validate and package the example:
npx --no-install dds-plugin validate ./my-plugin
npx --no-install dds-plugin pack ./my-plugin --out ./dist
With the unchanged example metadata, pack creates dist/example-hello-publisher-1.0.0.tgz and dist/example-hello-publisher-1.0.0.tgz.release.json. The release JSON contains the final archive SHA-256, manifest/disclosure hashes and file inventory. Inspect these files before distribution.
Only allowlisted files, dds-package.json and generated npm metadata enter the archive. Validation inspects package data, and packing creates the local archive for your chosen distribution channel. The CLI rejects private configuration, key files and linked paths; review your chosen file contents before sharing.
Channel | What to provide |
|---|---|
Public GitHub Release | A versioned archive, its external release JSON, license and any required source access. |
Private registry or download channel | The same versioned files, audience authorization and actual plugin terms. |
Manifest v2 declares runtime, requested permissions and source: {visibility, licenseFile, repository?}. Set visibility to open or closed and include the actual license file. Code you own may use open-source or proprietary terms; applicable SDK and dependency notices still apply. Recipients receive the executable JavaScript together with the declared source-visibility and license metadata.
Follow Publishing and Licensing for disclosure fields and distribution requirements. Distribute the generated archive and release JSON through your selected GitHub release, private registry or download channel.
The 1.2.1 CLI records >=1.0.0 <2.0.0 in new plugin packages. Historical 0.3–0.13 and exact 1.0.0-rc.1 archives retain their original peers. Validate and repack a new plugin version for stable installation; the publisher explicitly updates the declared peer range and release metadata during repackaging.
Verify a Downloaded Plugin
SDK 1.2.1 provides dds-plugin verify for exact released 0.3.x–0.13.x, RC1 and current stable plugin metadata. Keep the .tgz and .tgz.release.json together. Verification preserves the original peer. Check the package created above:
Verify the packaged example
npx --no-install dds-plugin verify ./dist/example-hello-publisher-1.0.0.tgz
The command checks bounded gzip/tar structure, exact file allowlists, every file hash, manifest, disclosure, license and generated npm metadata. It rejects links, unsafe or duplicate paths, extra files and npm hooks/dependencies. It reads and validates the local archive in place as a data-only operation. Success prints a JSON receipt; rejection exits with code 1.
For renamed downloads, use --metadata with the matching release JSON. Obtain the expected SHA-256 independently through a trusted release channel and pass it with --sha256 to pin the selected bytes. The Node API exposes the same options:
verify-release.mjs
import { verifyPluginArchive } from '@altifigence/dds-plugin-sdk/publishing';
const receipt = await verifyPluginArchive(process.argv[2], {
metadataPath: process.argv[3],
expectedSha256: process.argv[4],
});
console.log(receipt.pluginId, receipt.pluginVersion, receipt.artifact.sha256);
Run verify-release.mjs with the archive path, metadata path and independently obtained 64-character lowercase hash as its three arguments. checksumPinned is true only when that supplied hash matches. Limits are 12 MiB compressed input, 10 MiB file contents, 4 MiB per file, 256 files and 256 KiB external metadata.
The paired metadata records archive integrity through matching hashes. Obtain the expected digest from an independently trusted release channel, because replacing both files can create a new matching pair. Review the publisher and executable contents, grant host permissions explicitly and validate the target installation as separate steps. A receipt describes bytes read during that call; recheck the actual bytes if the file can change before use. Existing 0.3.x/0.4.x/0.5.x/0.6.x/0.7.x/0.8.x/0.9.x/0.10.x/0.11.x plugin archives remain verifiable when they satisfy the strengthened file policy; installing them on 1.0 still requires publisher validation and repacking. Remove newly excluded files and publish a new plugin version if needed. This verifier is for DDS plugin packages; SDK npm tarballs use their release SHA-256.
See Archive verification and the complete package/verify/tamper example.
Permissions, Licenses and Data Use
Requested permissions in a manifest are separate from the host grants that enable operations. Give users the plugin identity, version, actual license, workspace scope and requested permissions before enabling it. Explain any backend operator, data sent, purpose, retention and privacy notice before connecting that backend.
Record | Meaning |
|---|---|
| A host access decision for the exact package, workspace and permissions. |
| A user acknowledged an information notice. |
| A user chose whether to accept the plugin publisher’s actual terms. |
| A separate choice when optional processing uses consent as its basis. |
An SDK workspace approval is a technical access decision. Record acceptance of plugin terms and optional personal-data consent as their own choices and record kinds. Use the SDK under its Apache-2.0 license and notices.
Host developers can preserve a versioned notice with the portable asynchronous helpers. For example, save this as notice.mjs and run node notice.mjs:
notice.mjs
import { createNotice, parseNotice } from '@altifigence/dds-plugin-sdk/consent';
const notice = await createNotice({
id: 'greet-data-use',
version: '1.0.0',
locale: 'en',
purpose: 'Explain the greet command',
text: 'The greet command uses the name you enter to return a greeting. It does not read project files or contact another backend.',
});
await parseNotice(notice);
console.log(notice.text);
console.log(`Notice text SHA-256: ${notice.contentSha256}`);
createPermissionGrant binds a requested permission subset to manifest v2, artifact and manifest hashes, workspace generation, host identity, notice and expiry. isPermissionGranted evaluates the current identities and revocation events supplied by the host. revokeConsentReceipt creates a separate event; the host must then stop future authorized calls.
These helpers validate local records. The host supplies the actual user choice, identity, storage and enforcement. Read Permissions and consent for exact fields and the interactive permission example for an explicit allow/deny/revoke demonstration. The host manages publisher terms and their acceptance records.
Source, Releases and Contributions
The official SDK repository contains the source, schemas, examples and contract tests. To run the released example and SDK tests from source:
git clone --branch v1.2.1 --depth 1 https://github.com/Altifigence/dds-plugin-sdk.git
cd dds-plugin-sdk
npm ci
npm test
npm run example
npm run example:language
npm run example:project
npm run example:verify
npm run example:jobs
npm run example:observe
npm run benchmark:files
npm run example:artifacts
npm run benchmark:artifacts
npm run example:durable-jobs
npm run example:stored-artifacts
Report SDK bugs through GitHub Issues, with the SDK version and a minimal reproduction. The SDK is licensed under Apache-2.0; see the repository license and notices. Use the release page for versioned archives and release notes.
This repository is the intentionally public developer SDK. Its release contains the declared SDK files, schemas, examples and notices described in its public scope. Package checks enforce the exact published file inventory and reject known secret and private-path patterns. Review the actual release contents alongside those pattern checks.
Security Updates and Host Limits
Update both your workspace server and SDK client to 0.3.2 or later. Install the server update to activate its upgraded file checks and request limits. Restart the upgraded host, review its new generation and obtain approval again before using the workspace.
The Node workspace host rejects hardlinks that could alias protected files or files outside the selected root. Copy an intentionally shared project file into a regular single-link file. Credential stores such as .netrc, _netrc, .git-credentials, .gnupg, .kube and .docker, additional SSH key names, and Windows device aliases are also blocked. Packaging and download verification apply the matching credential-name policy.
Server resource | Limit |
|---|---|
Concurrent incoming bodies | 16; further uploads receive HTTP 429 before dispatch |
Executing requests | 64; cancellation uses a separate dispatch path |
Connections / requests per socket | 128 / 128 |
Request and reply / file content | 1,600,000 / 262,144 UTF-8 bytes |
The client cancels unread rejected responses and stalled streams on a deadline or cancellation. A timeout after a write starts can leave its result uncertain: reread the file before retrying. Review file contents alongside explicit path exclusions, and run trusted plugin code with the host process’s operating-system access in mind. Use the security upgrade guide and workspace limits when deploying a host.
Development Tools
After installing SDK 1.2.1 above, create a separate command-plugin project. Choose a new destination for the generated files; run dependency installation and plugin execution explicitly after scaffolding. The scaffold includes a command, test, manifest, disclosure, pinned SDK dependency and Apache-2.0 LICENSE/NOTICE.
npx --no-install dds-plugin init ../my-command-plugin --id my-command-plugin --publisher example
cd ../my-command-plugin
npm install --ignore-scripts
npm run doctor
npm test
npx --no-install dds-plugin dev . --trust-local-code --command greet --input '{"name":"Ada"}'
Doctor reads metadata and checks Node, SDK resolution, the manifest, license, disclosure and allowlisted package files without importing the plugin. Errors produce exit status 1; example publisher/support values are warnings. Replace those values and review licenses before distribution.
npx --no-install dds-plugin doctor . --json
npx --no-install dds-plugin dev . --trust-local-code --watch
npx --no-install dds-plugin dev . --trust-local-code --job --command greet --input '{"name":"Ada"}'
npm run pack:plugin
Dev requires --trust-local-code. It runs trusted local imports/activation in a child and watches only allowlisted files plus dds-package.json. Each run has a deadline and 256 KiB stdout/stderr limit. Ctrl+C stops watching and cleans up its process tree. The child runs with your operating-system authority and inherited environment. The default test host provides document reading and diagnostics; configure a separate workspace host and explicit grants for workspace/backend integrations.
Use --job to print job progress/logs; use --timeout-ms to set up to 30 seconds for ordinary commands or 30 minutes for jobs. Node APIs are initPlugin, doctorPlugin and runPluginDev in /devtools. See the development tools guide for watch behavior and resource cleanup.
Long-running Command Jobs
Enable jobs: true on a 0.4.0 SDK host/server to run commands beyond the ordinary request deadline. Jobs are disabled by default. Try the complete local HTTP example, which reports progress, a named-backend log and a hash-pinned result file:
node node_modules/@altifigence/dds-plugin-sdk/examples/command-jobs/run.mjs
Expected output: Command job: progress, backend log and pinned result file verified. A command handler receives optional job in {signal, job}. It provides reportProgress, log, addArtifact and invokeBackend. Existing workspace.read/write and backend.invoke grants still apply; no arbitrary executable path is accepted.
Javascript
await client.connect();
if (!(await client.getJobCapabilities()).enabled) throw new Error("Jobs are unavailable");
const jobId = crypto.randomUUID(); // Save before sending.
let job = await client.startCommandJob(pluginId, "analyze", {}, artifactSha256, {jobId, timeoutMs: 300_000});
let after = 0;
for (;;) {
const page = await client.getJobEvents(jobId, after);
after = page.nextCursor;
if (page.dropped) console.log("Expired events:", page.dropped);
for (const event of page.events) console.log(event.kind, event.data);
job = await client.getJob(jobId);
if (job.state !== "running" && !page.hasMore && after >= job.lastSequence) break;
await new Promise(resolve => setTimeout(resolve, 250));
}
if (job.state === "succeeded") {
const file = await client.readJobArtifact(jobId, "report");
console.log(file.content);
}
The polling snippet assumes a connected client and a configured analyze command that registers report. Keep the job ID before starting. Disconnecting or aborting a polling request does not cancel execution; reconnect to the same generation and query/cancel explicitly. Retried starts with the same ID and input reuse the retained job; changed arguments conflict. Host restart loses the in-memory records. Enable the separate 0.8 durable store below to recover committed metadata after restart.
States are running, succeeded, failed, cancelled and timed_out. Late output is discarded after cancellation; side effects are not rolled back. Unsettled providers keep their slots. There are at most 4 concurrent jobs, 32 retained records, 32 nested operations per job, 256 events/64 KiB per job, 64 events per page and 16 artifacts. Runtime defaults to 5 minutes and is capped at 30 minutes. Settled terminal records expire 15 minutes after their last event.
Text result files are workspace-relative UTF-8 up to 256 KiB. The host reads them using the existing grant, records SHA-256 and rejects later reads if the bytes changed. For binary or larger simulation output, use the optional binary result API. Partial artifacts can remain after cancellation; inspect the terminal job state to establish success. Older 0.3 clients keep using existing v1 methods; standalone SDK jobs use 0.4 or later on both client and host. See Jobs for exact contracts and limits.
Observe Workspace Files
project.watchFiles() samples 1–16 explicit relative file paths. SDK 1.0.0 uses revision-only requests on supporting hosts and existing bounded reads on older hosts. The example assumes a connected, host-approved client. Change design.sv with an external editor to end the loop; the retained edit snapshot stays unchanged.
Javascript
import {createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
const project = createWorkspaceProject(client);
const edit = await project.openFile('design.sv');
const original = edit.snapshot;
try {
for await (const change of project.watchFiles(['design.sv'], {intervalMs: 1000})) {
console.log(change.kind, change.path, change.previousRevision, change.revision);
if (change.kind !== 'initial') break;
}
console.log(edit.snapshot === original);
} finally { project.dispose(); }
Events are immutable {kind, path, previousRevision, revision}. The first sample emits initial; later changes emit created, changed or deleted. Missing files have revision null. includeInitial: false records the baseline silently, and equal revisions produce no event. Only not_found means deletion; permission, protected-path, size and transport errors end observation.
Keep unsaved UI text separately. Observation preserves the draft and retained edit snapshot; the caller explicitly chooses reload, merge or save, and saves check the retained revision for conflicts. Paths are read one at a time in order; this is sampled observation, so intermediate changes can coalesce. Select the exact file paths to sample; each event describes an observed path and revision. Existing root, file-size and protected-path restrictions apply on read-only and writable servers.
Both file and job observers start on their first next(), fetch no background pages while the consumer is paused and share a maximum of eight active observers per client. One next() may be pending; a concurrent read fails with conflict. Break or return() stops pending reads; project disposal stops its file observers, and disconnect/reconnect/disposal invalidates all old observers. AbortSignal ends observation with cancelled; late replies cannot yield results.
intervalMs is 250–60,000 ms (default 1,000), applied between file passes or idle job reads. requestTimeoutMs is 1–30,000 ms per request, defaulting to the client deadline. Total timeoutMs is 1–1,800,000 ms from the first next(), including consumer pauses. Files have no total timeout by default; jobs default to 30 minutes. Deadlines report budget_exceeded and release the slot. These limits are exported as WORKSPACE_OBSERVATION_LIMITS.
node node_modules/@altifigence/dds-plugin-sdk/examples/workspace-observation/run.mjs
Expected output: Workspace observation: file changes, retained draft and resumed job verified. The complete example creates its own temporary workspace and checks file changes, draft conflicts and explicit job resumption. See Observation for all options and lifetime rules.
Observe and Resume Jobs
client.watchJob() follows an existing job using jobs.events/get; waitForJob() returns its terminal snapshot. The snippet assumes a connected client, an explicitly started jobId and a savedCursor (or undefined). Check getJobCapabilities() before starting a job. Observation never starts, retries or cancels the command.
Javascript
let after = savedCursor ?? 0;
for await (const update of client.watchJob(jobId, {after, intervalMs: 1000})) {
if (update.dropped) console.log('Expired events:', update.dropped);
for (const event of update.events) console.log(event.kind, event.data);
console.log(update.snapshot.state, update.snapshot.progress);
after = update.nextCursor;
}
const result = await client.waitForJob(jobId, {after, timeoutMs: 120000});
if (result.state === 'succeeded') console.log(result.result);
else console.log(result.state, result.error.code);
Each frozen update contains snapshot, events, after, nextCursor, dropped and hasMore. Handle at most 64 events per page and record nextCursor after processing it, together with job ID and workspace identity. dropped reports expired history. A snapshot can be newer than its event page; keep reading terminal snapshots while hasMore is true. The iterator ends after the final page. waitForJob() drains the same pages and returns succeeded, failed, cancelled or timed_out; inspect state instead of treating every resolved promise as success.
Stopping an iterator or timing out only stops observation. The server command continues until it finishes or cancelJob() is explicitly called. After a host-approved reconnect, verify the same workspace ID and generation, then create a new observer with the saved job ID and cursor. Old observers are invalid even if the identity is unchanged. Missing/expired jobs and transport failures are reported without resubmission; in-memory jobs do not survive host restart. Durable recovery uses recoverJob() with a new connection; live observers do not resume across generations.
Existing v1 hello and job contracts remain unchanged. File observation falls back on 0.3.2/0.4/0.5 hosts; job observation requires an enabled 0.4 or later host. Check host job capabilities before observing; an unsupported response ends the request and preserves explicit control over command execution. These observers run through standalone SDK clients and hosts. See Observation and Compatibility.
File Revisions and Conditional Reads
SDK 0.6.0 adds getFileCapabilities(), getFileRevision(path) and readFileIfChanged(path, knownRevision) to connected clients. Revision reads return {path, revision} with no content. A matching conditional read returns {path, revision, notModified: true}; changed content returns notModified: false and content. Pass knownRevision: null for current content. Missing files reject with not_found.
Javascript
let cached = await client.readFile('design.sv');
const current = await client.readFileIfChanged(cached.path, cached.revision);
if (!current.notModified) cached = current;
console.log(cached.content);
const metadata = await client.getFileRevision('design.sv');
console.log(metadata.revision);
Use an already connected, authorized client. Keep unsaved drafts separate from this cache. Conditional reads hash and return one file snapshot; a later read can still observe another change. Save with the revision belonging to the returned content. These calls do not update edit-session snapshots or merge drafts. An unchanged reply has no content field; an empty changed file has content: “”.
File observation automatically uses revision-only reads when supported. The optional fs.capabilities, fs.revision and fs.readIfChanged methods preserve the strict v1 hello and original file methods. Known pre-0.6 SDK workspace hosts use fs.read without probing. Other hosts must answer discovery or return a correctly correlated unsupported error. Each false capability selects its own bounded full-read fallback; the old-server response still transfers the full content.
Capabilities are cached only for the current connection and reset on reconnect or revocation. Invalid replies, path/revision mismatches, permissions, authentication, transport failures and timeouts do not trigger fallback. Advertised operations that later fail are not silently downgraded. AbortSignal covers discovery and the read; timeoutMs is applied to each HTTP request. A connection change invalidates the old operation.
The server still performs a guarded full file read and SHA-256 calculation for every sample. UTF-8 validation, the 262,144-byte limit and protected path/link checks remain in force. This reduces network response bytes while retaining the guarded disk reads and SHA-256 calculation for each sample. A local Node 22.23.1 Windows measurement of 20 unchanged 200,000-byte samples returned 4,003,974 bytes for full reads, 3,867 for revisions (99.903% less) and 4,247 for conditional reads (99.894% less). Discovery is included; HTTP headers, TLS and the initial hello/content baseline are excluded. Run npm run benchmark:files in a checkout to reproduce the fixture.
The SDK provides a stable 1.x API. Existing 0.3.2, 0.4, 0.5 and 0.6 clients keep their original APIs on 0.7 hosts. Use these revision APIs through a connected standalone SDK client. See File revisions for the complete contract and migration rules.
Large and Binary Job Results
SDK 0.7.0 adds an optional binary result-file extension. A trusted command registers an existing workspace file; the host records its SHA-256 and length. Clients read at most 64 KiB per chunk, and the Node downloader resumes a partial file and verifies the complete output. The maximum recorded file is 1 GiB; existing 256 KiB UTF-8 file and text-artifact APIs retain their bounds.
Enable jobs: true and binaryArtifacts: true on the server-owned plugin host. Both default to false. Keep the explicit token, operator notice, reviewed plugin artifact pin and effective workspace.read grant. The following builds on the workspace setup above; read-only workspaces may register files already generated by the operator’s configured tool.
Javascript
const server = await createWorkspaceServer({
root, workspaceId, token, notice,
plugins: [{plugin, artifactSha256}],
grants: ['workspace.read'],
jobs: true, binaryArtifacts: true, writable: false,
});
Register the result inside a command started with startCommandJob. Registration streams the existing file through SHA-256 using a 64 KiB buffer. The reference points to that source file, not an immutable copy. Protected paths, traversal, links and non-regular files are rejected; later source changes fail with conflict.
Javascript
context.registerCommand({id: 'collect', title: 'Collect trace'}, async (_, {job}) => {
if (!job) throw new Error('Start this command as a job');
const artifact = await job.addBinaryArtifact({
id: 'trace', path: 'outputs/trace.fst', label: 'Simulation trace',
});
return {artifactId: artifact.id};
});
Use an already connected, authorized client and an existing job ID. The destination is an absolute path in an existing real directory controlled by the caller. The helper writes destination + “.dds-part” and refuses to overwrite an existing final file.
Javascript
import {downloadJobBinaryArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const capabilities = await client.getBinaryArtifactCapabilities();
if (!capabilities.enabled) throw new Error('Binary results are not enabled');
const reference = await client.getJobBinaryArtifact(jobId, 'trace');
const receipt = await downloadJobBinaryArtifact(client, reference, {
destination: absoluteDownloadPath, resume: true,
signal: abortController.signal,
onProgress({receivedBytes, totalBytes}) {
console.log(receivedBytes, totalBytes);
},
});
console.log(receipt.verified, receipt.revision);
Keep the whole {jobId, scope, artifact} reference. After interruption, explicitly reconnect to the same host generation and call the helper again with that reference and resume: true. It rehashes the saved prefix and requests only the missing suffix. It checks SHA-256 for each chunk, the complete received stream and the actual staging file before publishing. The final verified: true receipt confirms completion; synchronous progress callbacks remain unverified. Corrupt partial files require explicit removal or a new destination.
listJobBinaryArtifacts(jobId) returns recorded binary metadata separately from existing text results. readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) returns canonical base64 with a chunk SHA-256, exact range and EOF marker. decodeBinaryArtifactData from /artifacts returns Uint8Array bytes. Browser consumers must verify the whole-file hash themselves; individual chunk checks do not prove that assembled output matches the reference.
Binary and text results share 16 slots and an ID namespace per job. Binary capture/read operations are limited to four per host/workspace, and Node downloads to four per process. Node download timeoutMs is a total deadline, defaulting to a maximum of 30 minutes; requestTimeoutMs defaults to 5 seconds with a 30-second maximum. Publication needs hardlink support such as NTFS or ext4. Use a caller-controlled directory and trusted writers; filesystem checks operate with the host process’s operating-system authority.
Optional artifacts.capabilities, artifacts.list and artifacts.read preserve existing v1 hello, job snapshots and events. Hosts before 0.7 report the extension disabled; the client preserves that capability result and explicit control of reads and execution. Authentication, malformed replies and transport errors stay errors. Reconnect, revocation, job expiry or a changed host generation invalidate old operations. Job retention remains in memory for 15 minutes after the terminal job’s last event. Cancelled jobs may leave recorded partial tool output; inspect the terminal job state to establish success. This describes the default live/source APIs. The separate stored-result API below retains bytes across restarts.
Run npm run example:artifacts for a real 2 MiB transfer with interruption, reconnect and suffix-only resume; npm run benchmark:artifacts uses 8 MiB. A local Windows run transferred 8,388,625 bytes in 129 chunk requests, resuming a 65,536-byte prefix and verifying the final SHA-256. Base64 adds overhead; the JSON response bodies totaled 11,257,419 bytes. The transfer bounds memory usage and verifies the complete received file. See Binary artifacts for the full contract. Run the transfer through a standalone SDK client and host.
Durable Jobs, History and Explicit Retry
SDK 0.8.0 adds optional durable stores in an operator-owned directory outside the workspace. Supply absolute paths, a stable workspace ID, reviewed plugin code, package SHA-256, token and notice. The example also enables retained file bytes; omit artifacts from jobStorage to store only job metadata. Existing v1 replies and memory-only defaults remain compatible.
Javascript
import {createNodeJobStore} from '@altifigence/dds-plugin-sdk/job-storage-node';
import {createNodeArtifactStore} from '@altifigence/dds-plugin-sdk/artifact-storage-node';
import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
const store = await createNodeJobStore({directory, workspaceRoot: root, workspaceId});
const artifacts = await createNodeArtifactStore({jobStore: store});
const server = await createWorkspaceServer({
root, workspaceId, token, notice, plugins: [{plugin, artifactSha256}],
grants: ['workspace.read'], jobs: true, binaryArtifacts: true,
jobStorage: {store, artifacts},
});
A provider starts only after its initial intent is saved. Later checkpoints are coalesced; flushJobStore() waits for requested checkpoints, not command completion. Recovery separates the current connection from the original execution scope and reports live, completed, interrupted, expired, missing, corrupt or unsupported. An interrupted job never restarts automatically; its unrecordedTail is unknown.
Javascript
const capabilities = await client.getJobStorageCapabilities();
const query = {limit: 16, commandId: 'analyze'};
const page = await client.listJobHistory(pluginId, artifactSha256, query);
const prior = await client.recoverJob(pluginId, previousJobId, artifactSha256);
const attempt = await client.retryCommandJob(pluginId, previousJobId,
reviewedFreshInput, artifactSha256, {jobId: crypto.randomUUID()});
History filters state, recovery disposition, command, start time and parent attempt. Pages contain up to 32 entries, ordered by descending start time then job ID. A cursor freezes membership for 60 seconds and must reuse the same query; new jobs are excluded, deleted or unauthorized records are skipped and expiry is reported. Restart loses cursors. artifactCount, snapshotCount and resultAvailability describe recorded references, not current file proof.
Explicit retry needs a fresh job ID, new validated input, the same currently approved package and an available command. attemptOf links the new run to its unchanged parent. Repeating the same ID, input, parent and timeout retrieves the retained attempt without rerunning, including after restart. Missing/expired records cannot provide that guarantee. An accepted execution can continue after the waiting request is cancelled; query the new job ID before deciding to retry.
Default retention omits raw input, result bodies, progress text and artifact labels; logs are redacted. Only an explicit deterministic host redactor retains reviewed text. Tokens, secrets and old consent are never restored. Current workspace/plugin identity, read permission and every recorded grant are rechecked. Job metadata defaults to 256 records, 64 MiB and 24 hours, with a seven-day maximum. Removal and pruning are explicit host operations.
The local store has one writer, validates workspace/root identity and checks metadata integrity. Explicit stale-lock recovery only reclaims a provably dead same-machine PID. Unknown/corrupt files require inspection. On Windows, file sync and rename support the tested recovery after process termination; persistence follows the behavior of the filesystem and storage device. See Job storage, History and the durable-jobs example.
Stored Results and Restart Downloads
With the artifact store enabled, await job.addArtifact() or job.addBinaryArtifact() copies and verifies the full file before registration. Text remains bounded to 256 KiB; binary files are at most 1 GiB. The source stream and actual staging file are SHA-256 checked. Cancellation, disk-full errors, mutation and partial writes do not publish usable results. Files published before a crash but not recorded by the job can remain for operator inspection.
Javascript
import {downloadStoredJobArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const list = await client.listStoredJobArtifacts(pluginId, jobId, artifactSha256);
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, artifactSha256);
const receipt = await downloadStoredJobArtifact(client, reference, {
destination: absoluteOutputPath, resume: true,
});
console.log(receipt.storage, receipt.snapshotId, receipt.verified);
The list separates source references from snapshot metadata and reports retained, expired, missing, corrupt or unsupported snapshots. retained is a metadata status; getStoredJobArtifact() verifies metadata and the whole stored file before returning a fresh current-generation reference. Each read rechecks current authority and file identity. Deleted sources do not affect stored bytes, and missing snapshots never fall back to a mutable source. For text snapshots, call client.readStoredJobArtifactText(textReference).
After a restart, reconnect with current grants and obtain a new reference. The snapshot ID, store ID and digest stay stable; the old generation is rejected. resume: true rechecks a saved .dds-part prefix against that snapshot, verifies chunks and the full staging file, and publishes without overwriting the destination. Reads need retained job metadata as well as file bytes. Browser chunk consumers must verify the complete digest; the Worker adapter below provides explicit browser disk resumption.
Artifact storage defaults to 256 files, 256 MiB and 24 hours, with maximum total storage of 4 GiB and retention of seven days. Chunks are at most 64 KiB, with four concurrent reads. inspect() reports usage, expiry times, invalid entries and orphans. remove(snapshot) and prune() are explicit operator operations. Active jobs and individual reads are pinned; expiry or removal between chunks can stop the next read. Optional orphan pruning only removes recognized single-link files. Corrupt or ambiguous entries need inspection.
File retention stores actual project bytes independently of log redaction. Choose it deliberately. Current plugin/command, package hash, workspace and recorded grants remain required after restart. Finish maintenance, then await server.close(), artifacts.close() and store.close(), in that order. Configure and use file retention on the standalone SDK host.
Run npm run example:stored-artifacts for a real child-process restart, source deletion, verified partial download resume, history and explicit retry. npm run example:durable-jobs also covers forced process termination. See Stored results. Known 0.7 and earlier hosts report storage disabled without unknown probes. Existing live/source APIs keep their original behavior.
Observe a Project
The operator explicitly enables projects and selects allowed roots on the server. The default is disabled. Known SDK 0.3–0.8 hosts report unavailable without a new discovery probe. The supported profile uses Windows/Linux local filesystems. Run this example through the standalone SDK project APIs.
import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
import {createWorkspaceClient, createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
// The operator chooses the workspace and its allowed local directories.
const server = await createWorkspaceServer({
root: operatorWorkspace, workspaceId, token, notice,
projects: {roots: ['rtl'], fileSystem: 'local'},
});
const client = createWorkspaceClient({url: server.url, token});
await client.connect();
const project = createWorkspaceProject(client);
if (!(await project.getProjectCapabilities()).enabled) {
throw new Error('Project tools are unavailable');
}
const observer = project.watchProject({
root: 'rtl', include: ['**/*.sv'], exclude: ['build/**'],
intervalMs: 1000, debounceMs: 50,
}, {signal});
for await (const event of observer) {
renderExternalView(event.snapshot, event.kind, event.reason);
}
project.dispose(); client.dispose(); await server.close();The first event is a full snapshot. Later changes carry deltas against a previous revision; lost hints, changes during the initial scan, incomplete scans and slow-consumer overflow produce a full resync view with a reason. Renames may appear as delete/create. Each file is verified separately at its observation time; the resulting view combines those samples, and intermediate writes can coalesce.
The server and client each allow four subscriptions, with four queued events per native subscription. The default idle lease is 30 seconds; a later read may return not_found. After a long pause, create a new iterator for an initial snapshot. break/return, cancellation and disposal release subscriptions; if a broken connection prevents cleanup, the remaining remote resources expire with their lease.
Default scan limits are depth 8, 512 entries, 1 MiB per file, 16 MiB total and 10 seconds. Configurable maxima are depth 32, 1,000 entries, 16 MiB per file, 64 MiB total and 30 seconds. Limited files may carry metadata without a content hash; check complete and reasons. Deadlines are checked between filesystem calls; use deliberately chosen host-process OS access for those calls.
Project Tree and Search
listTree returns a tree, searchFiles searches relative filenames by literal substring or bounded glob, and searchText finds literal text in UTF-8 files. root is required; include/exclude are relative to it. Use literal text and the documented bounded filename glob syntax for search patterns. Case-insensitive matching folds only ASCII A–Z so original UTF-16 positions remain stable.
const tree = await project.listTree({root: 'rtl', pageSize: 16});
const names = await project.searchFiles({root: 'rtl', query: '**/*.sv', mode: 'glob'});
const query = {root: 'rtl', include: ['**/*.sv'], query: 'module ', pageSize: 16};
let page = await project.searchText(query);
for (const item of page.items) {
console.log(item.entry.path, item.entry.revision, item.match.range, item.match.snippet);
}
if (page.nextCursor) {
const next = await project.searchText({...query, cursor: page.nextCursor});
console.log(next.stale, next.items.map(item => item.state));
if (next.nextCursor) await project.releaseProjectQuery(next.nextCursor);
}
if (tree.nextCursor) await project.releaseProjectQuery(tree.nextCursor);
if (names.nextCursor) await project.releaseProjectQuery(names.nextCursor);Text matches include a content SHA-256, zero-based UTF-16 range and bounded snippet. A cursor freezes the original membership for at most 60 seconds and requires the same query. Later pages recheck current content and mark items current, changed, missing or unverified; new files appear only in a new query. The captured match and revision stay unchanged.
Text files are bounded to 256 KiB, queries to 256 UTF-16 units and snippets to 512 units. Defaults are 256 results (maximum 512), 32 items per page (maximum 64) and a 64 KiB response (maximum 128 KiB). Binary files, invalid UTF-8 and byte/depth/time/response limits are reported as incomplete results with reasons. There are two concurrent queries and eight retained cursor views; release unused cursors explicitly.
Project Drafts and Reconnect
const edit = await project.openFile('rtl/counter.sv');
const original = edit.snapshot;
const draft = original.content + '\n// unsaved draft';
const query = {root: 'rtl', include: ['**/*.sv'], query: 'module '};
let page = await project.searchText(query);
for await (const event of project.watchProject({root: 'rtl', include: query.include}, {signal})) {
if (event.snapshot.revision !== page.snapshotRevision) {
if (page.nextCursor) await project.releaseProjectQuery(page.nextCursor);
page = await project.searchText(query); // keep the same explicit scope
}
renderTreeAndMatches(event.snapshot, page); // draft remains caller-owned
}
// A changed file causes conflict; a move/deletion can cause not_found.
try { await edit.save(draft); }
catch (error) {
if (!['conflict', 'not_found'].includes(error.code)) throw error;
showResolutionChoice(error, draft, original);
}
// Only an explicit edit.reload() replaces the edit snapshot.
project.dispose(); client.disconnect(); await client.connect();
const freshProject = createWorkspaceProject(client);
const freshObserver = freshProject.watchProject({root: 'rtl'});
console.log((await freshObserver.next()).value.cursor); // 1: full initial view
await freshObserver.return(); freshProject.dispose();When a query snapshotRevision differs from the observed snapshot.revision, release the old cursor and repeat the same root/filter query. Observation never mutates edit.snapshot or caller-owned draft content. After an external change, move or deletion, the original CAS condition reports a conflict; the caller chooses an explicit reload, merge or separate save.
The client checks connection generation, root/filter, query hash, page positions, snapshot SHA-256 and event continuity. Late responses are discarded after revocation, disconnect or reconnect. Watch cursors and query cursors are separate and are not restored automatically. server.revokeProjects() ends project access; re-enabling requires a new server generation.
npm run example:project-watch
npm run example:project-query
npm run example:project-tools
npm run example:project-browserInstalled Node examples verify creation, search, external changes, retained drafts, CAS conflicts and reconnect. For the browser example, open the printed loopback URL and choose Run scenario. It uses only its temporary workspace, which is removed when the example server stops. HTTP requests default to five seconds; configure client and server timeouts deliberately for larger scans.
Project observation · Tree/search contracts · HTTP project tools
Stream and Verify Browser Artifacts
import {streamStoredJobArtifact} from '@altifigence/dds-plugin-sdk/artifact-transfer';
import {createOpfsFileSink} from '@altifigence/dds-plugin-sdk/artifact-transfer-browser';
// selectedDirectory belongs to the application; no picker or grant is opened by the SDK.
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, pluginPin);
const sink = await createOpfsFileSink(selectedDirectory, 'trace.bin', {overwrite: false});
const receipt = await streamStoredJobArtifact(client, reference, {sink, signal});
if (receipt.verification === 'stored') showSavedHash(receipt.storedSha256);The browser-safe helper receives at most one 64 KiB chunk at a time, waits for the selected sink and incrementally hashes the entire file. It validates exact ranges, identity, base64 and each chunk hash before writing. A readback sink then independently re-reads saved bytes; verification is stored only after both full hashes match. Without readback, verification is received and storedSha256 is null. Progress reaching all bytes is not completion.
The application selects file handles or OPFS directories and grants any needed permissions. Pass the explicitly selected destination and approved access to the SDK adapter; selection and permissions belong to the application. The asynchronous file/OPFS writable sinks keep staging until close and discard it on pre-commit failure. For reload-safe partials, use the dedicated Worker adapter below. File limits are 1 GiB, four direct concurrent streams and a 30-minute total deadline.
Upload Selected Files
import {uploadFile} from '@altifigence/dds-plugin-sdk/uploads';
import {createBrowserUploadSource} from '@altifigence/dds-plugin-sdk/uploads-browser';
// The operator separately configures uploads.directory/principalId/roots/fileSystem
// on the Node workspace server, and grants workspace.write to this pinned plugin.
const source = createBrowserUploadSource(selectedFile);
const status = await uploadFile(client, source, {
uploadId: crypto.randomUUID(), pluginId, artifactSha256: pluginPin,
path: 'input/trace.bin', expectedRevision: null, signal,
});
if (status.state === 'committed' && status.commitReceipt.verified) {
showCommittedUpload(status.commitReceipt);
}
// To recover a previously selected upload ID, pass the same specification and
// source with recover: true. The helper queries current authority and rehashes it.Uploads are disabled by default. The operator configures a local Node workspace, an isolated staging directory, allowed roots and one principal, then grants the selected plugin workspace.write at its exact archive pin. The helper prehashes the selected source before beginning. The server accepts sequential 64 KiB chunks, verifies duplicates and full content, and commits only after conditional target checks. No staging bytes appear in normal workspace listings.
expectedRevision: null requires a missing target; a SHA-256 requires the matching current target. Cancellation retains the acknowledged server prefix. A fresh explicit recover operation queries current authority, validates the same source/specification and resumes only the matching prefix. A lost commit response is uncertain until queried; it is not permission to repeat commit or roll back a file. Maximum limits are 1 GiB per file, 4 GiB per store and four active sessions; defaults are lower. Known 0.3–0.9 hosts report uploads disabled without probing new methods.
Schedule File Transfers
import {createTransferQueue} from '@altifigence/dds-plugin-sdk/transfer-queue';
const queue = createTransferQueue({
concurrency: 2, perConnection: 1, bufferBytes: 131072,
bytesPerSecond: 1048576, attempts: 3,
});
const unsubscribe = queue.subscribe(view => renderTransfer(view));
const download = queue.enqueueStoredDownload(client, reference, {sink});
download.pause(); // finishes the current stage, then waits at the next boundary
download.resume();
const receipt = await download.result;
queue.release(download.id);
unsubscribe(); await queue.dispose();A caller-owned queue mixes upload, live download and stored download jobs. It bounds retained jobs (32), simultaneous stages (4), client-connection concurrency, decoded chunk reservations (64–256 KiB), rate and retries. Eligible work progresses past a saturated connection, and bounded priority head starts prevent small eligible jobs from starving. A paused job finishes its current stage and then waits; pause can retain a storage lock. Total deadlines include queue wait and pause.
Automatic retry is limited to SDK-recognized 429/503, network loss or request timeout during an idempotent exact chunk operation, with bounded backoff and jitter. Begin/commit and authorization, checksum, range, source or sink failures return control to the caller for explicit review. acknowledgedBytes, transferredBytes, attemptedBytes, retriedBytes, resumedBytes and remainingBytes are separate; only a verified receipt yields completed. An already committed file stays committed after cancel/dispose.
Resume Browser Downloads
// Run inside an application-owned dedicated Worker with OPFS + Web Locks.
import {createOpfsArtifactSink} from '@altifigence/dds-plugin-sdk/artifact-resume-browser';
import {streamStoredJobArtifact} from '@altifigence/dds-plugin-sdk/artifact-transfer';
await client.connect();
const fresh = await client.getStoredJobArtifact(pluginId, jobId, artifactId, pluginPin);
const sink = createOpfsArtifactSink({
directory: selectedDirectory, partialId: selectedPartialId, reference: fresh,
});
const receipt = await streamStoredJobArtifact(client, fresh, {sink, resume: true, signal});
console.log(receipt.resumedBytes, receipt.receivedBytes, receipt.storedSha256);
// The first transfer omits resume, and refuses any existing files for that ID.
// A queue can use the same sink and explicit resume: true on a new stored download.Persistent recovery requires a dedicated Worker, OPFS sync access and Web Locks. The caller reselects its directory and partial UUID after reload and obtains a fresh approved stored reference. The sink stores two exact data/metadata filenames, the complete immutable snapshot identity, expiry and current/previous prefix hashes. It stores no token, grants or old connection scope. Each data chunk is flushed before the small metadata stream is closed.
Both sink and helper independently rehash the prefix. An uncheckpointed tail is trimmed only after the recorded prefix matches. Metadata beyond the actual file size may fall back to the previous checkpoint only if those bytes and hash match; corruption, missing entries, expiry or a different snapshot fail without silently restarting. An origin-wide exclusive lock rejects another tab, remains held through readback, and is released on close or Worker termination. Reopening then requires explicit recovery.
Local metadata is limited to 16 KiB and four open sink sessions. Retention defaults to one hour, with a 24-hour maximum capped by the host snapshot expiry. The browser manages storage quota and eviction, and same-origin scripts share its storage authority. Recovery uses the recorded checkpoints under those storage rules. Chromium 154 on Windows was exercised for cancellation, reload, host restart, two-tab conflict and owner-tab termination with full saved-file hashes. The reported checks cover that browser and operating-system combination.
npm run example:browser-artifacts
npm run example:uploads-browser
npm run example:transfer-queue-browser
npm run example:browser-resumeStreaming · Uploads · Transfer queue · Worker recovery
Signature Help and Completion Assistance
Declare signature-help, completion-resolve and completion-snippets as needed in manifest v2; completion modifiers also require completion. The host must grant document.read and language.provide. Existing literal completions remain valid. languageCapabilities() reports the SDK implementation and its limits, without granting permission.
const signatures = await host.requestLanguage('signature-help', {
position, context: {triggerKind: 'invoked', isRetrigger: false},
});
const list = await host.requestLanguage('completion', {position});
if (list.data.length) {
const detailed = list.data[0].resolveToken
? await host.resolveCompletion(list.data[0].resolveToken) : list;
const preview = host.prepareCompletion(detailed, 0);
showInsertionPreview(preview.content, preview.tabstops);
host.releaseCompletion(detailed);
}
host.releaseCompletion(list);The application supplies the current position and host; preparation returns data without writing a document or file. Signature help supports up to 16 signatures, 64 parameters each and UTF-16 parameter-label offsets. Completion resolution keeps provider data private, returns a one-use host token and fixes the selected label/insertion/range. Tokens bind provider, scope and document, expire after 60 seconds and are limited to 128 entries, 4 MiB and four actual resolver operations. Document/provider changes discard them.
Snippets support $n, ${n}, ${n:literal}, $0 and documented escapes, with mirrors and ordered tabstops. Variables, nesting, choices, transforms and executable commands are rejected. UTF-16/CRLF boundaries and overlapping extra edits are checked. Providers run as trusted code with the host process’s operating-system authority; a provider that ignores cancellation keeps its actual pending slot until it settles.
Reviewed Workspace Edits and Rename
prepare-rename returns a validated range/placeholder or null; rename returns a WorkspaceEdit proposal or null. Proposals support edit, create, move and delete over disjoint relative file paths. Current source SHA-256, destination absence, protected-path policy, UTF-16 edit geometry and limits are checked. Language capabilities authorize proposals; the workspace client supplies separately approved file access and mutation.
import {previewWorkspaceEdit, applyWorkspaceEdit, recoverWorkspaceEdit}
from '@altifigence/dds-plugin-sdk/workspace-edits';
const preview = await previewWorkspaceEdit(client, proposal);
// Show every change, conflict and required capability; obtain this exact review.
const receipt = await applyWorkspaceEdit(client, preview, {
reviewed: approvedReview, // {planId, digest} from that review
journal,
authorize: (request, {signal}) => currentHostPolicy(request, signal),
});
// After interruption, current-authority readback does not replay changes.
const observed = await recoverWorkspaceEdit(client, journal, preview.planId);The caller uses a connected authorized workspace client and a trusted journal. Preview contains complete before/after snapshots and a digest; apply requires the reviewed planId/digest and a current host policy returning true. Every file is preflighted, then each operation uses the existing per-file CAS and current write/manage capabilities. The journal persists and reads back intent before each mutation and a receipt afterward. A conflict or uncertainty stops further writes; each file commits through its own CAS operation, so an interrupted plan can contain already committed files.
The optional workspace-edits-node adapter stores a bounded journal outside the selected workspace, binds its identity and uses a single-writer lock, regular files and checksum checkpoints. After process termination, recoverStaleLock is an explicit choice and only reclaims a proven dead owner. Recovery reports applied/not-applied/conflicted/unknown from current bytes and returns the next action to the caller. Compensation creates a new inverse proposal for fresh review. On Windows, the adapter synchronizes files and performs rename operations; the reported durability checks cover process termination and recovery, with persistence governed by the filesystem and storage device. Limits include 32 changes, 1,000 edits, 256 KiB per file, an 8 MiB preview and 64 retained journal plans.
Formatting and Diagnostic Code Actions
const formatted = await host.requestLanguage('format-range', {
path: 'main.dds', range: selectedRange,
formatOptions: {tabSize: 2, insertSpaces: true, endOfLine: 'preserve'},
});
const formatProposal = host.prepareFormatting(formatted);
await host.requestDiagnostics();
const actions = await host.requestLanguage('code-actions', {
path: 'main.dds', range: selectedRange,
context: {triggerKind: 'invoked', only: ['quickfix']},
});
if (actions.data.length && !actions.data[0].disabled) {
const selected = actions.data[0].resolveToken
? await host.resolveCodeAction(actions.data[0].resolveToken) : actions;
if (!selected.data[0].disabled) {
const fixProposal = host.prepareCodeAction(selected, 0);
showWorkspaceEditProposal(fixProposal); // separate preview, review and apply
}
host.releaseCodeActions(selected);
}
host.releaseCodeActions(actions);format-document and format-range require a path and tabSize/insertSpaces options; only range formatting takes a selection. A result is null or exactly one current-file edit with the current snapshot hash. Range edits stay within the selection. endOfLine selects preserve, lf or crlf for inserted text; unedited bytes stay unchanged. Content-identical proposals normalize to null. prepareFormatting performs no write.
The host binds action requests and resolve tokens to the accepted diagnostic revision and current snapshot. Later diagnostic publication, document change or provider disposal invalidates old selections. Out-of-order diagnostic calls do not overwrite the newer accepted bundle. Up to 100 actions carry plain labels, bounded diagnostic indices, proposed edits, private resolve data or a disabled reason. Unknown command/URL/shell fields are rejected. Action edits may extend beyond the selection, so review the complete proposal; formatting and actions never approve their own writes.
Semantic Display, Folding, Hints and Symbols
import {decodeSemanticTokens} from '@altifigence/dds-plugin-sdk';
const tokens = await host.requestLanguage('semantic-tokens',
previousResultId ? {previousResultId} : {});
host.validateLanguageResult(tokens); // actual current host-owned result only
renderWhitelistedTokens(decodeSemanticTokens(tokens.data, currentDocumentText));
const folds = await host.requestLanguage('folding-ranges', {});
const hints = await host.requestLanguage('inlay-hints', {range: visibleRange});
const symbols = await host.requestLanguage('document-symbol-tree', {});
for (const result of [folds, hints, symbols]) host.validateLanguageResult(result);
// Render labels as text nodes. Release results when no longer retained.
host.releaseLanguageResult(tokens);Semantic tokens use a legend with unique names and nine host-owned style keys, plus five integers per token: delta line/start, UTF-16 length, type index and modifier bits. Tokens cannot overlap, split a surrogate, cross a line or leave the current document. The host always returns a full normalized array and a host UUID, with updateKind full/delta/fallback. A separate semantic-tokens-delta capability enables provideDelta against provider-owned previous data; the cache stores identity and token data, not old document text.
A cache base is bound to the provider, scope, URI and language, with at most eight entries, 4 MiB and 60 seconds. Ordinary increasing document versions preserve a possible delta base while making the old display result stale. A lost/expired base, null delta or mismatched provider base ID permits at most one full fallback within the original timeout. Invalid data or provider errors fail without retry. Deactivate, unregister and document replacement clear affected bases. Call validateLanguageResult immediately before rendering; a copied, released or stale object fails.
Limits are 20,000 semantic tokens, 64 token types, 16 modifiers and 64 delta edits; folding allows 1,000 ranges with depth 32 and rejects crossing ranges. Inlay hints allow 1,000 single-line plain labels within the requested range. Hierarchical symbols allow 1,000 total entries and 16 levels, with contained children/selections and ordered nonoverlapping siblings. The original flat document-symbols contract is unchanged. The browser example exercises full/delta/fallback, folding, navigation and lifecycle; an HTML-like hint remains literal text.
npm run example:assistance
npm run example:workspace-edits
npm run example:language-editing
npm run example:language-display
npm run example:language-display-browserAssistance · Reviewed edits · Formatting/actions · Display
Typed Settings and Secret References
The /settings module provides an operator-owned memory store for one plugin. A versioned definition declares each key, data schema, default, allowed user/workspace scopes and display metadata. Effective values replace each whole key in the order default < user < workspace. read(workspaceId) returns immutable values, sources and a store-wide revision. Nested objects are not recursively merged; a missing value without a default remains absent.
import {createSettingsStore} from '@altifigence/dds-plugin-sdk/settings';
const settings = createSettingsStore({schemaVersion: 1, pluginId: 'example',
version: 1, settings: {count: {
schema: {schemaVersion: 1, schema: {
type: 'integer', minimum: 1, maximum: 10, default: 2,
}}, scopes: ['user', 'workspace'], display: {label: 'Count'},
}},
});
settings.update({workspaceId: 'selected-project', scope: 'workspace',
expectedRevision: settings.read('selected-project').revision, values: {count: 4}});
const effective = settings.read('selected-project');
// Mount as createPluginHost({settings: {example: settings}, ...}).Writes validate the full transaction and use expectedRevision CAS. reset removes a key from one layer; readOnly requires a default and no writable scopes. Subscriptions coalesce synchronous changes and return disposable handles. Explicit migrate(nextDefinition, callback, options) validates the next state and commits only if its revision still matches. Failure, cancellation or timeout preserves the old definition and state. Export/import is plain data; the operator owns persistence and encryption. Limits include 64 keys, 32 workspace layers, 1 MiB exported state and one actual migration.
Workspace plugins declare settings and settings.read, and the operator mounts the matching store with that grant. context.settings is read-only and bound to the plugin and selected workspace. The /secrets resolver separately issues opaque references for a plugin, workspace, command allowlist and lifetime. The manifest must declare secrets.resolve and the host must grant it. Input fields use type: object with format: dds-secret-reference; ordinary strings and lookalike objects convey no secret authority.
Only references in validated input are available through a command’s options.secrets.withSecret. Each execution has a fresh ID; the resolver checks scope, expiry, revocation and current authorization around resolution and the callback. The callback returns undefined and receives a copy cleared on abort and every exit. Provider errors are sanitized. Put the lease before effects requiring that authority. The default reference lifetime is 60 seconds, at most one hour; limits are 128 references, 8 actual leases and 16 KiB of material. Trusted in-process code runs with the host process’s operating-system authority and can retain copies. Never put material into settings, bundles, logs or results; classify arbitrary application strings explicitly when handling sensitive data.
Structured Command Schemas and Forms
Commands may declare inputSchema and outputSchema using a schemaVersion: 1 envelope. Existing primitive parameters remain supported; declaring parameters and inputSchema together is rejected. The host validates and applies input defaults before starting a handler or job, then validates output before publishing success. Output defaults are never applied. New schema/display metadata requires a 0.12-aware peer; older strict validators reject it, while legacy definitions retain their behavior.
import {parseCommandInput, parseCommandOutput} from '@altifigence/dds-plugin-sdk';
const command = {id: 'summarize', title: 'Summarize',
inputSchema: {schemaVersion: 1, schema: {
type: 'object', additionalProperties: false,
properties: {names: {type: 'array', minItems: 1, maxItems: 8,
items: {type: 'string', minLength: 1, maxLength: 64}}}, required: ['names'],
}}, outputSchema: {schemaVersion: 1, schema: {type: 'integer', minimum: 0}},
};
const input = parseCommandInput({names: ['Ada']}, command);
parseCommandOutput(input.names.length, command);The bounded subset supports closed objects, arrays, strings, finite numbers, safe integers, booleans, null, primitive enums, bounds and validated defaults. Unknown keywords, remote references, regex, unions, coercion, accessors and custom prototypes are rejected. Schemas allow 32 KiB, depth 8 and 128 nodes; values allow 64 KiB. A complete command retains the 16 KiB metadata budget. Local DataValidationError exposes code, reason and known field paths such as /input/options/names/0; HTTP and job failures expose safe codes without rejected values.
describeDataForm returns paths, types, choices, defaults, required flags and secret-reference hints. Shared display metadata carries literal label/help/order and accessibility names, descriptions and keyboard hints. The host owns rendering and interaction. The schemas supply literal form data; the host explicitly implements rendering, resource access and command execution.
Localization and Accessibility Metadata
import {parseLocaleCatalog, resolveMessage, localizeDisplay}
from '@altifigence/dds-plugin-sdk/localization';
const catalog = parseLocaleCatalog({schemaVersion: 1, defaultLocale: 'en',
messages: {en: {title: 'Run', done: '{count} results'},
ko: {title: '실행', done: '결과 {count}개'}, ar: {}}, fallbacks: {ar: ['en']},
});
const message = resolveMessage(catalog, 'ko-KR', 'done', {count: 2});
const display = localizeDisplay(catalog, 'ko', {
labelKey: 'title', accessibility: {nameKey: 'title', shortcut: 'Control+Enter'},
});
// Render message.text as textContent; use message.locale and message.direction.
// Preserve raw values and command IDs when the display language changes.Catalogs use canonical BCP 47 base tags and explicit acyclic fallback edges. Up to eight preferences negotiate exact tags, then ancestors and the default. The default locale defines all keys; translations may omit keys but cannot invent them. Per-key lookup follows ordered fallback edges, then the default. Every translation and its arguments must match the exact {name} placeholder set. This is literal interpolation without ICU expressions. resolveMessage reports the actual source locale and direction, so English fallback inside an RTL page can retain lang=en and dir=ltr.
Number formatting supports decimal/percent; date formatting uses an explicit epoch and UTC by default; plural selection returns an Intl cardinal/ordinal category for the caller’s message choice. Hosts own Intl data and support. validateLocalizedSurfaces checks manifest/command/settings/schema keys and theme display sidecars, including resolved display lengths and missing translations. Theme JSON/XML remains compatible. Catalog limits are 32 locales, 256 keys and 256 KiB; static labels cannot contain placeholders.
The /accessibility helpers report missing names, duplicate normalized shortcuts and explicit opaque color-pair contrast in light/dark themes. Use these reports as inspection hints; the host manages operating-system key bindings and the application’s accessibility assessment. The independent example includes EN/KO, partial Arabic and long-label fixtures. It exercises scoped settings, denied/revoked references, invalid fields, Ctrl+Enter and language changes during a pending command. Browser layout was checked at desktop/mobile sizes in light/dark themes.
npm run example:configuration
npm run example:configuration-browserSettings · Secret references · Command schemas · Localization
Development Templates and Generation
Six templates, exact archive dependencies, generation review, conflict preservation and doctor checks.
Full contracts, examples and limits
Deterministic Testing and Replay
Explicit synthetic fixtures, virtual time, faults, bounded hash-only traces and resource cleanup.
Full contracts, examples and limits
Local Diagnostics and Debugging
Opt-in local profiles and a trusted child debugger with an ephemeral loopback endpoint and total deadline.
Full contracts, examples and limits
Host Conformance
18 versioned profiles distinguish supported, unsupported and failed contracts; custom adapters retain explicit authority.
Full contracts, examples and limits
SDK Support and Migration
See the export inventory, stable/optional/experimental policy, exact peers, runtime dates and migration examples.
Full contracts, examples and limits
Release Acceptance
The release’s combined fault workloads and measured performance guards document the standalone SDK’s functional behavior.
Full contracts, examples and limits
1.1 Dependency, Provenance and Update Tools
1.1.0 adds deterministic offline bundles of reviewed dependencies, CycloneDX SBOMs, detached signatures with operator-owned Ed25519 keys, digest-bound approval/activation/rollback and explicit upstream comparison. Five Node-only entry points include declarations, schemas and independent examples. The host grants execution explicitly after signature review, and old jobs retain their original hash. Operators select distribution channels and invoke activation, rollback and upstream comparison through these standalone SDK tools.
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjsComplete bundle, signature, update and upstream guide
1.2 Workflows, Cache, Tool Streams and LSP
1.2.0 adds reviewed command DAGs with per-step jobs/grants, durable checkpoints and explicit new-attempt recovery; deterministic content-based cache and incremental execution; bounded UTF-8/JSONL/text tool streams; and an optional stdio LSP 3.17 bridge. Seven new entry points bring the package to 50 exports and 107 schemas with declarations and independent installed examples, with zero runtime npm dependencies. The tool-stream parser also works in browsers; workflows, stores, external processes and LSP require Node. Actual adapters were checked with TypeScript 5.9.3 and language-server 5.3.0; the LSP bridge accepts diagnostics bound to a document version. Operators explicitly review and start workflow attempts and configure the standalone SDK host, stores and external processes.
node node_modules/@altifigence/dds-plugin-sdk/examples/workflows/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjs