scene-capability-engine 3.6.57 → 3.6.59

package/lib/commands/app.js

@@ -10,6 +10,7 @@ const { getCurrentDeviceProfile } = require('../device/current-device');
 const { loadDeviceOverride } = require('../device/device-override-store');
 const { loadAppRegistryConfig, saveAppRegistryConfig } = require('../app/registry-config');
 const { syncBundleRegistry, syncServiceCatalog } = require('../app/registry-sync-service');
+const { scaffoldEngineeringWorkspace } = require('../app/engineering-scaffold-service');
 
 function normalizeString(value) {
   if (typeof value !== 'string') {
@@ -213,27 +214,311 @@ function buildAppInstallStateItem(bundle = {}, currentDevice = null) {
   };
 }
 
-function buildEngineeringSummary(graph = {}) {
+const ENGINEERING_PREVIEW_REASON_CODES = Object.freeze({
+  SOURCE_MISSING: 'engineering.source_missing',
+  PROJECTION_MISSING: 'engineering.projection_missing',
+  WORKSPACE_UNAVAILABLE: 'engineering.workspace_unavailable',
+  HYDRATE_REQUIRED: 'engineering.hydrate_required',
+  ACTIVATE_REQUIRED: 'engineering.activate_required',
+  UPSTREAM_CONTRACT_MISSING: 'engineering.upstream_contract_missing'
+});
+
+function buildEngineeringReadinessReasonCodes(graph = {}) {
   const bundle = graph.bundle || {};
   const engineeringProject = graph.engineering_project || {};
   const metadata = engineeringProject.metadata && typeof engineeringProject.metadata === 'object'
     ? engineeringProject.metadata
     : {};
+  const attached = Boolean(
+    engineeringProject.engineering_project_id
+    || engineeringProject.repo_url
+    || engineeringProject.project_key
+    || engineeringProject.project_name
+  );
+  const sourceKnown = Boolean(normalizeString(engineeringProject.repo_url));
+  const workspacePath = normalizeString(engineeringProject.workspace_path) || null;
+  const hydrated = Boolean(metadata.hydration && metadata.hydration.status === 'ready');
+  const active = Boolean(metadata.activation && metadata.activation.active === true);
+  const reasonCodes = [];
+
+  if (!attached || !sourceKnown) {
+    reasonCodes.push(ENGINEERING_PREVIEW_REASON_CODES.SOURCE_MISSING);
+  }
+  if (!workspacePath) {
+    reasonCodes.push(ENGINEERING_PREVIEW_REASON_CODES.PROJECTION_MISSING);
+    reasonCodes.push(ENGINEERING_PREVIEW_REASON_CODES.WORKSPACE_UNAVAILABLE);
+  } else if (!hydrated) {
+    reasonCodes.push(ENGINEERING_PREVIEW_REASON_CODES.HYDRATE_REQUIRED);
+  } else if (!active) {
+    reasonCodes.push(ENGINEERING_PREVIEW_REASON_CODES.ACTIVATE_REQUIRED);
+  }
+
+  return Array.from(new Set(reasonCodes));
+}
+
+function buildEngineeringPreviewNextActions(graph = {}) {
+  const engineeringProject = graph.engineering_project || {};
+  const metadata = engineeringProject.metadata && typeof engineeringProject.metadata === 'object'
+    ? engineeringProject.metadata
+    : {};
+  const attached = Boolean(
+    engineeringProject.engineering_project_id
+    || engineeringProject.repo_url
+    || engineeringProject.project_key
+    || engineeringProject.project_name
+  );
+  const sourceKnown = Boolean(normalizeString(engineeringProject.repo_url));
+  const workspacePath = normalizeString(engineeringProject.workspace_path) || null;
+  const hydrated = Boolean(metadata.hydration && metadata.hydration.status === 'ready');
+  const active = Boolean(metadata.activation && metadata.activation.active === true);
+  const nextActions = [];
+
+  if (!attached || !sourceKnown) {
+    nextActions.push('attach');
+  }
+  if (!workspacePath || !hydrated) {
+    nextActions.push('hydrate');
+  }
+  if (workspacePath && hydrated && !active) {
+    nextActions.push('activate');
+  }
+  if (engineeringProject.dirty_state === true) {
+    nextActions.push('review_local_changes');
+  }
+
+  return Array.from(new Set(nextActions));
+}
+
+function buildEngineeringPreviewSummary(graph = {}) {
+  const bundle = graph.bundle || {};
+  const engineeringProject = graph.engineering_project || {};
+  const metadata = engineeringProject.metadata && typeof engineeringProject.metadata === 'object'
+    ? engineeringProject.metadata
+    : {};
+  const attached = Boolean(
+    engineeringProject.engineering_project_id
+    || engineeringProject.repo_url
+    || engineeringProject.project_key
+    || engineeringProject.project_name
+  );
+  const sourceKnown = Boolean(normalizeString(engineeringProject.repo_url));
+  const workspacePath = normalizeString(engineeringProject.workspace_path) || null;
+  const hydrated = Boolean(metadata.hydration && metadata.hydration.status === 'ready');
+  const active = Boolean(metadata.activation && metadata.activation.active === true);
+  const readinessReasonCodes = buildEngineeringReadinessReasonCodes(graph);
+
   return {
     app_id: bundle.app_id || null,
-    app_name: bundle.app_name || null,
-    engineering_project_id: engineeringProject.engineering_project_id || null,
-    project_name: engineeringProject.project_name || null,
-    repo_url: engineeringProject.repo_url || null,
-    current_branch: engineeringProject.current_branch || null,
-    workspace_path: engineeringProject.workspace_path || null,
-    code_version: engineeringProject.code_version || null,
-    dirty_state: engineeringProject.dirty_state === true,
-    hydrated: Boolean(metadata.hydration && metadata.hydration.status === 'ready'),
-    active: Boolean(metadata.activation && metadata.activation.active === true)
+    appKey: bundle.app_key || null,
+    appName: bundle.app_name || null,
+    engineeringProjectId: engineeringProject.engineering_project_id || null,
+    projectName: engineeringProject.project_name || null,
+    projectKey: engineeringProject.project_key || null,
+    repoUrl: engineeringProject.repo_url || null,
+    provider: engineeringProject.repo_provider || null,
+    branch: engineeringProject.current_branch || engineeringProject.default_branch || null,
+    codeVersion: engineeringProject.code_version || null,
+    workspacePath,
+    dirtyState: engineeringProject.dirty_state === true,
+    attached,
+    hydrated,
+    active,
+    sourceKnown,
+    projectionReady: Boolean(workspacePath),
+    readinessReasonCodes,
+    nextActions: buildEngineeringPreviewNextActions(graph)
+  };
+}
+
+function buildEngineeringSummary(graph = {}) {
+  const preview = buildEngineeringPreviewSummary(graph);
+  return {
+    app_id: preview.app_id,
+    app_name: preview.appName,
+    engineering_project_id: preview.engineeringProjectId,
+    project_name: preview.projectName,
+    repo_url: preview.repoUrl,
+    current_branch: preview.branch,
+    workspace_path: preview.workspacePath,
+    code_version: preview.codeVersion,
+    dirty_state: preview.dirtyState,
+    hydrated: preview.hydrated,
+    active: preview.active,
+    sourceKnown: preview.sourceKnown,
+    projectionReady: preview.projectionReady,
+    readinessReasonCodes: preview.readinessReasonCodes,
+    nextActions: preview.nextActions
+  };
+}
+
+function buildEngineeringOwnershipRelation(graph = {}, currentDevice = null) {
+  const bundle = graph.bundle || {};
+  const engineeringProject = graph.engineering_project || {};
+  const metadata = engineeringProject.metadata && typeof engineeringProject.metadata === 'object'
+    ? engineeringProject.metadata
+    : {};
+  const ownership = metadata.ownership && typeof metadata.ownership === 'object'
+    ? metadata.ownership
+    : {};
+  const sharedPolicy = normalizeString(ownership.shared_policy || ownership.sharedPolicy) || null;
+  const explicitOwnershipType = normalizeString(ownership.ownership_type || ownership.ownershipType).toLowerCase();
+  const workspacePath = normalizeString(engineeringProject.workspace_path) || null;
+  let ownershipType = 'unresolved';
+
+  if (['local', 'shared', 'unresolved'].includes(explicitOwnershipType)) {
+    ownershipType = explicitOwnershipType;
+  } else if (sharedPolicy) {
+    ownershipType = 'shared';
+  } else if (workspacePath) {
+    ownershipType = 'local';
+  }
+
+  return {
+    appKey: bundle.app_key || null,
+    workspaceId: normalizeString(bundle.workspace_id || ownership.workspace_id || ownership.workspaceId) || null,
+    userId: normalizeString(ownership.user_id || ownership.userId) || null,
+    deviceId: normalizeString(ownership.device_id || ownership.deviceId) || (ownershipType === 'local' && currentDevice ? currentDevice.device_id : null),
+    ownershipType,
+    sharedPolicy
   };
 }
 
+function buildEngineeringActionSteps(actionMode, graph = {}) {
+  const preview = buildEngineeringPreviewSummary(graph);
+  const attachReady = preview.attached && preview.sourceKnown;
+  const hydrateReady = preview.projectionReady && preview.hydrated;
+  const activateReady = preview.active;
+  const steps = [{
+    key: 'register',
+    status: 'done',
+    detail: 'App bundle is registered in SCE.'
+  }];
+
+  if (attachReady) {
+    steps.push({
+      key: 'attach',
+      status: 'done',
+      detail: 'Engineering source metadata is attached.'
+    });
+  } else {
+    steps.push({
+      key: 'attach',
+      status: 'pending',
+      reasonCode: ENGINEERING_PREVIEW_REASON_CODES.SOURCE_MISSING,
+      detail: 'Attach engineering source metadata before continuing.'
+    });
+  }
+
+  if (!attachReady) {
+    steps.push({
+      key: 'hydrate',
+      status: 'skipped',
+      reasonCode: ENGINEERING_PREVIEW_REASON_CODES.SOURCE_MISSING,
+      detail: 'Hydration is blocked until engineering source metadata is attached.'
+    });
+  } else if (!preview.projectionReady) {
+    steps.push({
+      key: 'hydrate',
+      status: 'pending',
+      reasonCode: ENGINEERING_PREVIEW_REASON_CODES.PROJECTION_MISSING,
+      detail: 'Create or bind a local engineering workspace before hydration.'
+    });
+  } else if (!preview.hydrated) {
+    steps.push({
+      key: 'hydrate',
+      status: 'pending',
+      reasonCode: ENGINEERING_PREVIEW_REASON_CODES.HYDRATE_REQUIRED,
+      detail: 'Engineering workspace exists but is not hydrated yet.'
+    });
+  } else {
+    steps.push({
+      key: 'hydrate',
+      status: 'done',
+      detail: 'Engineering workspace is hydrated.'
+    });
+  }
+
+  if (actionMode === 'import' && hydrateReady && !activateReady) {
+    steps.push({
+      key: 'activate',
+      status: 'skipped',
+      detail: 'Import completes without activation in phase-1.'
+    });
+    return steps;
+  }
+
+  if (!attachReady) {
+    steps.push({
+      key: 'activate',
+      status: 'skipped',
+      reasonCode: ENGINEERING_PREVIEW_REASON_CODES.SOURCE_MISSING,
+      detail: 'Activation is blocked until engineering source metadata is attached.'
+    });
+  } else if (!preview.projectionReady) {
+    steps.push({
+      key: 'activate',
+      status: 'skipped',
+      reasonCode: ENGINEERING_PREVIEW_REASON_CODES.PROJECTION_MISSING,
+      detail: 'Activation is blocked until a local engineering workspace is available.'
+    });
+  } else if (!preview.hydrated) {
+    steps.push({
+      key: 'activate',
+      status: 'skipped',
+      reasonCode: ENGINEERING_PREVIEW_REASON_CODES.HYDRATE_REQUIRED,
+      detail: 'Activation is blocked until hydration completes.'
+    });
+  } else if (!preview.active) {
+    steps.push({
+      key: 'activate',
+      status: 'pending',
+      reasonCode: ENGINEERING_PREVIEW_REASON_CODES.ACTIVATE_REQUIRED,
+      detail: 'Engineering workspace is ready but not active.'
+    });
+  } else {
+    steps.push({
+      key: 'activate',
+      status: 'done',
+      detail: 'Engineering workspace is active.'
+    });
+  }
+
+  return steps;
+}
+
+function buildEngineeringActionSuccess(actionMode, steps = []) {
+  if (actionMode === 'import') {
+    return ['register', 'attach', 'hydrate'].every((key) => steps.some((step) => step.key === key && step.status === 'done'));
+  }
+  return ['register', 'attach', 'hydrate', 'activate'].every((key) => steps.some((step) => step.key === key && step.status === 'done'));
+}
+
+async function runAppEngineeringActionEnvelopeCommand(actionMode, options = {}, dependencies = {}) {
+  const appRef = normalizeString(options.app);
+  if (!appRef) {
+    throw new Error('--app is required');
+  }
+  const { graph } = await requireAppGraph(appRef, dependencies);
+  const preview = buildEngineeringPreviewSummary(graph);
+  const steps = buildEngineeringActionSteps(actionMode, graph);
+  const payload = {
+    mode: actionMode,
+    generated_at: new Date().toISOString(),
+    query: {
+      app: appRef
+    },
+    success: buildEngineeringActionSuccess(actionMode, steps),
+    summary: preview,
+    preview,
+    steps,
+    bundle: graph.bundle,
+    engineering_project: graph.engineering_project,
+    scene_bindings: graph.scene_bindings || []
+  };
+  printPayload(payload, options, `App Engineering ${actionMode === 'open' ? 'Open' : 'Import'}`);
+  return payload;
+}
+
 function deriveEngineeringProjectId(bundle = {}) {
   const appKey = normalizeString(bundle.app_key);
   if (appKey) {
@@ -560,13 +845,15 @@ async function runAppEngineeringShowCommand(options = {}, dependencies = {}) {
     throw new Error('--app is required');
   }
   const { graph } = await requireAppGraph(appRef, dependencies);
+  const preview = buildEngineeringPreviewSummary(graph);
   const payload = {
     mode: 'app-engineering-show',
     generated_at: new Date().toISOString(),
     query: {
       app: appRef
     },
-    summary: buildEngineeringSummary(graph),
+    summary: preview,
+    preview,
     bundle: graph.bundle,
     engineering_project: graph.engineering_project,
     scene_bindings: graph.scene_bindings || []
@@ -575,6 +862,67 @@ async function runAppEngineeringShowCommand(options = {}, dependencies = {}) {
   return payload;
 }
 
+async function runAppEngineeringPreviewCommand(options = {}, dependencies = {}) {
+  const appRef = normalizeString(options.app);
+  if (!appRef) {
+    throw new Error('--app is required');
+  }
+  const { graph } = await requireAppGraph(appRef, dependencies);
+  const preview = buildEngineeringPreviewSummary(graph);
+  const payload = {
+    mode: 'app-engineering-preview',
+    generated_at: new Date().toISOString(),
+    query: {
+      app: appRef
+    },
+    summary: preview,
+    preview,
+    bundle: graph.bundle,
+    engineering_project: graph.engineering_project,
+    scene_bindings: graph.scene_bindings || []
+  };
+  printPayload(payload, options, 'App Engineering Preview');
+  return payload;
+}
+
+async function runAppEngineeringOwnershipCommand(options = {}, dependencies = {}) {
+  const appRef = normalizeString(options.app);
+  if (!appRef) {
+    throw new Error('--app is required');
+  }
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const { graph } = await requireAppGraph(appRef, dependencies);
+  const currentDevice = await getCurrentDeviceProfile(projectPath, {
+    fileSystem,
+    persistIfMissing: false
+  });
+  const ownership = buildEngineeringOwnershipRelation(graph, currentDevice);
+  const payload = {
+    mode: 'app-engineering-ownership',
+    generated_at: new Date().toISOString(),
+    query: {
+      app: appRef
+    },
+    summary: ownership,
+    ownership,
+    current_device: currentDevice,
+    bundle: graph.bundle,
+    engineering_project: graph.engineering_project,
+    scene_bindings: graph.scene_bindings || []
+  };
+  printPayload(payload, options, 'App Engineering Ownership');
+  return payload;
+}
+
+async function runAppEngineeringOpenCommand(options = {}, dependencies = {}) {
+  return runAppEngineeringActionEnvelopeCommand('open', options, dependencies);
+}
+
+async function runAppEngineeringImportCommand(options = {}, dependencies = {}) {
+  return runAppEngineeringActionEnvelopeCommand('import', options, dependencies);
+}
+
 async function runAppEngineeringAttachCommand(options = {}, dependencies = {}) {
   const appRef = normalizeString(options.app);
   if (!appRef) {
@@ -675,6 +1023,42 @@ async function runAppEngineeringHydrateCommand(options = {}, dependencies = {})
   return payload;
 }
 
+async function runAppEngineeringScaffoldCommand(options = {}, dependencies = {}) {
+  const appRef = normalizeString(options.app);
+  if (!appRef) {
+    throw new Error('--app is required');
+  }
+  await ensureAuthorized('app:engineering:scaffold', options, dependencies);
+  const { graph } = await requireAppGraph(appRef, dependencies);
+  const engineeringProject = graph.engineering_project || {};
+  const workspacePath = normalizeString(options.workspacePath) || normalizeString(engineeringProject.workspace_path);
+  if (!workspacePath) {
+    throw new Error('engineering workspace_path is not set; run app engineering hydrate first or pass --workspace-path');
+  }
+
+  const result = await scaffoldEngineeringWorkspace({
+    workspacePath,
+    overwritePolicy: options.overwritePolicy,
+    fileSystem: dependencies.fileSystem || fs,
+    templateRoot: dependencies.templateRoot
+  });
+  const payload = {
+    mode: 'app-engineering-scaffold',
+    generated_at: new Date().toISOString(),
+    query: {
+      app: appRef
+    },
+    success: result.failedDirectoryCount === 0 && result.failedFileCount === 0,
+    summary: result,
+    result,
+    bundle: graph.bundle,
+    engineering_project: graph.engineering_project,
+    scene_bindings: graph.scene_bindings || []
+  };
+  printPayload(payload, options, 'App Engineering Scaffold');
+  return payload;
+}
+
 async function runAppEngineeringActivateCommand(options = {}, dependencies = {}) {
   const appRef = normalizeString(options.app);
   if (!appRef) {
@@ -1246,9 +1630,37 @@ function registerAppCommands(program) {
     .command('engineering')
     .description('Manage engineering project projection for one app bundle');
 
+  engineering
+    .command('preview')
+    .description('Preview engineering readiness for one app bundle')
+    .requiredOption('--app <app-id-or-key>', 'App id or app key')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runAppEngineeringPreviewCommand, options, 'app engineering preview'));
+
+  engineering
+    .command('ownership')
+    .description('Show the read-only engineering ownership relation for one app bundle')
+    .requiredOption('--app <app-id-or-key>', 'App id or app key')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runAppEngineeringOwnershipCommand, options, 'app engineering ownership'));
+
+  engineering
+    .command('open')
+    .description('Return the canonical engineering open result envelope')
+    .requiredOption('--app <app-id-or-key>', 'App id or app key')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runAppEngineeringOpenCommand, options, 'app engineering open'));
+
+  engineering
+    .command('import')
+    .description('Return the canonical engineering import result envelope')
+    .requiredOption('--app <app-id-or-key>', 'App id or app key')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runAppEngineeringImportCommand, options, 'app engineering import'));
+
   engineering
     .command('show')
-    .description('Show engineering projection for one app bundle')
+    .description('Show engineering projection for one app bundle (compatibility alias of preview)')
     .requiredOption('--app <app-id-or-key>', 'App id or app key')
     .option('--json', 'Print machine-readable JSON output')
     .action((options) => safeRun(runAppEngineeringShowCommand, options, 'app engineering show'));
@@ -1281,6 +1693,18 @@ function registerAppCommands(program) {
     .option('--json', 'Print machine-readable JSON output')
     .action((options) => safeRun(runAppEngineeringHydrateCommand, options, 'app engineering hydrate'));
 
+  engineering
+    .command('scaffold')
+    .description('Scaffold SCE baseline files into the engineering workspace')
+    .requiredOption('--app <app-id-or-key>', 'App id or app key')
+    .option('--workspace-path <path>', 'Override workspace path for scaffold')
+    .option('--overwrite-policy <policy>', 'Overwrite policy: never, missing-only, explicit', 'missing-only')
+    .option('--auth-lease <lease-id>', 'Write authorization lease id')
+    .option('--auth-password <password>', 'Inline auth password if policy allows')
+    .option('--actor <actor>', 'Audit actor override')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runAppEngineeringScaffoldCommand, options, 'app engineering scaffold'));
+
   engineering
     .command('activate')
     .description('Activate engineering workspace for one app bundle')
