feat: ship SDK 0.12 settings, structured commands and localization

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.12.0 — 2026-10-05
+
+- Add bounded versioned settings, default/user/workspace precedence, atomic CAS,
+  subscriptions and explicit migrations that preserve prior state on failure.
+- Add operator-owned secret references with scoped leases, expiry/revocation,
+  current authorization, redacted failures and deterministic owned-buffer cleanup.
+- Validate structured command inputs/defaults and outputs in normal and job paths;
+  keep legacy parameters and reject ambiguous declarations. Add form metadata,
+  stable local field errors and explicit per-execution secret access.
+- Add locale catalogs, deterministic fallback, literal placeholders, Intl helpers,
+  display cross-checks, accessibility names/keyboard hints and contrast reports.
+  Include independent HTTP and EN/KO/RTL/long-label browser examples.
+- Retain actual normal-command/port request slots when cancellation is ignored.
+  Add types and schemas for the public contracts; keep exact published plugin
+  metadata verification through 0.11 and target new packages at `>=0.12.0 <0.13.0`.
+
 ## 0.11.0 — 2026-10-04
 
 - Add semantic full/delta tokens with bounded provider-bound caches and one full

PUBLIC_SURFACE.json

@@ -12,17 +12,19 @@
     "docs/BROWSER_RESUME.md",
     "docs/COMPATIBILITY.md",
     "docs/CONSENT.md",
+    "docs/DATA_SCHEMAS.md",
     "docs/DEVTOOLS.md",
     "docs/FILE_REVISIONS.md",
     "docs/host-contract.md",
     "docs/JOB_HISTORY.md",
     "docs/JOB_STORAGE.md",
     "docs/JOBS.md",
-    "docs/LANGUAGE_DISPLAY.md",
-    "docs/LANGUAGE.md",
     "docs/LANGUAGE_ASSISTANCE.md",
+    "docs/LANGUAGE_DISPLAY.md",
     "docs/LANGUAGE_EDITING.md",
+    "docs/LANGUAGE.md",
     "docs/LICENSING.md",
+    "docs/LOCALIZATION.md",
     "docs/OBSERVATION.md",
     "docs/performance.md",
     "docs/PROJECT_QUERIES.md",
@@ -31,14 +33,16 @@
     "docs/PROJECTS.md",
     "docs/PUBLIC_SCOPE.md",
     "docs/PUBLISHING.md",
+    "docs/SECRETS.md",
+    "docs/SETTINGS.md",
     "docs/testing.md",
     "docs/THEMES.md",
     "docs/TRANSFER_QUEUE.md",
     "docs/UPLOADS.md",
     "docs/VERIFYING.md",
+    "docs/WORKSPACE_EDITS.md",
     "docs/workspace-protocol.md",
     "docs/WORKSPACES.md",
-    "docs/WORKSPACE_EDITS.md",
     "examples/binary-artifacts/run.mjs",
     "examples/browser-artifacts/browser.html",
     "examples/browser-artifacts/browser.mjs",
@@ -52,6 +56,13 @@
     "examples/browser-resume/serve.mjs",
     "examples/browser-resume/worker.mjs",
     "examples/command-jobs/run.mjs",
+    "examples/configuration/browser.html",
+    "examples/configuration/browser.mjs",
+    "examples/configuration/catalog.mjs",
+    "examples/configuration/LICENSE",
+    "examples/configuration/plugin.mjs",
+    "examples/configuration/run.mjs",
+    "examples/configuration/serve.mjs",
     "examples/consent/prompt.mjs",
     "examples/consent/README.md",
     "examples/durable-jobs/run.mjs",
@@ -109,11 +120,11 @@
     "examples/user-workspace/project/design.sv",
     "examples/user-workspace/server.mjs",
     "examples/user-workspace/tool.mjs",
-    "examples/workspace-observation/run.mjs",
+    "examples/workspace-edits/child.mjs",
     "examples/workspace-edits/LICENSE",
     "examples/workspace-edits/plugin.mjs",
