scene-capability-engine 3.6.60 → 3.6.62

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

@@ -0,0 +1,350 @@
+const path = require('path');
+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 {
+  PROJECT_CANDIDATE_REASON_CODES,
+  inspectProjectCandidate
+} = require('./candidate-inspection-service');
+const {
+  buildWorkspaceProjectId
+} = require('./portfolio-projection-service');
+
+const PROJECT_ONBOARDING_REASON_CODES = {
+  MISSING_ROOT: 'project.onboarding.blocked.missing_root',
+  BLOCKED_BY_CANDIDATE: 'project.onboarding.blocked.candidate_state',
+  ROOT_ACCEPTED: 'project.onboarding.root_accepted',
+  IMPORT_NO_ACTIVATE: 'project.onboarding.import_no_activate',
+  REGISTERED: 'project.onboarding.registered',
+  ADOPTED: 'project.onboarding.adopted',
+  SCAFFOLD_REUSED: 'project.onboarding.scaffold_reused',
+  ADOPTION_FAILED: 'project.onboarding.adoption_failed'
+};
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function buildStep(key, status, detail, reasonCode) {
+  return {
+    key,
+    status,
+    ...(reasonCode ? { reasonCode } : {}),
+    ...(detail ? { detail } : {})
+  };
+}
+
+function buildWorkspaceNameCandidate(rootDir) {
+  const base = path.basename(rootDir).trim().toLowerCase();
+  const normalized = base.replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return normalized || 'project';
+}
+
+async function allocateWorkspaceId(rootDir, stateManager) {
+  const base = buildWorkspaceNameCandidate(rootDir);
+  if (!await stateManager.hasWorkspace(base)) {
+    return base;
+  }
+
+  for (let index = 2; index < 1000; index += 1) {
+    const candidate = `${base}-${index}`;
+    if (!await stateManager.hasWorkspace(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(`unable to allocate workspace id for root: ${rootDir}`);
+}
+
+function buildFailureEnvelope(rootInspection, steps, detail, reasonCode) {
+  return {
+    mode: 'import',
+    generated_at: new Date().toISOString(),
+    success: false,
+    preview: rootInspection,
+    summary: rootInspection,
+    steps,
+    error: {
+      reasonCode,
+      detail
+    }
+  };
+}
+
+async function runWithSuppressedConsole(callback, enabled) {
+  if (!enabled) {
+    return callback();
+  }
+
+  const originalLog = console.log;
+  const originalInfo = console.info;
+  const originalWarn = console.warn;
+  console.log = () => {};
+  console.info = () => {};
+  console.warn = () => {};
+  try {
+    return await callback();
+  } finally {
+    console.log = originalLog;
+    console.info = originalInfo;
+    console.warn = originalWarn;
+  }
+}
+
+async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
+  const fileSystem = dependencies.fileSystem || fs;
+  const stateManager = dependencies.stateManager || new WorkspaceStateManager(dependencies.workspaceStatePath);
+  const root = normalizeString(options.root || options.rootDir);
+  if (!root) {
+    throw new Error('--root is required');
+  }
+
+  const rootInspection = await inspectProjectCandidate({ root }, {
+    ...dependencies,
+    fileSystem,
+    stateManager
+  });
+  const steps = [];
+
+  if (rootInspection.kind === 'invalid') {
+    steps.push(buildStep(
+      'register',
+      'failed',
+      'Root directory cannot be onboarded.',
+      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+    ));
+    steps.push(buildStep(
+      'attach',
+      'failed',
+      'Local root is not accessible as a project directory.',
+      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
+    ));
+    steps.push(buildStep(
+      'activate',
+      'skipped',
+      'Import does not activate invalid roots.',
+      PROJECT_ONBOARDING_REASON_CODES.IMPORT_NO_ACTIVATE
+    ));
+    steps.push(buildStep(
+      'scaffold',
+      'skipped',
+      'Scaffold is blocked until the root becomes valid.',
+      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+    ));
+    return buildFailureEnvelope(
+      rootInspection,
+      steps,
+      'Root inspection reported an invalid candidate state.',
+      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+    );
+  }
+
+  if (rootInspection.reasonCodes.includes(PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA)) {
+    steps.push(buildStep(
+      'register',
+      'failed',
+      'Root contains invalid SCE metadata and cannot be imported safely.',
+      PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
+    ));
+    steps.push(buildStep(
+      'attach',
+      'done',
+      'Local root is reachable.',
+      PROJECT_ONBOARDING_REASON_CODES.ROOT_ACCEPTED
+    ));
+    steps.push(buildStep(
+      'hydrate',
+      'failed',
+      'Existing project metadata must be repaired before import.',
+      PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
+    ));
+    steps.push(buildStep(
+      'activate',
+      'skipped',
+      'Import does not activate blocked projects.',
+      PROJECT_ONBOARDING_REASON_CODES.IMPORT_NO_ACTIVATE
+    ));
+    steps.push(buildStep(
+      'scaffold',
+      'skipped',
+      'Scaffold is blocked by invalid project metadata.',
+      PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
+    ));
+    return buildFailureEnvelope(
+      rootInspection,
+      steps,
+      'Existing project metadata is invalid.',
+      PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
+    );
+  }
+
+  let onboardingPreview = { ...rootInspection };
+  let importResult = null;
+  let takeoverBaseline = null;
+
+  if (rootInspection.kind === 'directory-candidate') {
+    const orchestrator = dependencies.smartOrchestrator || new SmartOrchestrator();
+    importResult = await runWithSuppressedConsole(() => orchestrator.orchestrate(rootInspection.rootDir, {
+      dryRun: false,
+      verbose: false,
+      skipBackup: false,
+      skipUpdate: false
+    }), options.json === true);
+
+    if (!importResult.success) {
+      steps.push(buildStep(
+        'register',
+        'failed',
+        'Workspace registration was not attempted because adoption failed.',
+        PROJECT_ONBOARDING_REASON_CODES.ADOPTION_FAILED
+      ));
+      steps.push(buildStep(
+        'attach',
+        'done',
+        'Local root is reachable.',
+        PROJECT_ONBOARDING_REASON_CODES.ROOT_ACCEPTED
+      ));
+      steps.push(buildStep(
+        'hydrate',
+        'failed',
+        (importResult.errors || []).join('; ') || 'Adoption failed.',
+        PROJECT_ONBOARDING_REASON_CODES.ADOPTION_FAILED
+      ));
+      steps.push(buildStep(
+        'activate',
+        'skipped',
+        'Import does not activate failed onboarding results.',
+        PROJECT_ONBOARDING_REASON_CODES.IMPORT_NO_ACTIVATE
+      ));
+      steps.push(buildStep(
+        'scaffold',
+        'failed',
+        'SCE baseline could not be applied to the root directory.',
+        PROJECT_ONBOARDING_REASON_CODES.ADOPTION_FAILED
+      ));
+      return buildFailureEnvelope(
+        rootInspection,
+        steps,
+        (importResult.errors || []).join('; ') || 'Adoption failed.',
+        PROJECT_ONBOARDING_REASON_CODES.ADOPTION_FAILED
+      );
+    }
+
+    const packageJson = require('../../package.json');
+    takeoverBaseline = await applyTakeoverBaseline(rootInspection.rootDir, {
+      apply: true,
+      writeReport: true,
+      sceVersion: packageJson.version
+    });
+    onboardingPreview = await inspectProjectCandidate({ root: rootInspection.rootDir }, {
+      ...dependencies,
+      fileSystem,
+      stateManager
+    });
+  }
+
+  let workspaceId = rootInspection.workspaceId || null;
+  if (!workspaceId) {
+    workspaceId = await allocateWorkspaceId(rootInspection.rootDir, stateManager);
+    await stateManager.createWorkspace(workspaceId, rootInspection.rootDir);
+    onboardingPreview = {
+      ...onboardingPreview,
+      kind: 'workspace-backed',
+      projectId: buildWorkspaceProjectId(workspaceId),
+      workspaceId,
+      readiness: onboardingPreview.kind === 'directory-candidate' ? 'ready' : onboardingPreview.readiness,
+      availability: 'accessible',
+      localCandidate: false,
+      reasonCodes: Array.from(new Set([
+        PROJECT_CANDIDATE_REASON_CODES.WORKSPACE_REGISTERED,
+        ...onboardingPreview.reasonCodes
+      ]))
+    };
+  }
+
+  steps.push(buildStep(
+    'register',
+    'done',
+    rootInspection.workspaceId
+      ? 'Workspace was already registered.'
+      : `Workspace registered as ${workspaceId}.`,
+    rootInspection.workspaceId
+      ? PROJECT_CANDIDATE_REASON_CODES.WORKSPACE_REGISTERED
+      : PROJECT_ONBOARDING_REASON_CODES.REGISTERED
+  ));
+  steps.push(buildStep(
+    'attach',
+    'done',
+    'Local root is accepted as the canonical onboarding source.',
+    PROJECT_ONBOARDING_REASON_CODES.ROOT_ACCEPTED
+  ));
+  steps.push(buildStep(
+    'hydrate',
+    'done',
+    rootInspection.kind === 'directory-candidate'
+      ? 'SCE baseline and project hydration were applied to the root directory.'
+      : 'Existing SCE project root is ready for portfolio import.',
+    rootInspection.kind === 'directory-candidate'
+      ? PROJECT_ONBOARDING_REASON_CODES.ADOPTED
+      : PROJECT_CANDIDATE_REASON_CODES.SCE_PRESENT
+  ));
+  steps.push(buildStep(
+    'activate',
+    'skipped',
+    'Import keeps active workspace selection unchanged in phase-1.',
+    PROJECT_ONBOARDING_REASON_CODES.IMPORT_NO_ACTIVATE
+  ));
+  steps.push(buildStep(
+    'scaffold',
+    rootInspection.kind === 'directory-candidate' ? 'done' : 'skipped',
+    rootInspection.kind === 'directory-candidate'
+      ? 'Applied SCE baseline files to the project root.'
+      : 'Existing SCE baseline is reused; no scaffold rewrite was required.',
+    rootInspection.kind === 'directory-candidate'
+      ? PROJECT_ONBOARDING_REASON_CODES.ADOPTED
+      : PROJECT_ONBOARDING_REASON_CODES.SCAFFOLD_REUSED
+  ));
+
+  return {
+    mode: 'import',
+    generated_at: new Date().toISOString(),
+    success: true,
+    preview: onboardingPreview,
+    summary: onboardingPreview,
+    steps,
+    result: {
+      rootDir: onboardingPreview.rootDir,
+      projectId: onboardingPreview.projectId || null,
+      workspaceId: onboardingPreview.workspaceId || null,
+      ...(importResult ? {
+        adoption: {
+          mode: importResult.mode || null,
+          backupId: importResult.backup ? importResult.backup.id : null,
+          changes: importResult.changes || { created: [], updated: [], deleted: [], preserved: [] },
+          warnings: importResult.warnings || []
+        }
+      } : {}),
+      ...(takeoverBaseline ? {
+        takeoverBaseline: {
+          reportFile: takeoverBaseline.report_file || null,
+          summary: takeoverBaseline.summary || {}
+        }
+      } : {})
+    }
+  };
+}
+
+module.exports = {
+  PROJECT_ONBOARDING_REASON_CODES,
+  runProjectRootOnboardingImport
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.6.60",
+  "version": "3.6.62",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {

package/scripts/magicball-project-contract-audit.js

@@ -8,19 +8,21 @@ const REQUIRED_CHECKS = [
   {
     path: 'README.md',
     requiredSnippets: [
-      '`sce project portfolio show|target resolve|supervision show`'
+      '`sce project portfolio show|candidate inspect|onboarding import|target resolve|supervision show`'
     ]
   },
   {
     path: 'README.zh.md',
     requiredSnippets: [
-      '`sce project portfolio show|target resolve|supervision show`'
+      '`sce project portfolio show|candidate inspect|onboarding import|target resolve|supervision show`'
     ]
   },
   {
     path: 'docs/command-reference.md',
     requiredSnippets: [
       'sce project portfolio show [options]',
+      'sce project candidate inspect --root <path> [options]',
+      'sce project onboarding import --root <path> [options]',
       'sce project target resolve [options]',
       'sce project supervision show --project <id> [options]'
     ]
@@ -45,6 +47,8 @@ const REQUIRED_CHECKS = [
     path: 'docs/magicball-project-portfolio-contract.md',
     requiredSnippets: [
       'sce project portfolio show --json',
+      'sce project candidate inspect --root <path> --json',
+      'sce project onboarding import --root <path> --json',
       'sce project target resolve --json',
       'sce project supervision show --project <project-id> --json'
     ]
@@ -53,7 +57,11 @@ const REQUIRED_CHECKS = [
     path: 'docs/magicball-frontend-state-and-command-mapping.md',
     requiredSnippets: [
       'projectPortfolio: Record<string, unknown> | null',
+      'projectCandidate: Record<string, unknown> | null',
+      'projectOnboarding: Record<string, unknown> | null',
       '`sce project portfolio show --json`',
+      '`sce project candidate inspect --root <path> --json`',
+      '`sce project onboarding import --root <path> --json`',
       '`sce project target resolve --request <text> --current-project <project-id> --json`',
       '`sce project supervision show --project <project-id> --json`'
     ]
@@ -62,6 +70,8 @@ const REQUIRED_CHECKS = [
     path: 'docs/magicball-cli-invocation-examples.md',
     requiredSnippets: [
       'sce project portfolio show --json',
+      'sce project candidate inspect --root "C:/workspace/customer-order-demo" --json',
+      'sce project onboarding import --root "C:/workspace/customer-order-demo" --json',
       'sce project target resolve --request "continue customer-order-demo" --json',
       'sce project supervision show --project workspace:customer-order-demo --json'
     ]
@@ -71,6 +81,8 @@ const REQUIRED_CHECKS = [
     requiredSnippets: [
       '## Phase 0: Multi-project Workspace Shell',
       'sce project portfolio show --json',
+      'sce project candidate inspect --root "<path>" --json',
+      'sce project onboarding import --root "<path>" --json',
       'sce project target resolve --request "<text>" --current-project <project-id> --json',
       'sce project supervision show --project <project-id> --json'
     ]
@@ -80,14 +92,15 @@ const REQUIRED_CHECKS = [
     requiredSnippets: [
       '- `docs/magicball-project-portfolio-contract.md`',
       '- project switcher from `project portfolio show`',
+      '- local-root candidate receipt from `project candidate inspect`',
       '- project health summary from `project supervision show`'
     ]
   },
   {
     path: 'docs/magicball-integration-issue-tracker.md',
     requiredSnippets: [
-      '- `project portfolio show/target resolve/supervision show`',
-      '5. treat `project portfolio / target resolve / supervision` as the default multi-project shell truth'
+      '- `project portfolio show/candidate inspect/onboarding import/target resolve/supervision show`',
+      '5. treat `project portfolio / candidate inspect / onboarding import / target resolve / supervision` as the default multi-project shell truth'
     ]
   },
   {

package/template/.sce/README.md

@@ -243,6 +243,6 @@ A Spec is a complete feature definition with three parts:
 ---
 
 **Project Type**: Spec-driven development  
-**sce Version**: 3.6.60  
-**Last Updated**: 2026-03-19  
+**sce Version**: 3.6.62  
+**Last Updated**: 2026-03-21
 **Purpose**: Guide AI tools to work effectively with this project