scene-capability-engine 3.6.65 → 3.6.67

package/lib/project/project-channel-projection.js

@@ -0,0 +1,181 @@
+const fs = require('fs-extra');
+const { ProjectChannelContextStore } = require('../runtime/project-channel-context-store');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function safeIsoAt(value) {
+  const normalized = normalizeString(value);
+  if (!normalized) {
+    return null;
+  }
+  const time = Date.parse(normalized);
+  return Number.isFinite(time) ? new Date(time).toISOString() : null;
+}
+
+function buildEmptyProjectChannelProjection() {
+  return {
+    summary: {
+      available: false,
+      contextProjectId: null,
+      canonicalProjectIdMatched: false,
+      focusedChannelId: null,
+      channelCount: 0,
+      storageMode: 'none'
+    },
+    resolvedChannel: null,
+    channels: [],
+    partial: false,
+    partialReasons: []
+  };
+}
+
+function sortChannels(channels = [], focusedChannelId = '') {
+  const normalizedFocusedChannelId = normalizeString(focusedChannelId);
+  return [...channels].sort((left, right) => {
+    const leftFocused = normalizeString(left && left.channelId) === normalizedFocusedChannelId ? 0 : 1;
+    const rightFocused = normalizeString(right && right.channelId) === normalizedFocusedChannelId ? 0 : 1;
+    if (leftFocused !== rightFocused) {
+      return leftFocused - rightFocused;
+    }
+    return `${left && left.channelId ? left.channelId : ''}`.localeCompare(`${right && right.channelId ? right.channelId : ''}`);
+  });
+}
+
+function buildChannelSummary(channel = {}, focusedChannelId = '') {
+  const channelId = normalizeString(channel.channelId);
+  return {
+    channelId,
+    focused: channelId === normalizeString(focusedChannelId),
+    activeScene: normalizeString(channel.activeScene) || null,
+    activeSpecId: normalizeString(channel.activeSpecId) || null,
+    activeDoc: normalizeString(channel.activeDoc) || null,
+    activeSessionPath: normalizeString(channel.activeSessionPath) || null,
+    runState: normalizeString(channel.runState) || null,
+    updatedAt: safeIsoAt(channel.updatedAt),
+    ...(channel.agentRuntime && typeof channel.agentRuntime === 'object'
+      ? {
+          agentRuntime: {
+            agentId: normalizeString(channel.agentRuntime.agentId) || null,
+            backendProfile: normalizeString(channel.agentRuntime.backendProfile) || null,
+            runtimeSessionId: normalizeString(channel.agentRuntime.runtimeSessionId) || null
+          }
+        }
+      : {})
+  };
+}
+
+async function listPersistedProjectChannelIds(projectRoot, fileSystem = fs) {
+  const store = new ProjectChannelContextStore(projectRoot, fileSystem);
+  const contexts = await store.listPersistedContexts();
+  return contexts.map((item) => item.projectId);
+}
+
+function chooseContextProjectId(projectIds = [], preferredProjectIds = []) {
+  const preferred = preferredProjectIds
+    .map((value) => normalizeString(value))
+    .filter(Boolean);
+  for (const preferredProjectId of preferred) {
+    if (projectIds.includes(preferredProjectId)) {
+      return {
+        projectId: preferredProjectId,
+        ambiguous: false
+      };
+    }
+  }
+  if (projectIds.length === 1) {
+    return {
+      projectId: projectIds[0],
+      ambiguous: false
+    };
+  }
+  return {
+    projectId: null,
+    ambiguous: projectIds.length > 1
+  };
+}
+
+async function buildProjectChannelProjection(projectRoot, options = {}, dependencies = {}) {
+  const fileSystem = dependencies.fileSystem || fs;
+  const store = dependencies.projectChannelContextStore || new ProjectChannelContextStore(projectRoot, fileSystem);
+  const preferredProjectIds = Array.isArray(options.preferredProjectIds)
+    ? options.preferredProjectIds
+    : [];
+  const requestedChannelId = normalizeString(options.channelId);
+  const partialReasons = [];
+
+  let projectIds = [];
+  let persistedContexts = [];
+  try {
+    persistedContexts = await store.listPersistedContexts();
+    projectIds = persistedContexts.map((item) => item.projectId);
+  } catch (_error) {
+    partialReasons.push('project_channel_context_unavailable');
+  }
+
+  const resolution = chooseContextProjectId(projectIds, preferredProjectIds);
+  if (resolution.ambiguous) {
+    partialReasons.push('project_channel_context_ambiguous');
+  }
+  if (!resolution.projectId) {
+    return {
+      ...buildEmptyProjectChannelProjection(),
+      partial: partialReasons.length > 0,
+      partialReasons
+    };
+  }
+
+  let context;
+  try {
+    context = await store.load(resolution.projectId, {
+      allowDefaultChannelSynthesis: false
+    });
+  } catch (_error) {
+    return {
+      ...buildEmptyProjectChannelProjection(),
+      partial: true,
+      partialReasons: [...partialReasons, 'project_channel_context_unavailable']
+    };
+  }
+
+  const focusedChannelId = normalizeString(context.focusedChannelId) || null;
+  const channels = sortChannels(
+    Object.values(context.channels || {}).map((channel) => buildChannelSummary(channel, focusedChannelId)),
+    focusedChannelId
+  );
+  if (channels.length === 0) {
+    partialReasons.push('project_channel_context_empty');
+  }
+  const resolvedChannel = channels.find((channel) => channel.channelId === requestedChannelId)
+    || channels.find((channel) => channel.focused)
+    || null;
+  const contextProjectId = normalizeString(context.projectId) || resolution.projectId;
+  const canonicalProjectIdMatched = preferredProjectIds.includes(contextProjectId);
+  const storageRecord = persistedContexts.find((item) => item.projectId === contextProjectId)
+    || persistedContexts.find((item) => item.projectId === resolution.projectId)
+    || null;
+
+  return {
+    summary: {
+      available: true,
+      contextProjectId,
+      canonicalProjectIdMatched,
+      focusedChannelId,
+      channelCount: channels.length,
+      storageMode: storageRecord ? storageRecord.storageMode : 'unknown'
+    },
+    resolvedChannel,
+    channels,
+    partial: partialReasons.length > 0,
+    partialReasons
+  };
+}
+
+module.exports = {
+  buildEmptyProjectChannelProjection,
+  buildProjectChannelProjection
+};

