@workbench-kit/workbench-config 0.0.2-prototype.0.1.4 → 0.0.2-prototype.0.2.11

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@workbench-kit/workbench-config",
-  "version": "0.0.2-prototype.0.1.4",
+  "version": "0.0.2-prototype.0.2.11",
   "private": false,
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@workbench-kit/base": "0.0.2-prototype.0.1.4",
-    "@workbench-kit/platform": "0.0.2-prototype.0.1.4"
+    "@workbench-kit/base": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/platform": "0.0.2-prototype.0.2.11"
   },
   "files": [
     "src",

package/src/index.ts

@@ -1,3 +1,6 @@
+import { assertKnownKeys, assertRecord } from './parse-helpers.js';
+import { WorkbenchConfigValidationError } from './validation-error.js';
+
 export const WORKBENCH_KIT_WORKBENCH_CONFIG_VERSION = '0.0.0' as const;
 
 export const WORKBENCH_CONFIG_DIR = '.workbench' as const;
@@ -6,6 +9,7 @@ export type WorkbenchConfigFileName =
   | 'workspace.json'
   | 'settings.json'
   | 'keybindings.json'
+  | 'user-commands.json'
   | 'extensions.json'
   | 'extensions.lock.json'
   | 'layout.default.json'
@@ -16,8 +20,23 @@ export interface WorkbenchExtensionsConfig {
   recommendations: readonly string[];
 }
 
+export interface WorkbenchExtensionsLockEntry {
+  readonly integrity?: string | undefined;
+  readonly version: string;
+}
+
+export interface WorkbenchExtensionsLock {
+  readonly extensions: Readonly<Record<string, WorkbenchExtensionsLockEntry>>;
+  readonly lockfileVersion: number;
+}
+
 export interface WorkbenchLayoutConfig {
   readonly activityBar: {
+    readonly hiddenItemIds?: readonly string[];
+    readonly itemOrder?: readonly string[];
+    readonly visible: boolean;
+  };
+  readonly auxiliaryBar: {
     readonly visible: boolean;
   };
   readonly panel: {
@@ -25,12 +44,14 @@ export interface WorkbenchLayoutConfig {
   };
   readonly sideBar: {
     readonly activeViewContainer?: string;
+    readonly sizePercent?: number;
     readonly visible: boolean;
   };
 }
 
 export type WorkbenchLayoutConfigInput = Partial<{
   activityBar: Partial<WorkbenchLayoutConfig['activityBar']>;
+  auxiliaryBar: Partial<WorkbenchLayoutConfig['auxiliaryBar']>;
   panel: Partial<WorkbenchLayoutConfig['panel']>;
   sideBar: Partial<WorkbenchLayoutConfig['sideBar']>;
 }>;
@@ -39,6 +60,9 @@ export const DEFAULT_WORKBENCH_LAYOUT_CONFIG: WorkbenchLayoutConfig = {
   activityBar: {
     visible: true,
   },
+  auxiliaryBar: {
+    visible: false,
+  },
   panel: {
     visible: false,
   },
@@ -47,19 +71,14 @@ export const DEFAULT_WORKBENCH_LAYOUT_CONFIG: WorkbenchLayoutConfig = {
   },
 };
 
-export class WorkbenchConfigValidationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'WorkbenchConfigValidationError';
-  }
-}
+export { WorkbenchConfigValidationError };
 
 export function parseWorkbenchExtensionsConfig(input: unknown): WorkbenchExtensionsConfig {
   const record = assertRecord(input, 'extensions config');
 
   return {
-    enabled: readOptionalStringArray(record, 'enabled'),
-    recommendations: readOptionalStringArray(record, 'recommendations'),
+    enabled: readOptionalStringArrayFromExtensionsConfig(record, 'enabled'),
+    recommendations: readOptionalStringArrayFromExtensionsConfig(record, 'recommendations'),
   };
 }
 
@@ -75,31 +94,102 @@ export function parseWorkbenchExtensionsConfigJson(jsonText: string): WorkbenchE
   }
 }
 
