Add edit plan inbox pickup

docs/cinematic-video-editing-service-plan.md

@@ -794,7 +794,7 @@ It writes the script only and requires an imported audio file.
 11. [x] Add storyboard prompt generation from `analysis.json`.
 12. [x] Add local AI director prompt generation with thumbnail/contact-sheet instructions.
 13. [x] Add local director source-folder scheduler.
-14. [ ] Add project `inbox/` plan pickup.
+14. [x] Add project `inbox/` plan pickup.
 15. [ ] Add strict JSON edit plan schema and validation.
 16. [ ] Add `PUT /v1/edit-projects/{projectId}/plan`.
 17. [ ] Add simple segment rendering without transitions.

src/main/java/org/example/videoclips/editing/EditPlanInboxScanner.java

@@ -0,0 +1,149 @@
+package org.example.videoclips.editing;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.example.videoclips.api.dto.EditProjectResponse;
+import org.example.videoclips.config.VideoClippingProperties;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Optional;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.stream.Stream;
+
+@Component
+@ConditionalOnExpression("${video-clipping.editing.enabled:true} and "
+        + "${video-clipping.editing.local-director.enabled:true}")
+public class EditPlanInboxScanner {
+
+    private static final Logger log = LoggerFactory.getLogger(EditPlanInboxScanner.class);
+
+    private final Path projectRoot;
+    private final String expectedPlanFileName;
+    private final boolean autoRender;
+    private final ObjectMapper objectMapper;
+    private final EditProjectStore store;
+    private final EditProjectService projectService;
+    private final Optional<EditRenderer> renderer;
+    private final AtomicBoolean scanning = new AtomicBoolean();
+
+    @Autowired
+    public EditPlanInboxScanner(
+            VideoClippingProperties properties,
+            ObjectMapper objectMapper,
+            EditProjectStore store,
+            EditProjectService projectService,
+            ObjectProvider<EditRenderer> rendererProvider
+    ) {
+        this(properties, objectMapper, store, projectService, rendererProvider.getIfAvailable());
+    }
+
+    EditPlanInboxScanner(
+            VideoClippingProperties properties,
+            ObjectMapper objectMapper,
+            EditProjectStore store,
+            EditProjectService projectService,
+            EditRenderer renderer
+    ) {
+        this.projectRoot = Path.of(properties.getEditing().getProjectDirectory());
+        this.expectedPlanFileName = properties.getEditing().getLocalDirector().getExpectedPlanFileName();
+        this.autoRender = properties.getEditing().getLocalDirector().isAutoRenderWhenPlanAppears();
+        this.objectMapper = objectMapper;
+        this.store = store;
+        this.projectService = projectService;
+        this.renderer = Optional.ofNullable(renderer);
+    }
+
+    @Scheduled(
+            initialDelayString = "${video-clipping.editing.local-director.poll-interval-ms:5000}",
+            fixedDelayString = "${video-clipping.editing.local-director.poll-interval-ms:5000}"
+    )
+    public void scan() {
+        if (!scanning.compareAndSet(false, true)) {
+            return;
+        }
+        try {
+            findNextPlan().ifPresent(this::importPlan);
+        } finally {
+            scanning.set(false);
+        }
+    }
+
+    Optional<Path> findNextPlan() {
+        if (!Files.isDirectory(projectRoot)) {
+            return Optional.empty();
+        }
+        try (Stream<Path> projects = Files.list(projectRoot)) {
+            return projects.filter(Files::isDirectory)
+                    .sorted(Comparator.comparing(path -> path.getFileName().toString()))
+                    .map(path -> path.resolve("inbox").resolve(expectedPlanFileName))
+                    .filter(Files::isRegularFile)
+                    .filter(path -> !Files.exists(path.getParent().getParent().resolve("edit-plan.json")))
+                    .findFirst();
+        } catch (IOException ex) {
+            throw new IllegalStateException("Unable to scan edit project inboxes: " + projectRoot, ex);
+        }
+    }
+
+    private void importPlan(Path inboxPlan) {
+        String projectId = inboxPlan.getParent().getParent().getFileName().toString();
+        log.info("event=edit_plan_inbox_detected project_id={} file={}", projectId, inboxPlan);
+        EditPlan plan;
+        try {
+            plan = objectMapper.readValue(inboxPlan.toFile(), EditPlan.class);
+            validateStructure(projectId, plan);
+        } catch (RuntimeException | IOException ex) {
+            log.warn("event=edit_plan_rejected project_id={} error_type={} message={}",
+                    projectId, ex.getClass().getSimpleName(), ex.getMessage());
+            if (Files.exists(inboxPlan)) {
+                move(inboxPlan, inboxPlan.resolveSibling(expectedPlanFileName + ".rejected"));
+            }
+            return;
+        }
+
+        store.writeJson(projectId, "edit-plan.json", normalized(plan));
+        move(inboxPlan, inboxPlan.resolveSibling(expectedPlanFileName + ".accepted"));
+        EditProjectResponse project = projectService.getProject(projectId);
+        projectService.updateProject(projectId, EditProjectStatus.PLANNED, Path.of(project.inputDirectory()), null);
+        log.info("event=edit_plan_imported project_id={} decision_count={} auto_render={}",
+                projectId, plan.decisions().size(), autoRender);
+        if (autoRender) {
+            renderer.orElseThrow(() -> new IllegalStateException(
+                    "Automatic rendering is enabled but no EditRenderer is available")).render(projectId);
+        }
+    }
+
+    private void validateStructure(String projectId, EditPlan plan) {
+        if (plan.projectId() == null || !projectId.equals(plan.projectId())) {
+            throw new IllegalArgumentException("Edit plan projectId must match its project inbox");
+        }
+        if (plan.style() == null || plan.style().isBlank() || plan.targetDurationSeconds() <= 0
+                || plan.decisions() == null || plan.audioCues() == null || plan.voiceover() == null) {
+            throw new IllegalArgumentException("Edit plan is missing required fields");
+        }
+    }
+
+    private EditPlan normalized(EditPlan plan) {
+        return new EditPlan(plan.projectId(), plan.style(), plan.targetDurationSeconds(),
+                List.copyOf(plan.decisions()), List.copyOf(plan.audioCues()), List.copyOf(plan.voiceover()),
+                plan.renderProfile(), plan.summary());
+    }
+
+    private void move(Path source, Path target) {
+        try {
+            Files.move(source, target, StandardCopyOption.ATOMIC_MOVE);
+        } catch (IOException ex) {
+            throw new IllegalStateException("Unable to archive edit plan inbox file: " + source, ex);
+        }
+    }
+}