package/lib/project/root-onboarding-service.js

@@ -3,6 +3,9 @@ const fs = require('fs-extra');
 const WorkspaceStateManager = require('../workspace/multi/workspace-state-manager');
 const SmartOrchestrator = require('../adoption/smart-orchestrator');
 const { applyTakeoverBaseline } = require('../workspace/takeover-baseline');
+const { discoverSemanticSharedSourceDescriptors } = require('../semantic/shared-source-discovery');
+const { buildProjectChannelProjection } = require('./project-channel-projection');
+const { buildProjectChannelOutputFromProjection } = require('./project-channel-output');
 const {
   PROJECT_CANDIDATE_REASON_CODES,
   inspectProjectCandidate
@@ -52,6 +55,19 @@ function buildPublication(preview = {}, options = {}) {
   };
 }
 
+function buildSemanticSharedSourceDiscoverySummary(discovery = {}) {
+  const summary = discovery && typeof discovery.summary === 'object'
+    ? discovery.summary
+    : {};
+  return {
+    totalDescriptors: Number.isFinite(summary.total) ? summary.total : 0,
+    approvedDescriptors: Number.isFinite(summary.approved) ? summary.approved : 0,
+    blockedDescriptors: Number.isFinite(summary.blocked) ? summary.blocked : 0,
+    items: Array.isArray(discovery.items) ? discovery.items : [],
+    blocked: Array.isArray(discovery.blocked) ? discovery.blocked : []
+  };
+}
+
 function buildWorkspaceNameCandidate(rootDir) {
   const base = path.basename(rootDir).trim().toLowerCase();
   const normalized = base.replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
@@ -129,29 +145,43 @@ async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
   const steps = [];
 
   if (rootInspection.kind === 'invalid') {
+    const blockedReasonCode = rootInspection.reasonCodes.includes(PROJECT_CANDIDATE_REASON_CODES.EPHEMERAL_ROOT)
+      ? PROJECT_CANDIDATE_REASON_CODES.EPHEMERAL_ROOT
+      : PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE;
+    const attachDetail = rootInspection.reasonCodes.includes(PROJECT_CANDIDATE_REASON_CODES.EPHEMERAL_ROOT)
+      ? 'Local root is reserved for ephemeral probe/import flow use and cannot become a managed project.'
+      : 'Local root is not accessible as a project directory.';
+    const publishDetail = rootInspection.reasonCodes.includes(PROJECT_CANDIDATE_REASON_CODES.EPHEMERAL_ROOT)
+      ? 'Canonical portfolio publication is blocked for ephemeral probe roots.'
+      : 'Canonical portfolio publication is blocked until the root is valid.';
+    const failureDetail = rootInspection.reasonCodes.includes(PROJECT_CANDIDATE_REASON_CODES.EPHEMERAL_ROOT)
+      ? 'Root inspection reported an ephemeral probe root that must not be imported.'
+      : 'Root inspection reported an invalid candidate state.';
     steps.push(buildStep(
       'register',
       'failed',
       'Root directory cannot be onboarded.',
-      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+      blockedReasonCode
     ));
     steps.push(buildStep(
       'attach',
       'failed',
-      'Local root is not accessible as a project directory.',
-      PROJECT_CANDIDATE_REASON_CODES.ROOT_INACCESSIBLE
+      attachDetail,
+      rootInspection.reasonCodes.includes(PROJECT_CANDIDATE_REASON_CODES.EPHEMERAL_ROOT)
+        ? PROJECT_CANDIDATE_REASON_CODES.EPHEMERAL_ROOT
+        : PROJECT_CANDIDATE_REASON_CODES.ROOT_INACCESSIBLE
     ));
     steps.push(buildStep(
       'hydrate',
       'failed',
       'Onboarding cannot continue until the root is valid.',
-      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+      blockedReasonCode
     ));
     steps.push(buildStep(
       'publish',
       'skipped',
-      'Canonical portfolio publication is blocked until the root is valid.',
-      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+      publishDetail,
+      blockedReasonCode
     ));
     steps.push(buildStep(
       'activate',
@@ -168,8 +198,8 @@ async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
     return buildFailureEnvelope(
       rootInspection,
       steps,
-      'Root inspection reported an invalid candidate state.',
-      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+      failureDetail,
+      blockedReasonCode
     );
   }
 
@@ -358,6 +388,17 @@ async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
       : PROJECT_ONBOARDING_REASON_CODES.SCAFFOLD_REUSED
   ));
 
+  const semanticSharedSourceDiscovery = buildSemanticSharedSourceDiscoverySummary(
+    await discoverSemanticSharedSourceDescriptors(rootInspection.rootDir, {
+      fileSystem
+    })
+  );
+  const projectChannelProjection = await buildProjectChannelProjection(rootInspection.rootDir, {
+    preferredProjectIds: [onboardingPreview.projectId, onboardingPreview.workspaceId]
+  }, {
+    fileSystem
+  });
+
   return {
     mode: 'import',
     generated_at: publishedAt,
@@ -369,6 +410,17 @@ async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
       visibleInPortfolio: true,
       publishedAt
     }),