-    "examples/workspace-edits/child.mjs",
     "examples/workspace-edits/run.mjs",
+    "examples/workspace-observation/run.mjs",
     "LICENSE",
     "NOTICE",
     "package.json",
@@ -128,15 +139,17 @@
     "schemas/binary-artifact-reference.schema.json",
     "schemas/binary-artifact.schema.json",
     "schemas/browser-artifact-checkpoint.schema.json",
+    "schemas/code-action.schema.json",
     "schemas/command.schema.json",
     "schemas/completion-item.schema.json",
-    "schemas/code-action.schema.json",
-    "schemas/document-symbol-tree.schema.json",
-    "schemas/folding-ranges.schema.json",
-    "schemas/formatting-options.schema.json",
+    "schemas/data-schema.schema.json",
     "schemas/diagnostics-request.schema.json",
     "schemas/diagnostics-result.schema.json",
+    "schemas/display-metadata.schema.json",
+    "schemas/document-symbol-tree.schema.json",
     "schemas/error.schema.json",
+    "schemas/folding-ranges.schema.json",
+    "schemas/formatting-options.schema.json",
     "schemas/inlay-hints.schema.json",
     "schemas/job-artifact-content.schema.json",
     "schemas/job-capabilities.schema.json",
@@ -153,6 +166,8 @@
     "schemas/language-request.schema.json",
     "schemas/language-result.schema.json",
     "schemas/language-snippet.schema.json",
+    "schemas/locale-catalog.schema.json",
+    "schemas/localized-message.schema.json",
     "schemas/manifest.schema.json",
     "schemas/project-entry.schema.json",
     "schemas/project-query-capabilities.schema.json",
@@ -162,9 +177,14 @@
     "schemas/project-watch-capabilities.schema.json",
     "schemas/project-watch-event.schema.json",
     "schemas/project-watch-options.schema.json",
+    "schemas/secret-reference.schema.json",
+    "schemas/secret-scope.schema.json",
     "schemas/semantic-legend.schema.json",
     "schemas/semantic-tokens-delta.schema.json",
     "schemas/semantic-tokens.schema.json",
+    "schemas/settings-definition.schema.json",
+    "schemas/settings-snapshot.schema.json",
+    "schemas/settings-state.schema.json",
     "schemas/signature-help.schema.json",
     "schemas/stored-artifact-chunk.schema.json",
     "schemas/stored-artifact-list.schema.json",
@@ -180,15 +200,17 @@
     "schemas/upload-spec.schema.json",
     "schemas/upload-status.schema.json",
     "schemas/workspace-conditional-file.schema.json",
+    "schemas/workspace-edit-preview.schema.json",
+    "schemas/workspace-edit-receipt.schema.json",
+    "schemas/workspace-edit-record.schema.json",
+    "schemas/workspace-edit.schema.json",
     "schemas/workspace-file-capabilities.schema.json",
     "schemas/workspace-file-revision.schema.json",
     "schemas/workspace-project-capabilities.schema.json",
     "schemas/workspace-project-poll.schema.json",
-    "schemas/workspace-edit.schema.json",
-    "schemas/workspace-edit-preview.schema.json",
-    "schemas/workspace-edit-record.schema.json",
-    "schemas/workspace-edit-receipt.schema.json",
     "SECURITY.md",
+    "src/accessibility.d.mts",
+    "src/accessibility.mjs",
     "src/artifact-download-node.d.mts",
     "src/artifact-download-node.mjs",
     "src/artifact-resume-browser.d.mts",
@@ -206,9 +228,14 @@
     "src/artifact-transfer.mjs",
     "src/artifacts.d.mts",
     "src/artifacts.mjs",
+    "src/configuration-operations.mjs",
+    "src/configuration-values.mjs",
     "src/consent.d.mts",
     "src/consent.mjs",
     "src/contracts.mjs",
+    "src/data-schema-schemas.mjs",
+    "src/data-schema.d.mts",
+    "src/data-schema.mjs",
     "src/dev-worker.mjs",
     "src/devtools.d.mts",
     "src/devtools.mjs",