@@ -1311,9 +1735,14 @@ module.exports = {
   runAppRuntimeActivateCommand,
   runAppRuntimeUninstallCommand,
   runAppInstallStateListCommand,
+  runAppEngineeringPreviewCommand,
+  runAppEngineeringOwnershipCommand,
+  runAppEngineeringOpenCommand,
+  runAppEngineeringImportCommand,
   runAppEngineeringShowCommand,
   runAppEngineeringAttachCommand,
   runAppEngineeringHydrateCommand,
+  runAppEngineeringScaffoldCommand,
   runAppEngineeringActivateCommand,
   registerAppCommands
 };

package/lib/commands/project.js

@@ -0,0 +1,105 @@
+const chalk = require('chalk');
+const { buildProjectPortfolioProjection } = require('../project/portfolio-projection-service');
+const { buildProjectSupervisionProjection } = require('../project/supervision-projection-service');
+const { resolveProjectTarget } = require('../project/target-resolution-service');
+
+async function runProjectPortfolioShowCommand(options = {}, dependencies = {}) {
+  const payload = await buildProjectPortfolioProjection(options, dependencies);
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue('Project Portfolio'));
+    console.log(`  Active Project: ${payload.activeProjectId || 'none'}`);
+    console.log(`  Visible Projects: ${payload.projects.length}`);
+  }
+  return payload;
+}
+
+async function runProjectTargetResolveCommand(options = {}, dependencies = {}) {
+  const payload = await resolveProjectTarget(options, dependencies);
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue('Project Target Resolve'));
+    console.log(`  Status: ${payload.status}`);
+    console.log(`  Resolved Project: ${payload.resolvedProjectId || 'none'}`);
+  }
+  return payload;
+}
+
+async function runProjectSupervisionShowCommand(options = {}, dependencies = {}) {
+  const payload = await buildProjectSupervisionProjection(options, dependencies);
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue('Project Supervision'));
+    console.log(`  Project: ${payload.projectId}`);
+    console.log(`  Blocked: ${payload.summary.blockedCount}`);
+    console.log(`  Handoff: ${payload.summary.handoffCount}`);
+    console.log(`  Risk: ${payload.summary.riskCount}`);
+  }
+  return payload;
+}
+
+function safeRun(handler, options = {}, context = 'project command') {
+  Promise.resolve(handler(options))
+    .catch((error) => {
+      if (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;
+    });
+}
+
+function registerProjectCommands(program) {
+  const project = program
+    .command('project')
+    .description('Inspect multi-project portfolio and routing projections');
+
+  const portfolio = project
+    .command('portfolio')
+    .description('Inspect the caller-visible project portfolio');
+
+  portfolio
+    .command('show')
+    .description('Show the canonical project portfolio projection')
+    .option('--workspace <name>', 'Resolve caller context against one registered workspace')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runProjectPortfolioShowCommand, options, 'project portfolio show'));
+
+  const target = project
+    .command('target')
+    .description('Resolve target project against the caller-visible portfolio');
+
+  target
+    .command('resolve')
+    .description('Resolve one project target without mutating active workspace selection')
+    .option('--request <text>', 'Routing request text')
+    .option('--current-project <id>', 'Caller asserted current project id')
+    .option('--workspace <name>', 'Resolve caller context against one registered workspace')
+    .option('--device <id>', 'Opaque caller device id')
+    .option('--tool-instance-id <id>', 'Opaque caller tool instance id')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runProjectTargetResolveCommand, options, 'project target resolve'));
+
+  const supervision = project
+    .command('supervision')
+    .description('Inspect project-scoped supervision projection');
+
+  supervision
+    .command('show')
+    .description('Show project-scoped supervision summary and drillback items')
+    .requiredOption('--project <id>', 'Visible project id')
+    .option('--cursor <cursor>', 'Best-effort incremental checkpoint; full snapshot remains supported')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runProjectSupervisionShowCommand, options, 'project supervision show'));
+}
+
+module.exports = {
+  runProjectPortfolioShowCommand,
+  runProjectTargetResolveCommand,
+  runProjectSupervisionShowCommand,
+  registerProjectCommands
+};

