scene-capability-engine 3.6.53 → 3.6.55

package/lib/commands/scene.js

@@ -5,6 +5,12 @@ const { spawnSync } = require('child_process');
 const fs = require('fs-extra');
 const chalk = require('chalk');
 const yaml = require('js-yaml');
+const { listSceneWorkspaces, getSceneWorkspace } = require('../app/scene-workspace-store');
+const { buildSceneWorkspaceApplyPlan } = require('../app/install-plan-service');
+const { executeInstallPlan } = require('../app/install-apply-runner');
+const { runAppRuntimeInstallCommand, runAppRuntimeActivateCommand, runAppRuntimeUninstallCommand } = require('./app');
+const { loadDeviceOverride } = require('../device/device-override-store');
+const { getCurrentDeviceProfile } = require('../device/current-device');
 
 const semver = require('semver');
 const SceneLoader = require('../scene-runtime/scene-loader');
@@ -50,6 +56,19 @@ const SCENE_ROUTE_POLICY_DIFF_KEYS = [
   'mode_bias.commit.critical',
   'max_alternatives'
 ];
+
+async function runSceneWorkspaceCommand(handler, options = {}, context = 'scene workspace command') {
+  try {
+    await handler(options);
+  } catch (error) {
+    if (options && options.json) {
+      console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+    } else {
+      console.error(chalk.red(`${context} failed:`), error.message);
+    }
+    process.exitCode = 1;
+  }
+}
 const SCENE_PACKAGE_API_VERSION = 'sce.scene.package/v0.1';
 const SCENE_PACKAGE_KINDS = new Set([
   'scene-template',
@@ -202,6 +221,40 @@ function registerSceneCommands(program) {
     .command('scene')
     .description('Execute scene contracts with runtime guardrails');
 
+  const workspaceCmd = sceneCmd
+    .command('workspace')
+    .description('Inspect file-backed scene workspace intent definitions');
+
+  workspaceCmd
+    .command('list')
+    .description('List scene workspace definitions from .sce/app/scene-profiles')
+    .option('--limit <n>', 'Maximum rows', '100')
+    .option('--status <status>', 'Filter by workspace status')
+    .option('--query <text>', 'Free-text query against id/name/description/tags/collections')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      await runSceneWorkspaceCommand(runSceneWorkspaceListCommand, options, 'scene workspace list');
+    });
+
+  workspaceCmd
+    .command('show')
+    .description('Show one scene workspace definition')
+    .requiredOption('--workspace <id>', 'Workspace id or file basename')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      await runSceneWorkspaceCommand(runSceneWorkspaceShowCommand, options, 'scene workspace show');
+    });
+
+  workspaceCmd
+    .command('apply')
+    .description('Build a plan-first apply diff for one scene workspace')
+    .requiredOption('--workspace <id>', 'Workspace id or file basename')
+    .option('--execute', 'Reserved for future explicit execution; currently returns a blocked plan')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      await runSceneWorkspaceCommand(runSceneWorkspaceApplyCommand, options, 'scene workspace apply');
+    });
+
   sceneCmd
     .command('validate')
     .description('Validate scene manifest from spec or file path')
@@ -6883,6 +6936,178 @@ function printScaffoldSummary(options, summary) {
   console.log(`  Dry Run: ${summary.dry_run ? 'yes' : 'no'}`);
 }
 