@@ -232,12 +259,15 @@
     "src/language-assistance.mjs",
     "src/language-display-schemas.mjs",
     "src/language-display.mjs",
-    "src/language-editing.mjs",
     "src/language-editing-schemas.mjs",
+    "src/language-editing.mjs",
     "src/language-registry.mjs",
     "src/language-values.mjs",
     "src/lifecycle.mjs",
     "src/limits.mjs",
+    "src/localization-schemas.mjs",
+    "src/localization.d.mts",
+    "src/localization.mjs",
     "src/node-project-context.mjs",
     "src/node-store-context.mjs",
     "src/node-workspace-context.mjs",
@@ -259,6 +289,11 @@
     "src/publishing.mjs",
     "src/schemas.d.mts",
     "src/schemas.mjs",
+    "src/secrets.d.mts",
+    "src/secrets.mjs",
+    "src/settings-host.mjs",
+    "src/settings.d.mts",
+    "src/settings.mjs",
     "src/sha256-stream.mjs",
     "src/stored-artifact-download-node.d.mts",
     "src/stored-artifact-download-node.mjs",
@@ -285,6 +320,12 @@
     "src/version.mjs",
     "src/workspace-client.d.mts",
     "src/workspace-client.mjs",
+    "src/workspace-edit-contracts.mjs",
+    "src/workspace-edit-schemas.mjs",
+    "src/workspace-edits-node.d.mts",
+    "src/workspace-edits-node.mjs",
+    "src/workspace-edits.d.mts",
+    "src/workspace-edits.mjs",
     "src/workspace-identity-node.mjs",
     "src/workspace-node.d.mts",
     "src/workspace-node.mjs",
@@ -302,12 +343,6 @@
     "src/workspace-upload-client.mjs",
     "src/workspace-upload-node.mjs",
     "src/workspace-values.mjs",
-    "src/workspace-edit-contracts.mjs",
-    "src/workspace-edit-schemas.mjs",
-    "src/workspace-edits.mjs",
-    "src/workspace-edits.d.mts",
-    "src/workspace-edits-node.mjs",
-    "src/workspace-edits-node.d.mts",
     "templates/LICENSE.proprietary.example.txt",
     "templates/publisher-disclosure.example.json"
   ]

README.md

@@ -10,6 +10,12 @@ a small ESM package, TypeScript declarations and versioned contracts. Connect
 your own workspace and tools with the Node.js host and HTTP client. The SDK has
 **zero runtime dependencies**.
 
+Version 0.12 adds [versioned settings](docs/SETTINGS.md), [execution-scoped secret
+references](docs/SECRETS.md), [structured command schemas](docs/DATA_SCHEMAS.md)
+and [localization/accessibility helpers](docs/LOCALIZATION.md). Run
+`npm run example:configuration` for the independent HTTP example or
+`npm run example:configuration-browser` for EN/KO, RTL and long-label forms.
+
 Version 0.11 adds [signature help and completion assistance](docs/LANGUAGE_ASSISTANCE.md),
 including lazy item resolution, limited snippets and pure insertion previews.
 Run `npm run example:assistance` for the nested-call and Unicode example.
@@ -34,7 +40,7 @@ application, private engines/services and production signing systems are outside
 this repository. Read the [public scope](docs/PUBLIC_SCOPE.md) and
 [compatibility table](docs/COMPATIBILITY.md) for exact boundaries.
 
-Version **0.11.0** supports Node 22 and 24. Manifest v1 diagnostic plugins remain
+Version **0.12.0** supports Node 22 and 24. Manifest v1 diagnostic plugins remain
 compatible. Manifest v2 adds commands, permission-scoped workspace and backend
 APIs, and open-source or proprietary distribution metadata. Themes export to
 the XML format already supported by DDS. The workspace host runs trusted plugins
@@ -94,7 +100,7 @@ mkdir my-dds-plugin
 cd my-dds-plugin
 npm init -y
 npm pkg set type=module