src/main/java/org/example/videoclips/editing/EditRenderer.java

@@ -0,0 +1,6 @@
+package org.example.videoclips.editing;
+
+public interface EditRenderer {
+
+    void render(String projectId);
+}

src/test/java/org/example/videoclips/editing/EditPlanInboxScannerTest.java

@@ -0,0 +1,109 @@
+package org.example.videoclips.editing;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.example.videoclips.api.dto.CreateEditProjectRequest;
+import org.example.videoclips.config.VideoClippingProperties;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.time.Clock;
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+class EditPlanInboxScannerTest {
+
+    @TempDir
+    Path tempDir;
+
+    private VideoClippingProperties properties;
+    private ObjectMapper objectMapper;
+    private FileSystemEditProjectStore store;
+    private EditProjectService projectService;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        properties = new VideoClippingProperties();
+        properties.getEditing().setProjectDirectory(tempDir.resolve("projects").toString());
+        objectMapper = new ObjectMapper().findAndRegisterModules();
+        store = new FileSystemEditProjectStore(properties, objectMapper);
+        projectService = new EditProjectService(store,
+                Clock.fixed(Instant.parse("2026-07-10T10:00:00Z"), ZoneOffset.UTC));
+        Path input = Files.createDirectories(tempDir.resolve("input"));
+        projectService.createProject(new CreateEditProjectRequest(
+                "Porsche Edit", input.toString(), 60, "cinematic-porsche-promo", true, true, true));
+    }
+
+    @Test
+    void ignoresTemporaryPlanFiles() throws Exception {
+        Path inbox = store.inboxDirectory("porsche-edit");
+        Files.writeString(inbox.resolve("edit-plan.json.tmp"), "{}");
+        Files.writeString(inbox.resolve("edit-plan.json.part"), "{}");
+        Files.writeString(inbox.resolve("edit-plan.json.download"), "{}");
+
+        EditPlanInboxScanner scanner = scanner(false, null);
+
+        assertThat(scanner.findNextPlan()).isEmpty();
+        scanner.scan();
+        assertThat(store.editPlanFile("porsche-edit")).doesNotExist();
+    }
+
+    @Test
+    void rejectsMalformedOrMismatchedPlanFiles() throws Exception {
+        Path inboxPlan = store.inboxDirectory("porsche-edit").resolve("edit-plan.json");
+        Files.writeString(inboxPlan, "{not-json}");
+
+        scanner(false, null).scan();
+
+        assertThat(inboxPlan).doesNotExist();
+        assertThat(inboxPlan.resolveSibling("edit-plan.json.rejected")).exists();
+        assertThat(store.editPlanFile("porsche-edit")).doesNotExist();
+        assertThat(projectService.getProject("porsche-edit").status()).isEqualTo(EditProjectStatus.CREATED);
+    }
+
+    @Test
+    void acceptsValidPlanOnceWithoutRenderingWhenDisabled() throws Exception {
+        writeValidPlan();
+        EditRenderer renderer = mock(EditRenderer.class);
+        EditPlanInboxScanner scanner = scanner(false, renderer);
+
+        scanner.scan();
+        scanner.scan();
+
+        assertThat(store.editPlanFile("porsche-edit")).exists();
+        assertThat(store.inboxDirectory("porsche-edit").resolve("edit-plan.json.accepted")).exists();
+        assertThat(projectService.getProject("porsche-edit").status()).isEqualTo(EditProjectStatus.PLANNED);
+        verify(renderer, never()).render("porsche-edit");
+    }
+
+    @Test
+    void invokesRendererWhenAutoRenderIsEnabled() throws Exception {
+        writeValidPlan();
+        EditRenderer renderer = mock(EditRenderer.class);
+
+        scanner(true, renderer).scan();
+
+        verify(renderer).render("porsche-edit");
+    }
+
+    private void writeValidPlan() throws Exception {
+        EditPlan plan = new EditPlan("porsche-edit", "cinematic-porsche-promo", 60,
+                List.of(new EditDecision("clip_00001", 0, 2.5, 0, 2.5,
+                        "cut", "cut", 1.0, "cinematic", "opening")),
+                List.of(), List.of(), "mp4-h264-aac-1080p", "Hero edit");
+        objectMapper.writeValue(store.inboxDirectory("porsche-edit").resolve("edit-plan.json").toFile(), plan);
+    }
+
+    private EditPlanInboxScanner scanner(boolean autoRender, EditRenderer renderer) {
+        properties.getEditing().getLocalDirector().setAutoRenderWhenPlanAppears(autoRender);
+        return new EditPlanInboxScanner(properties, objectMapper, store, projectService, renderer);
+    }
+}