+export function parseWorkbenchExtensionsLock(input: unknown): WorkbenchExtensionsLock {
+  const record = assertRecord(input, 'extensions lock');
+  const lockfileVersion = record.lockfileVersion;
+  if (
+    typeof lockfileVersion !== 'number' ||
+    !Number.isInteger(lockfileVersion) ||
+    lockfileVersion < 1
+  ) {
+    throw new WorkbenchConfigValidationError(
+      'Expected extensions lock "lockfileVersion" to be a positive integer.',
+    );
+  }
+
+  const extensionsRecord = assertRecord(record.extensions ?? {}, 'extensions lock extensions');
+  const extensions: Record<string, WorkbenchExtensionsLockEntry> = {};
+  for (const [extensionId, rawEntry] of Object.entries(extensionsRecord)) {
+    const entry = assertRecord(rawEntry, `extensions lock entry "${extensionId}"`);
+    if (typeof entry.version !== 'string' || entry.version.trim().length === 0) {
+      throw new WorkbenchConfigValidationError(
+        `Expected extensions lock entry "${extensionId}" to include a non-empty version.`,
+      );
+    }
+    if (entry.integrity !== undefined && typeof entry.integrity !== 'string') {
+      throw new WorkbenchConfigValidationError(
+        `Expected extensions lock entry "${extensionId}" integrity to be a string.`,
+      );
+    }
+    extensions[extensionId] = {
+      integrity: typeof entry.integrity === 'string' ? entry.integrity : undefined,
+      version: entry.version.trim(),
+    };
+  }
+
+  return {
+    extensions,
+    lockfileVersion,
+  };
+}
+
+export function parseWorkbenchExtensionsLockJson(jsonText: string): WorkbenchExtensionsLock {
+  try {
+    return parseWorkbenchExtensionsLock(JSON.parse(jsonText) as unknown);
+  } catch (error) {
+    if (error instanceof WorkbenchConfigValidationError) {
+      throw error;
+    }
+
+    throw new WorkbenchConfigValidationError('Expected extensions lock to be valid JSON.');
+  }
+}
+
 export function parseWorkbenchLayoutConfig(input: unknown): WorkbenchLayoutConfig {
   const record = assertRecord(input, 'layout config');
-  assertKnownKeys(record, ['activityBar', 'panel', 'sideBar'], 'layout config');
+  assertKnownKeys(record, ['activityBar', 'auxiliaryBar', 'panel', 'sideBar'], 'layout config');
 
   const activityBar = readOptionalRecord(record, 'activityBar');
+  const auxiliaryBar = readOptionalRecord(record, 'auxiliaryBar');
   const panel = readOptionalRecord(record, 'panel');
   const sideBar = readOptionalRecord(record, 'sideBar');
 
-  assertKnownKeys(activityBar, ['visible'], 'layout config activityBar');
+  assertKnownKeys(
+    activityBar,
+    ['hiddenItemIds', 'itemOrder', 'visible'],
+    'layout config activityBar',
+  );
+  assertKnownKeys(auxiliaryBar, ['visible'], 'layout config auxiliaryBar');
   assertKnownKeys(panel, ['visible'], 'layout config panel');
-  assertKnownKeys(sideBar, ['activeViewContainer', 'visible'], 'layout config sideBar');
+  assertKnownKeys(
+    sideBar,
+    ['activeViewContainer', 'sizePercent', 'visible'],
+    'layout config sideBar',
+  );
 
   return {
     activityBar: {
+      hiddenItemIds: readOptionalStringArray(activityBar, 'hiddenItemIds'),
+      itemOrder: readOptionalStringArray(activityBar, 'itemOrder'),
       visible: readOptionalBoolean(
         activityBar,
         'visible',
         DEFAULT_WORKBENCH_LAYOUT_CONFIG.activityBar.visible,
       ),
     },
+    auxiliaryBar: {
+      visible: readOptionalBoolean(
+        auxiliaryBar,
+        'visible',
+        DEFAULT_WORKBENCH_LAYOUT_CONFIG.auxiliaryBar.visible,
+      ),
+    },
     panel: {
       visible: readOptionalBoolean(panel, 'visible', DEFAULT_WORKBENCH_LAYOUT_CONFIG.panel.visible),
     },
     sideBar: {
       ...readOptionalLayoutId(sideBar, 'activeViewContainer'),
+      ...readOptionalSizePercent(sideBar, 'sizePercent'),
       visible: readOptionalBoolean(
         sideBar,
         'visible',
@@ -121,13 +211,37 @@ export function parseWorkbenchLayoutConfigJson(jsonText: string): WorkbenchLayou
   }
 }
 
-function assertRecord(value: unknown, label: string): Record<string, unknown> {
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-    throw new WorkbenchConfigValidationError(`Expected ${label} to be an object.`);
-  }
-
-  return value as Record<string, unknown>;
-}
+export {
+  parseWorkbenchKeybindingsConfig,
+  parseWorkbenchKeybindingsConfigJson,
+  type WorkbenchKeybindingDefinition,
+} from './keybindings-config.js';
+export {
+  parseWorkbenchSettingsConfig,
+  parseWorkbenchSettingsConfigJson,
+  type WorkbenchSettingsConfig,
+} from './settings-config.js';
+export {
+  createEmptyPreferenceValuesByScope,
+  FUTURE_PREFERENCE_SCOPES,
+  isPreferenceScope,
+  mergePreferenceValuesByScope,
+  mergeScopedPreferences,
+  PREFERENCE_SCOPE_MERGE_ORDER,
+  type FuturePreferenceScope,
+  type PreferenceScope,
+  type PreferenceValuesByScope,
+  type ScopedPreferenceLayer,
+} from './preference-scopes.js';
+export {
+  parseWorkbenchUserCommandsConfig,
+  parseWorkbenchUserCommandsConfigJson,
+  type WorkbenchUserCommandAction,
+  type WorkbenchUserCommandDefinition,
+  type WorkbenchUserCommandExecuteAction,
+  type WorkbenchUserCommandSequenceAction,
+  type WorkbenchUserCommandsConfig,
+} from './user-commands-config.js';
 
 function readOptionalRecord(record: Record<string, unknown>, key: string): Record<string, unknown> {
   const value = record[key];
@@ -143,6 +257,22 @@ function readOptionalRecord(record: Record<string, unknown>, key: string): Recor
 }
 
 function readOptionalStringArray(
+  record: Record<string, unknown>,
+  key: string,
+): readonly string[] | undefined {
+  const value = record[key];
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new WorkbenchConfigValidationError(`Expected "${key}" to be an array of strings.`);
+  }
+
+  return [...new Set(value.map((item) => item.trim()).filter(Boolean))];
+}
+
+function readOptionalStringArrayFromExtensionsConfig(
   record: Record<string, unknown>,
   key: keyof WorkbenchExtensionsConfig,
 ): readonly string[] {
@@ -193,10 +323,24 @@ function readOptionalLayoutId(
   };
 }
 