+    semanticSharedSourceDiscovery,
+    projectChannelContext: {
+      ...projectChannelProjection.summary
+    },
+    ...(projectChannelProjection.resolvedChannel
+      ? {
+          projectChannel: buildProjectChannelOutputFromProjection(projectChannelProjection, {
+            canonicalProjectId: onboardingPreview.projectId || null
+          })
+        }
+      : {}),
     steps,
     result: {
       rootDir: onboardingPreview.rootDir,

package/lib/project/semantic-shared-source-projection.js

@@ -0,0 +1,150 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { listSemanticSharedSources } = require('../semantic/shared-source-config');
+const { discoverSemanticSharedSourceDescriptors } = require('../semantic/shared-source-discovery');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function buildSourceKey(name = '', bundle = '') {
+  const normalizedName = normalizeString(name) || 'semantic-shared';
+  const normalizedBundle = normalizeString(bundle);
+  return `${normalizedName}::${normalizedBundle}`;
+}
+
+function buildConfiguredSourceIndexes(items = []) {
+  const byKey = new Set();
+  const byName = new Set();
+  for (const item of items) {
+    const name = normalizeString(item && item.name) || 'semantic-shared';
+    const bundle = normalizeString(item && item.bundle);
+    byName.add(name);
+    if (bundle) {
+      byKey.add(buildSourceKey(name, bundle));
+    }
+  }
+  return {
+    byKey,
+    byName
+  };
+}
+
+function isDescriptorConnected(item = {}, configuredIndexes = {}) {
+  if (!item.approved) {
+    return false;
+  }
+  const name = normalizeString(item.source_name) || 'semantic-shared';
+  const bundle = normalizeString(item.bundle);
+  if (bundle && configuredIndexes.byKey instanceof Set && configuredIndexes.byKey.has(buildSourceKey(name, bundle))) {
+    return true;
+  }
+  return !bundle
+    && configuredIndexes.byName instanceof Set
+    && configuredIndexes.byName.has(name);
+}
+
+function buildEmptySummary() {
+  return {
+    totalDescriptors: 0,
+    approvedDescriptors: 0,
+    blockedDescriptors: 0,
+    configuredSources: 0,
+    connectedApprovedDescriptors: 0,
+    pendingApprovedDescriptors: 0,
+    hasApprovedDescriptors: false,
+    hasPendingApprovedDescriptors: false
+  };
+}
+
+async function readDescriptorUpdatedAt(projectRoot, descriptorFile, fileSystem = fs) {
+  const normalizedDescriptorFile = normalizeString(descriptorFile);
+  if (!normalizedDescriptorFile) {
+    return null;
+  }
+  const absolutePath = path.join(projectRoot, normalizedDescriptorFile);
+  try {
+    const stats = await fileSystem.stat(absolutePath);
+    if (stats && stats.mtime instanceof Date && Number.isFinite(stats.mtime.getTime())) {
+      return stats.mtime.toISOString();
+    }
+  } catch (_error) {
+    return null;
+  }
+  return null;
+}
+
+async function buildSemanticSharedSourceProjection(projectRoot, dependencies = {}) {
+  const fileSystem = dependencies.fileSystem || fs;
+  const partialReasons = [];
+  let discovery = {
+    summary: {
+      total: 0,
+      approved: 0,
+      blocked: 0
+    },
+    items: [],
+    blocked: []
+  };
+  let configuredSources = {
+    total: 0,
+    items: []
+  };
+
+  try {
+    discovery = await discoverSemanticSharedSourceDescriptors(projectRoot, {
+      fileSystem
+    });
+  } catch (_error) {
+    partialReasons.push('semantic_shared_source_discovery_unavailable');
+  }
+
+  try {
+    configuredSources = await listSemanticSharedSources({}, {
+      projectPath: projectRoot,
+      fileSystem
+    });
+  } catch (_error) {
+    partialReasons.push('semantic_shared_source_config_unavailable');
+  }
+
+  const configuredItems = Array.isArray(configuredSources.items) ? configuredSources.items : [];
+  const configuredIndexes = buildConfiguredSourceIndexes(configuredItems);
+  const sourceItems = Array.isArray(discovery.items) ? discovery.items : [];
+  const items = [];
+  for (const item of sourceItems) {
+    items.push({
+      ...item,
+      connected: isDescriptorConnected(item, configuredIndexes),
+      updated_at: await readDescriptorUpdatedAt(projectRoot, item.descriptor_file, fileSystem)
+    });
+  }
+  const approvedItems = items.filter((item) => item.approved);
+  const connectedApprovedItems = approvedItems.filter((item) => item.connected);
+  const pendingApprovedItems = approvedItems.filter((item) => !item.connected);
+
+  return {
+    summary: {
+      totalDescriptors: items.length,
+      approvedDescriptors: approvedItems.length,
+      blockedDescriptors: Array.isArray(discovery.blocked) ? discovery.blocked.length : 0,
+      configuredSources: configuredItems.length,
+      connectedApprovedDescriptors: connectedApprovedItems.length,
+      pendingApprovedDescriptors: pendingApprovedItems.length,
+      hasApprovedDescriptors: approvedItems.length > 0,
+      hasPendingApprovedDescriptors: pendingApprovedItems.length > 0
+    },
+    items,
+    blocked: Array.isArray(discovery.blocked) ? discovery.blocked : [],
+    partial: partialReasons.length > 0,
+    partialReasons
+  };
+}
+
+module.exports = {
+  buildEmptySummary,
+  buildSemanticSharedSourceProjection
+};