package/lib/commands/scene.js

@@ -11,6 +11,7 @@ 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 { runSceneDeliveryShowCommand } = require('../scene/delivery-projection-service');
 
 const semver = require('semver');
 const SceneLoader = require('../scene-runtime/scene-loader');
@@ -255,6 +256,20 @@ function registerSceneCommands(program) {
       await runSceneWorkspaceCommand(runSceneWorkspaceApplyCommand, options, 'scene workspace apply');
     });
 
+  const deliveryCmd = sceneCmd
+    .command('delivery')
+    .description('Inspect scene delivery projection envelopes');
+
+  deliveryCmd
+    .command('show')
+    .description('Show delivery projection for one scene and optional spec')
+    .requiredOption('--scene <id>', 'Scene id')
+    .option('--spec <id>', 'Optional spec id filter')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      await runSceneWorkspaceCommand(runSceneDeliveryShowCommand, options, 'scene delivery show');
+    });
+
   sceneCmd
     .command('validate')
     .description('Validate scene manifest from spec or file path')
@@ -16777,6 +16792,7 @@ module.exports = {
   validateSceneContributeOptions,
   runSceneContributeCommand,
   printSceneContributeSummary,
+  runSceneDeliveryShowCommand,
   runSceneWorkspaceListCommand,
   runSceneWorkspaceShowCommand,
   runSceneWorkspaceApplyCommand,