-function assertKnownKeys(record: Record<string, unknown>, keys: readonly string[], label: string) {
-  const knownKeys = new Set(keys);
-  const unknownKeys = Object.keys(record).filter((key) => !knownKeys.has(key));
-  if (unknownKeys.length > 0) {
-    throw new WorkbenchConfigValidationError(`Unexpected ${label} field "${unknownKeys[0]}".`);
+function readOptionalSizePercent(
+  record: Record<string, unknown>,
+  key: string,
+): { readonly sizePercent?: number } {
+  const value = record[key];
+  if (value === undefined) {
+    return {};
   }
+
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new WorkbenchConfigValidationError(`Expected "${key}" to be a finite number.`);
+  }
+
+  return {
+    sizePercent: clampLayoutSizePercent(value),
+  };
+}
+
+function clampLayoutSizePercent(value: number): number {
+  return Math.min(90, Math.max(10, value));
 }

package/src/keybindings-config.ts

@@ -0,0 +1,68 @@
+import {
+  assertKnownKeys,
+  assertRecord,
+  readOptionalString,
+  readRequiredString,
+} from './parse-helpers.js';
+import { WorkbenchConfigValidationError } from './validation-error.js';
+
+export interface WorkbenchKeybindingDefinition {
+  readonly args?: readonly unknown[];
+  readonly command: string;
+  readonly key: string;
+  readonly when?: string;
+}
+
+export function parseWorkbenchKeybindingsConfig(
+  input: unknown,
+): readonly WorkbenchKeybindingDefinition[] {
+  if (!Array.isArray(input)) {
+    throw new WorkbenchConfigValidationError('Expected keybindings config to be an array.');
+  }
+
+  return input.map((entry, index) => parseWorkbenchKeybindingDefinition(entry, index));
+}
+
+export function parseWorkbenchKeybindingsConfigJson(
+  jsonText: string,
+): readonly WorkbenchKeybindingDefinition[] {
+  try {
+    return parseWorkbenchKeybindingsConfig(JSON.parse(jsonText) as unknown);
+  } catch (error) {
+    if (error instanceof WorkbenchConfigValidationError) {
+      throw error;
+    }
+
+    throw new WorkbenchConfigValidationError('Expected keybindings config to be valid JSON.');
+  }
+}
+
+function parseWorkbenchKeybindingDefinition(
+  input: unknown,
+  index: number,
+): WorkbenchKeybindingDefinition {
+  const record = assertRecord(input, `keybindings[${index}]`);
+  assertKnownKeys(record, ['args', 'command', 'key', 'when'], `keybindings[${index}]`);
+
+  const args = readOptionalArgs(record);
+
+  return {
+    ...(args ? { args } : {}),
+    command: readRequiredString(record, 'command'),
+    key: readRequiredString(record, 'key'),
+    ...(readOptionalString(record, 'when') ? { when: readOptionalString(record, 'when') } : {}),
+  };
+}
+
+function readOptionalArgs(record: Record<string, unknown>): readonly unknown[] | undefined {
+  const value = record.args;
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new WorkbenchConfigValidationError('Expected "args" to be an array.');
+  }
+
+  return [...value];
+}