+async function runSceneWorkspaceListCommand(rawOptions = {}, dependencies = {}) {
+  const options = rawOptions && typeof rawOptions === 'object' ? rawOptions : {};
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const limitCandidate = Number.parseInt(`${options.limit || 100}`, 10);
+  const limit = Number.isFinite(limitCandidate) && limitCandidate > 0 ? Math.min(limitCandidate, 1000) : 100;
+  const workspaces = await listSceneWorkspaces(projectRoot, {
+    fileSystem,
+    query: options.query,
+    status: options.status
+  });
+  const items = workspaces.slice(0, limit).map((item) => ({
+    workspace_id: item.workspace_id,
+    name: item.name,
+    description: item.description,
+    status: item.status,
+    item_count: item.item_count,
+    collection_ref_count: item.collection_refs.length,
+    tags: item.tags,
+    source_file: item.source_file
+  }));
+  const payload = {
+    mode: 'scene-workspace-list',
+    generated_at: new Date().toISOString(),
+    query: {
+      limit,
+      status: typeof options.status === 'string' ? options.status.trim() || null : null,
+      query: typeof options.query === 'string' ? options.query.trim() || null : null
+    },
+    summary: {
+      total: items.length
+    },
+    items,
+    view_model: {
+      type: 'table',
+      columns: ['workspace_id', 'name', 'status', 'item_count', 'collection_ref_count', 'source_file']
+    }
+  };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue(`Scene Workspace List (${items.length})`));
+    items.forEach((item) => {
+      console.log(`  - ${item.workspace_id} | ${item.name} | ${item.status} | items=${item.item_count}`);
+    });
+  }
+  return payload;
+}
+
+async function runSceneWorkspaceShowCommand(rawOptions = {}, dependencies = {}) {
+  const options = rawOptions && typeof rawOptions === 'object' ? rawOptions : {};
+  const workspaceRef = typeof options.workspace === 'string' ? options.workspace.trim() : '';
+  if (!workspaceRef) {
+    throw new Error('--workspace is required');
+  }
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const workspace = await getSceneWorkspace(projectRoot, workspaceRef, { fileSystem });
+  if (!workspace) {
+    throw new Error(`scene workspace not found: ${workspaceRef}`);
+  }
+  const payload = {
+    mode: 'scene-workspace-show',
+    generated_at: new Date().toISOString(),
+    query: {
+      workspace: workspaceRef
+    },
+    summary: {
+      workspace_id: workspace.workspace_id,
+      name: workspace.name,
+      status: workspace.status,
+      item_count: workspace.item_count,
+      collection_ref_count: workspace.collection_refs.length
+    },
+    workspace
+  };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue('Scene Workspace Show'));
+    console.log(`  Workspace: ${payload.summary.workspace_id}`);
+    console.log(`  Name: ${payload.summary.name}`);
+    console.log(`  Status: ${payload.summary.status}`);
+    console.log(`  Items: ${payload.summary.item_count}`);
+    console.log(`  Collection Refs: ${payload.summary.collection_ref_count}`);
+  }
+  return payload;
+}
+
+async function runSceneWorkspaceApplyCommand(rawOptions = {}, dependencies = {}) {
+  const options = rawOptions && typeof rawOptions === 'object' ? rawOptions : {};
+  const workspaceRef = typeof options.workspace === 'string' ? options.workspace.trim() : '';
+  if (!workspaceRef) {
+    throw new Error('--workspace is required');
+  }
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const stateStore = dependencies.stateStore || require('../state/sce-state-store').getSceStateStore(projectRoot, {
+    fileSystem,
+    env: dependencies.env || process.env
+  });
+  const currentDevice = await getCurrentDeviceProfile(projectRoot, {
+    fileSystem,
+    persistIfMissing: false
+  });
+  const deviceOverride = await loadDeviceOverride(projectRoot, { fileSystem });
+  const plan = await buildSceneWorkspaceApplyPlan(projectRoot, {
+    fileSystem,
+    store: stateStore,
+    workspaceRef,
+    currentDevice,
+    deviceOverride
+  });
+  const execution = options.execute
+    ? await executeInstallPlan(plan, {
+      store: stateStore,
+      executeInstall: runAppRuntimeInstallCommand,
+      executeActivate: runAppRuntimeActivateCommand,
+      executeUninstall: runAppRuntimeUninstallCommand,
+      dependencies: {
+        projectPath: projectRoot,
+        projectRoot,
+        fileSystem,
+        env: dependencies.env || process.env,
+        stateStore
+      },
+      commandOptions: options
+    })
+    : {
+      execute_supported: true,
+      executed: false,
+      blocked_reason: null,
+      results: []
+    };
+  const payload = {
+    mode: 'scene-workspace-apply',
+    generated_at: new Date().toISOString(),
+    execute_supported: execution.execute_supported,
+    executed: execution.executed,
+    execution_blocked_reason: execution.blocked_reason,
+    execution: {
+      results: execution.results,
+      preflight_failures: execution.preflight_failures || []
+    },
+    current_device: currentDevice,
+    device_override: deviceOverride,
+    summary: {
+      source_type: plan.source.type,
+      source_id: plan.source.id,
+      desired_app_count: plan.desired_apps.length,
+      install_count: plan.counts.install,
+      activate_count: plan.counts.activate,
+      uninstall_count: plan.counts.uninstall,
+      keep_count: plan.counts.keep,
+      skip_count: plan.counts.skip
+    },
+    plan
+  };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue('Scene Workspace Apply'));
+    console.log(`  Workspace: ${payload.summary.source_id}`);
+    console.log(`  Desired Apps: ${payload.summary.desired_app_count}`);
+    console.log(`  Install: ${payload.summary.install_count}`);
+    console.log(`  Uninstall: ${payload.summary.uninstall_count}`);
+    console.log(`  Keep: ${payload.summary.keep_count}`);
+    console.log(`  Skip: ${payload.summary.skip_count}`);
+  }
+  return payload;
+}
+
 async function runSceneValidateCommand(rawOptions = {}, dependencies = {}) {
   const projectRoot = dependencies.projectRoot || process.cwd();
   const sceneLoader = dependencies.sceneLoader || new SceneLoader({ projectPath: projectRoot });
@@ -16552,6 +16777,9 @@ module.exports = {
   validateSceneContributeOptions,
   runSceneContributeCommand,
   printSceneContributeSummary,
+  runSceneWorkspaceListCommand,
+  runSceneWorkspaceShowCommand,
+  runSceneWorkspaceApplyCommand,
   normalizeOntologyOptions,
   validateOntologyOptions,
   normalizeOntologyImpactOptions,

package/lib/device/current-device.js

@@ -0,0 +1,158 @@
+const crypto = require('crypto');
+const os = require('os');
+const path = require('path');
+const fs = require('fs-extra');
+const { MachineIdentifier } = require('../lock/machine-identifier');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeStringArray(value, fallback = []) {
+  if (!Array.isArray(value)) {
+    return [...fallback];
+  }
+  const seen = new Set();
+  const items = [];
+  for (const entry of value) {
+    const normalized = normalizeString(entry);
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    items.push(normalized);
+  }
+  return items;
+}
+
+function safeHostname() {
+  try {
+    return os.hostname() || 'unknown-host';
+  } catch (_error) {
+    return 'unknown-host';
+  }
+}
+
+function safeUsername() {
+  try {
+    return os.userInfo().username || process.env.USER || process.env.USERNAME || 'unknown-user';
+  } catch (_error) {
+    return process.env.USER || process.env.USERNAME || 'unknown-user';
+  }
+}
+
+function buildEphemeralDeviceId({ hostname, user, platform, arch }) {
+  const hash = crypto
+    .createHash('sha1')
+    .update(`${hostname}::${user}::${platform}::${arch}`)
+    .digest('hex')
+    .slice(0, 12);
+  return `${hostname}-ephemeral-${hash}`;
+}
+
+function buildDefaultCapabilityTags({ platform, arch }) {
+  const tags = ['desktop'];
+  if (platform) {
+    tags.push(platform);
+  }
+  if (arch) {
+    tags.push(arch);
+  }
+  if (platform && arch) {
+    tags.push(`${platform}-${arch}`);
+  }
+  return normalizeStringArray(tags);
+}
+
+async function readJsonIfExists(filePath, fileSystem) {
+  if (!await fileSystem.pathExists(filePath)) {
+    return null;
+  }
+  return fileSystem.readJson(filePath);
+}
+
+async function getCurrentDeviceProfile(projectPath = process.cwd(), options = {}) {
+  const fileSystem = options.fileSystem || fs;
+  const configDir = options.configDir || path.join(projectPath, '.sce', 'config');
+  const machineIdFile = options.machineIdFile || path.join(configDir, 'machine-id.json');
+  const profilePath = options.profilePath || path.join(projectPath, '.sce', 'state', 'device', 'device-current.json');
+  const persistIfMissing = options.persistIfMissing === true;
+  const fallbackPlatform = normalizeString(options.platform) || os.platform();
+  const fallbackArch = normalizeString(options.arch) || os.arch();
+  const fallbackHostname = normalizeString(options.hostname) || safeHostname();
+  const fallbackUser = normalizeString(options.user) || safeUsername();
+
+  let machineInfo = null;
+  let identitySource = 'ephemeral-device-fingerprint';
+
+  if (persistIfMissing) {
+    const machineIdentifier = options.machineIdentifier || new MachineIdentifier(configDir);
+    machineInfo = await machineIdentifier.getMachineInfo();
+    identitySource = 'machine-identifier';
+  } else {
+    const persistedMachineId = await readJsonIfExists(machineIdFile, fileSystem);
+    if (persistedMachineId && typeof persistedMachineId === 'object') {
+      machineInfo = {
+        id: normalizeString(persistedMachineId.id),
+        hostname: normalizeString(persistedMachineId.hostname) || fallbackHostname,
+        createdAt: normalizeString(persistedMachineId.createdAt) || null,
+        platform: fallbackPlatform,
+        user: fallbackUser
+      };
+      if (machineInfo.id) {
+        identitySource = 'machine-identifier';
+      } else {
+        machineInfo = null;
+      }
+    }
+  }
+
+  if (!machineInfo) {
+    machineInfo = {
+      id: buildEphemeralDeviceId({
+        hostname: fallbackHostname,
+        user: fallbackUser,
+        platform: fallbackPlatform,
+        arch: fallbackArch
+      }),
+      hostname: fallbackHostname,
+      createdAt: null,
+      platform: fallbackPlatform,
+      user: fallbackUser
+    };
+  }
+
+  const profile = await readJsonIfExists(profilePath, fileSystem);
+  const normalizedProfile = profile && typeof profile === 'object' ? profile : {};
+  const platform = normalizeString(normalizedProfile.platform) || normalizeString(machineInfo.platform) || fallbackPlatform;
+  const arch = normalizeString(normalizedProfile.arch) || fallbackArch;
+  const capabilityTags = normalizeStringArray(
+    normalizedProfile.capability_tags || normalizedProfile.capabilityTags,
+    buildDefaultCapabilityTags({ platform, arch })
+  );
+
+  return {
+    device_id: normalizeString(normalizedProfile.device_id || normalizedProfile.deviceId || normalizedProfile.id) || machineInfo.id,
+    hostname: normalizeString(normalizedProfile.hostname) || normalizeString(machineInfo.hostname) || fallbackHostname,
+    label: normalizeString(normalizedProfile.label || normalizedProfile.name) || normalizeString(machineInfo.hostname) || fallbackHostname,
+    platform,
+    arch,
+    user: normalizeString(normalizedProfile.user) || normalizeString(machineInfo.user) || fallbackUser,
+    created_at: normalizeString(normalizedProfile.created_at || normalizedProfile.createdAt) || normalizeString(machineInfo.createdAt) || null,
+    capability_tags: capabilityTags,
+    metadata: normalizedProfile.metadata && typeof normalizedProfile.metadata === 'object' ? normalizedProfile.metadata : {},
+    profile_path: profile ? profilePath : null,
+    identity_source: profile
+      ? `${identitySource}+device-profile`
+      : identitySource,
+    persistent_id_available: identitySource === 'machine-identifier'
+  };
+}
+
+module.exports = {
+  getCurrentDeviceProfile,
+  buildDefaultCapabilityTags
+};

package/lib/device/device-override-store.js

@@ -0,0 +1,157 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const seen = new Set();
+  const items = [];
+  for (const entry of value) {
+    const normalized = normalizeString(entry);
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    items.push(normalized);
+  }
+  return items;
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  return fallback;
+}
+
+function normalizeOverrideItem(item = {}) {
+  return {
+    app_id: normalizeString(item.app_id || item.appId) || null,
+    app_key: normalizeString(item.app_key || item.appKey) || null,
+    required: normalizeBoolean(item.required, false),
+    allow_local_remove: normalizeBoolean(item.allow_local_remove ?? item.allowLocalRemove, true),
+    priority: Number.isFinite(Number(item.priority)) ? Number(item.priority) : null,
+    default_entry: normalizeString(item.default_entry || item.defaultEntry) || null,
+    capability_tags: normalizeStringArray(item.capability_tags || item.capabilityTags),
+    metadata: item.metadata && typeof item.metadata === 'object' ? item.metadata : {}
+  };
+}
+
+function overrideItemKey(item = {}) {
+  return normalizeString(item.app_id) || normalizeString(item.app_key);
+}
+
+function normalizeDeviceOverride(raw = {}, filePath = null) {
+  const addedApps = Array.isArray(raw.added_apps || raw.addedApps)
+    ? (raw.added_apps || raw.addedApps)
+      .filter((item) => item && typeof item === 'object')
+      .map((item) => normalizeOverrideItem(item))
+      .filter((item) => item.app_id || item.app_key)
+    : [];
+
+  const dedupedAddedApps = [];
+  const seen = new Set();
+  for (const item of addedApps) {
+    const key = overrideItemKey(item);
+    if (!key || seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    dedupedAddedApps.push(item);
+  }
+
+  return {
+    removed_apps: normalizeStringArray(raw.removed_apps || raw.removedApps),
+    added_apps: dedupedAddedApps,
+    metadata: raw.metadata && typeof raw.metadata === 'object' ? raw.metadata : {},
+    source_file: filePath
+  };
+}
+
+function hasOwn(object, key) {
+  return Boolean(object) && Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function mergeDeviceOverride(existing = {}, patch = {}, filePath = null) {
+  const normalizedExisting = normalizeDeviceOverride(existing, filePath);
+  const nextRaw = {
+    removed_apps: normalizedExisting.removed_apps,
+    added_apps: normalizedExisting.added_apps,
+    metadata: normalizedExisting.metadata
+  };
+
+  if (hasOwn(patch, 'removed_apps') || hasOwn(patch, 'removedApps')) {
+    nextRaw.removed_apps = patch.removed_apps || patch.removedApps;
+  }
+
+  if (hasOwn(patch, 'added_apps') || hasOwn(patch, 'addedApps')) {
+    nextRaw.added_apps = patch.added_apps || patch.addedApps;
+  }
+
+  if (hasOwn(patch, 'metadata')) {
+    const patchMetadata = patch.metadata && typeof patch.metadata === 'object' ? patch.metadata : {};
+    nextRaw.metadata = {
+      ...normalizedExisting.metadata,
+      ...patchMetadata
+    };
+  }
+
+  return normalizeDeviceOverride(nextRaw, filePath);
+}
+
+async function loadDeviceOverride(projectPath = process.cwd(), options = {}) {
+  const fileSystem = options.fileSystem || fs;
+  const filePath = options.filePath || path.join(projectPath, '.sce', 'state', 'device', 'device-override.json');
+  if (!await fileSystem.pathExists(filePath)) {
+    return normalizeDeviceOverride({}, null);
+  }
+  const raw = await fileSystem.readJson(filePath);
+  return normalizeDeviceOverride(raw, filePath);
+}
+
+async function saveDeviceOverride(projectPath = process.cwd(), override = {}, options = {}) {
+  const fileSystem = options.fileSystem || fs;
+  const filePath = options.filePath || path.join(projectPath, '.sce', 'state', 'device', 'device-override.json');
+  const normalized = normalizeDeviceOverride(override, filePath);
+  await fileSystem.ensureDir(path.dirname(filePath));
+  await fileSystem.writeJson(filePath, {
+    removed_apps: normalized.removed_apps,
+    added_apps: normalized.added_apps,
+    metadata: normalized.metadata
+  }, { spaces: 2 });
+  return normalizeDeviceOverride({
+    removed_apps: normalized.removed_apps,
+    added_apps: normalized.added_apps,
+    metadata: normalized.metadata
+  }, filePath);
+}
+
+async function upsertDeviceOverride(projectPath = process.cwd(), patch = {}, options = {}) {
+  const fileSystem = options.fileSystem || fs;
+  const filePath = options.filePath || path.join(projectPath, '.sce', 'state', 'device', 'device-override.json');
+  const existing = await loadDeviceOverride(projectPath, {
+    fileSystem,
+    filePath
+  });
+  const merged = mergeDeviceOverride(existing, patch, filePath);
+  return saveDeviceOverride(projectPath, merged, {
+    fileSystem,
+    filePath
+  });
+}
+
+module.exports = {
+  loadDeviceOverride,
+  normalizeDeviceOverride,
+  mergeDeviceOverride,
+  saveDeviceOverride,
+  upsertDeviceOverride
+};