-npm install --ignore-scripts --save-exact https://github.com/Altifigence/dds-plugin-sdk/releases/download/v0.11.0/altifigence-dds-plugin-sdk-0.11.0.tgz
+npm install --ignore-scripts --save-exact https://github.com/Altifigence/dds-plugin-sdk/releases/download/v0.12.0/altifigence-dds-plugin-sdk-0.12.0.tgz
 ```
 
 Copy the example's `plugin.mjs` and `run.mjs` into this directory, then run:

docs/COMPATIBILITY.md

@@ -1,5 +1,21 @@
 # Compatibility and availability
 
+## 0.12 configuration and display
+
+[Settings](SETTINGS.md) and [secret references](SECRETS.md) are operator-owned
+optional ports. New `settings` capability, `settings.read`/`secrets.resolve`
+permissions, manifest display and [command schema metadata](DATA_SCHEMAS.md)
+require a 0.12-aware peer. Existing diagnostics, language features, commands and
+workspace protocol v1 continue to work. Older clients reject unknown metadata;
+an unchanged protocol version does not make new fields readable by an old peer.
+Keep legacy definitions when using old clients. Cancellation now retains normal
+command/port slots until actual provider settlement, as jobs already did.
+
+[Locale catalogs and accessibility helpers](LOCALIZATION.md) return display data
+and bounded inspection hints. They do not change DDS product UI or theme XML.
+New plugin archives use `>=0.12.0 <0.13.0`; verification preserves exact released
+0.3.x through 0.11.x peer metadata. An old archive's peer range is not widened.
+
 ## 0.11 language assistance and editing
 
 Optional `signature-help`, `completion-resolve` and `completion-snippets` extend the
@@ -29,7 +45,7 @@ is unchanged. These features do not establish a DDS product editor integration.
 | Browser-only DDS host | Native workspace transport is unavailable |
 | Language providers | Diagnostics plus completion, hover, definition, references and document symbols in SDK hosts since 0.3.0; no released DDS editor bridge is implied |
 | Project edit sessions | Client helpers in 0.3.0 over unchanged workspace protocol v1, including 0.2.x servers |
-| Download verification | Node API/CLI since 0.3.1; 0.11.0 accepts exact 0.3.x–0.11.x package metadata; no extraction, code execution or publisher authentication |
+| Download verification | Node API/CLI since 0.3.1; 0.12.0 accepts exact 0.3.x–0.12.x package metadata; no extraction, code execution or publisher authentication |
 | Development tools | `init`, `doctor`, `dev` since 0.4.0; local Node tools, explicit trusted-code execution |
 | Command jobs | Opt-in SDK host/client extension since 0.4.0; progress/logs/UTF-8 artifacts; v1 hello unchanged |
 | File and job observation | Client helpers since 0.5.0; 0.6 uses revision reads when supported; job reads need enabled 0.4+ hosts |

docs/DATA_SCHEMAS.md

@@ -0,0 +1,83 @@
+# Structured command data (SDK 0.12)
+
+Commands may declare `inputSchema` and `outputSchema`, each using the version-1
+envelope below. Existing `parameters` remain supported. Declaring both
+`parameters` and `inputSchema` is an error; neither silently overrides the other.
+
+```js
+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}},
+      count: {type: 'integer', minimum: 1, maximum: 10, default: 2},
+    }, required: ['names', 'count'],
+  }},
+  outputSchema: {schemaVersion: 1, schema: {type: 'integer', minimum: 0}},
+};
+const input = parseCommandInput({names: ['Ada']}, command); // count becomes 2
+parseCommandOutput(2, command);
+```
+
+The portable host applies defaults and validates inputs before invoking a handler
+or starting a job. It validates outputs before publishing success. Output defaults
+are never applied. A required output field must actually be returned. Job errors
+retain a safe error code and omit invalid results. Existing primitive parameter
+validation and commands without schemas retain their behavior.
+
+| Node type | Supported fields besides `type` and `display` |
+| --- | --- |
+| `object` | `properties`, `required`, mandatory `additionalProperties: false`, `default` |
+| `array` | mandatory `items`, `minItems`, `maxItems`, `default` |
+| `string` | `minLength`, `maxLength`, `enum`, `default` |
+| `number`, `integer` | `minimum`, `maximum`, `enum`, `default` |
+| `boolean`, `null` | `enum`, `default` |
+| Secret reference | `type: 'object', format: 'dds-secret-reference'`; no default |
+
+Numbers must be finite; integers must be safe integers. String value lengths use
+Unicode code points. Object property names use `[A-Za-z][A-Za-z0-9_.-]{0,127}`;
+`constructor`, `prototype` and `__proto__` are forbidden. Unknown value fields,
+unknown schema keywords, inconsistent ranges, duplicate enums and invalid defaults
+are rejected. This subset has no `$ref`, remote retrieval, regex, union, coercion,
+executable expression, HTML renderer or schema-supplied callback.
+
+Defaults fill absent fields, including fields inside present nested objects. They
+do not create a missing parent object unless that parent has its own valid default.
+Defaults must be independently valid without further default expansion. References
+cannot be placed in defaults, including through enclosing object/array defaults.
+`null` is a value, not a request to apply a default or reset a setting.
+
+`/data-schema` exports `parseDataSchema`, `validateDataValue` (defaults off unless
+`{applyDefaults: true}`), `collectSecretReferences` and `describeDataForm`.
+`DataValidationError` exposes `code`, `reason` and a JSON-pointer-like `path` using
+known schema property names and array indices. Command helpers prefix paths with
+`/input` or `/output`, for example `/input/options/names/0`. Unknown fields report
+their parent path without echoing an arbitrary rejected key or value. HTTP errors
+and retained job failures expose sanitized codes; run the public helpers locally
+when a form needs a detailed field path.
+
+Schemas are limited to 32 KiB, depth 8, 128 nodes, 64 properties per object and
+64 primitive enum entries. Values and expanded defaults are limited to 64 KiB;
+arrays to 256 items and strings to 16,384 code points. A complete command definition
+including both schemas still has the existing 16 KiB metadata budget. Plain JSON
+copying also has structural limits and rejects accessors, custom prototypes,
+sparse arrays, cycles, invalid Unicode and non-JSON values without invoking hooks.
+
+`display` contains literal `label`, `help`, `order`, `labelKey`, `helpKey` and
+`accessibility` metadata. `describeDataForm` returns field paths, types, required
+flags, choices, defaults and `secretReference` hints for a host-owned form. Array
+item descriptions use `/*`. The host decides how to render and edit data; display
+strings are never inserted as HTML. See [localization](LOCALIZATION.md).
+
+Declare reference fields explicitly to use [execution-scoped secrets](SECRETS.md).
+An ordinary string or an ordinary object resembling a reference conveys no secret
+authority. See the [configuration example](../examples/configuration/run.mjs) for
+actual HTTP commands and jobs, and `npm run example:configuration-browser` for forms.
+
+New schema/display metadata requires a 0.12-aware host/client. Older strict
+validators reject it. Keep legacy definitions when connecting older peers;
+protocol version 1 does not imply support for every optional metadata extension.

docs/DEVTOOLS.md

@@ -12,7 +12,7 @@ Install the released SDK in a tools directory, then create a sibling project:
 mkdir dds-tools
 cd dds-tools
 npm init -y
-npm install --ignore-scripts --save-exact https://github.com/Altifigence/dds-plugin-sdk/releases/download/v0.9.0/altifigence-dds-plugin-sdk-0.9.0.tgz
+npm install --ignore-scripts --save-exact https://github.com/Altifigence/dds-plugin-sdk/releases/download/v0.12.0/altifigence-dds-plugin-sdk-0.12.0.tgz
 npx --no-install dds-plugin init ../my-plugin --id my-plugin --publisher example
 cd ../my-plugin
 npm install --ignore-scripts