package/src/parse-helpers.ts

@@ -0,0 +1,46 @@
+import { WorkbenchConfigValidationError } from './validation-error.js';
+
+export function assertRecord(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new WorkbenchConfigValidationError(`Expected ${label} to be an object.`);
+  }
+
+  return value as Record<string, unknown>;
+}
+
+export function readRequiredString(record: Record<string, unknown>, key: string): string {
+  const value = record[key];
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new WorkbenchConfigValidationError(`Expected "${key}" to be a non-empty string.`);
+  }
+
+  return value.trim();
+}
+
+export function readOptionalString(
+  record: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = record[key];
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new WorkbenchConfigValidationError(`Expected "${key}" to be a non-empty string.`);
+  }
+
+  return value.trim();
+}
+
+export function assertKnownKeys(
+  record: Record<string, unknown>,
+  keys: readonly string[],
+  label: string,
+) {
+  const knownKeys = new Set(keys);
+  const unknownKeys = Object.keys(record).filter((key) => !knownKeys.has(key));
+  if (unknownKeys.length > 0) {
+    throw new WorkbenchConfigValidationError(`Unexpected ${label} field "${unknownKeys[0]}".`);
+  }
+}

package/src/preference-scopes.ts

@@ -0,0 +1,65 @@
+import type { WorkbenchSettingsConfig } from './settings-config.js';
+
+/** Runtime preference scopes supported in v1. */
+export type PreferenceScope = 'default' | 'workspace' | 'local';
+
+/** Documented future scopes — not merged or persisted yet. */
+export const FUTURE_PREFERENCE_SCOPES = ['user', 'resource', 'secret'] as const;
+
+export type FuturePreferenceScope = (typeof FUTURE_PREFERENCE_SCOPES)[number];
+
+/** Lower index = lower precedence when merging effective values. */
+export const PREFERENCE_SCOPE_MERGE_ORDER: readonly PreferenceScope[] = [
+  'default',
+  'workspace',
+  'local',
+];
+
+export type PreferenceValuesByScope = Partial<Record<PreferenceScope, WorkbenchSettingsConfig>>;
+
+export interface ScopedPreferenceLayer {
+  readonly scope: PreferenceScope;
+  readonly values: WorkbenchSettingsConfig;
+}
+
+export function isPreferenceScope(value: unknown): value is PreferenceScope {
+  return value === 'default' || value === 'workspace' || value === 'local';
+}
+
+export function mergeScopedPreferences(
+  layers: readonly ScopedPreferenceLayer[],
+): WorkbenchSettingsConfig {
+  const merged: Record<string, unknown> = {};
+
+  for (const scope of PREFERENCE_SCOPE_MERGE_ORDER) {
+    const layer = layers.find((candidate) => candidate.scope === scope);
+    if (!layer) {
+      continue;
+    }
+
+    for (const [key, value] of Object.entries(layer.values)) {
+      merged[key] = value;
+    }
+  }
+
+  return merged;
+}
+
+export function mergePreferenceValuesByScope(
+  valuesByScope: PreferenceValuesByScope,
+): WorkbenchSettingsConfig {
+  return mergeScopedPreferences(
+    PREFERENCE_SCOPE_MERGE_ORDER.flatMap((scope) => {
+      const values = valuesByScope[scope];
+      return values ? [{ scope, values }] : [];
+    }),
+  );
+}
+
+export function createEmptyPreferenceValuesByScope(): PreferenceValuesByScope {
+  return {
+    default: {},
+    local: {},
+    workspace: {},
+  };
+}

package/src/settings-config.ts

@@ -0,0 +1,23 @@
+import { WorkbenchConfigValidationError } from './validation-error.js';
+
+export type WorkbenchSettingsConfig = Readonly<Record<string, unknown>>;
+
+export function parseWorkbenchSettingsConfig(input: unknown): WorkbenchSettingsConfig {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    throw new WorkbenchConfigValidationError('Expected settings config to be an object.');
+  }
+
+  return { ...(input as Record<string, unknown>) };
+}
+
+export function parseWorkbenchSettingsConfigJson(jsonText: string): WorkbenchSettingsConfig {
+  try {
+    return parseWorkbenchSettingsConfig(JSON.parse(jsonText) as unknown);
+  } catch (error) {
+    if (error instanceof WorkbenchConfigValidationError) {
+      throw error;
+    }
+
+    throw new WorkbenchConfigValidationError('Expected settings config to be valid JSON.');
+  }
+}

package/src/user-commands-config.ts

@@ -0,0 +1,122 @@
+import {
+  assertKnownKeys,
+  assertRecord,
+  readOptionalString,
+  readRequiredString,
+} from './parse-helpers.js';
+import { WorkbenchConfigValidationError } from './validation-error.js';
+
+export interface WorkbenchUserCommandExecuteAction {
+  readonly args?: unknown;
+  readonly command: string;
+  readonly type: 'executeCommand';
+}
+
+export interface WorkbenchUserCommandSequenceAction {
+  readonly steps: readonly WorkbenchUserCommandAction[];
+  readonly type: 'sequence';
+}
+
+export type WorkbenchUserCommandAction =
+  WorkbenchUserCommandExecuteAction | WorkbenchUserCommandSequenceAction;
+
+export interface WorkbenchUserCommandDefinition {
+  readonly action: WorkbenchUserCommandAction;
+  readonly category?: string | undefined;
+  readonly command: string;
+  readonly title: string;
+}
+
+export interface WorkbenchUserCommandsConfig {
+  readonly commands: readonly WorkbenchUserCommandDefinition[];
+  readonly version?: number | undefined;
+}
+
+export function parseWorkbenchUserCommandsConfig(input: unknown): WorkbenchUserCommandsConfig {
+  const record = assertRecord(input, 'user commands config');
+  assertKnownKeys(record, ['commands', 'version'], 'user commands config');
+
+  const commands = record.commands;
+  if (!Array.isArray(commands)) {
+    throw new WorkbenchConfigValidationError('Expected "commands" to be an array.');
+  }
+
+  return {
+    commands: commands.map((entry, index) => parseUserCommandDefinition(entry, index)),
+    ...(readOptionalNumber(record, 'version') !== undefined
+      ? { version: readOptionalNumber(record, 'version') }
+      : {}),
+  };
+}
+
+export function parseWorkbenchUserCommandsConfigJson(
+  jsonText: string,
+): WorkbenchUserCommandsConfig {
+  try {
+    return parseWorkbenchUserCommandsConfig(JSON.parse(jsonText) as unknown);
+  } catch (error) {
+    if (error instanceof WorkbenchConfigValidationError) {
+      throw error;
+    }
+
+    throw new WorkbenchConfigValidationError('Expected user commands config to be valid JSON.');
+  }
+}
+
+function parseUserCommandDefinition(input: unknown, index: number): WorkbenchUserCommandDefinition {
+  const record = assertRecord(input, `user commands[${index}]`);
+  assertKnownKeys(record, ['action', 'category', 'command', 'title'], `user commands[${index}]`);
+
+  return {
+    action: parseUserCommandAction(record.action, `user commands[${index}].action`),
+    ...(readOptionalString(record, 'category')
+      ? { category: readOptionalString(record, 'category') }
+      : {}),
+    command: readRequiredString(record, 'command'),
+    title: readRequiredString(record, 'title'),
+  };
+}
+
+function parseUserCommandAction(input: unknown, label: string): WorkbenchUserCommandAction {
+  const record = assertRecord(input, label);
+  const type = readRequiredString(record, 'type');
+
+  if (type === 'executeCommand') {
+    assertKnownKeys(record, ['args', 'command', 'type'], label);
+    return {
+      ...(record.args !== undefined ? { args: record.args } : {}),
+      command: readRequiredString(record, 'command'),
+      type,
+    };
+  }
+
+  if (type === 'sequence') {
+    assertKnownKeys(record, ['steps', 'type'], label);
+    const steps = record.steps;
+    if (!Array.isArray(steps) || steps.length === 0) {
+      throw new WorkbenchConfigValidationError(
+        `Expected "${label}.steps" to be a non-empty array.`,
+      );
+    }
+
+    return {
+      steps: steps.map((step, index) => parseUserCommandAction(step, `${label}.steps[${index}]`)),
+      type,
+    };
+  }
+
+  throw new WorkbenchConfigValidationError(`Unexpected ${label} type "${type}".`);
+}
+
+function readOptionalNumber(record: Record<string, unknown>, key: string): number | undefined {
+  const value = record[key];
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new WorkbenchConfigValidationError(`Expected "${key}" to be a finite number.`);
+  }
+
+  return value;
+}

package/src/validation-error.ts

@@ -0,0 +1,6 @@
+export class WorkbenchConfigValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorkbenchConfigValidationError';
+  }
+}