Refine archive create/import TUI

[Moskize91]

Summary

• make wikigraph create create an empty .wikg archive and move EPUB ingestion to create --import
• remove obsolete create/chapter source input-format paths from TUI parsing and help docs
• tighten Agent-facing contracts for --json, inspect recommendations, source range bounds, and implicit query help routes

Verification

• pnpm run lint:fix
• pnpm test
• pnpm verify
• manual smoke tests for create/import, chapter add --json, source range bounds, and --query --reverse error routing

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 13890586-74be-4043-a00a-c85a5da92fa8

📥 Commits

Reviewing files that changed from the base of the PR and between c55e5a3 and 973f913.

📒 Files selected for processing (4)

• data/help/commands/maintenance/chapter/add.jinja
• data/help/commands/maintenance/chapter/set-source.jinja
• src/cli/args.ts
• test/cli/args.test.ts

✅ Files skipped from review due to trivial changes (2)

• data/help/commands/maintenance/chapter/set-source.jinja
• data/help/commands/maintenance/chapter/add.jinja

🚧 Files skipped from review as they are similar to previous changes (2)

• test/cli/args.test.ts
• src/cli/args.ts

---

Summary by CodeRabbit

• New Features
  • Added --import <epub-path> support for wikigraph <archive-uri> create (archive-first: creates empty by default, or imports EPUB when provided).
  • Chapter modification actions now support --json for machine-readable output.
• Bug Fixes
  • Improved validation for source sentence ranges with clearer out-of-bounds errors.
• Documentation
  • Refreshed CLI help and examples for archive creation and chapter source commands, removing --input-format usage and updating guidance across relevant help topics.

Walkthrough

This PR replaces archive creation input handling with --import <epub-path>, removes --input-format from chapter source-setting paths, and adds JSON output for chapter CLI actions. It also tightens readTextStreamRange bounds checks and updates help text plus tests to match the new archive-first command flow.

Possibly related PRs

• oomol-lab/wiki-graph#98: Also updates chapter-related CLI help content to match newer URI-first command shapes.

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title is related to the change, but it does not follow the required <type>(<scope>): <subject> format.	Use a conventional title like refactor(cli): refine archive create/import TUI.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description matches the PR by summarizing the create/import refactor, help-doc updates, and contract tightening.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch codex/refine-create-import-tui

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/cli/archive.ts (1)

464-501: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Temp directory leaked if DirectoryDocument.open throws.

In createEmptyArchive, DirectoryDocument.open(directoryPath) runs before the try/finally that removes directoryPath. If open throws (e.g. disk/permission failure), the temp dir created by createWikiGraphTempDirectory is never cleaned up.

🐛 Proposed fix

 async function createEmptyArchive(outputPath: string): Promise<void> {
   const directoryPath = await createWikiGraphTempDirectory("archive-write");
-  const document = await DirectoryDocument.open(directoryPath);
 
   try {
+    const document = await DirectoryDocument.open(directoryPath);
     try {
       await document.openSession(async (openedDocument) => {
         await openedDocument.writeToc({
           items: [],
           version: TOC_FILE_VERSION,
         });
       });
     } finally {
       await document.release();
     }
     await writeWikgArchive(directoryPath, outputPath);
   } finally {
     await rm(directoryPath, { force: true, recursive: true });
   }
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli/archive.ts` around lines 464 - 501, The temp directory cleanup in
createEmptyArchive is only protected after DirectoryDocument.open, so a failure
there can leak the directory created by createWikiGraphTempDirectory. Move the
DirectoryDocument.open handling inside the existing cleanup try/finally (or add
an outer finally around it) so directoryPath is always removed, and make sure
document.release is still called only when open succeeds.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@data/help/commands/maintenance/chapter/add.jinja`:
- Around line 10-11: The dedicated chapter add command usage text is missing the
newly supported --json flag. Update the add usage strings in the chapter add
template to include --json alongside the existing options for both stage
variants, matching the generic add block behavior already reflected in
predicate.jinja and the command’s JSON output support.

In `@data/help/commands/maintenance/chapter/set-source.jinja`:
- Line 8: The usage line for the set-source command is missing the supported
--json flag, so update the set-source usage text in the command template to
include --json alongside the existing options. Make the change in the set-source
help/usage definition so the documented syntax matches the command behavior and
returns JSON is clearly advertised.

In `@src/cli/args.ts`:
- Around line 3034-3056: The create command in args.ts is still silently
accepting unsupported read-only flags like --query and --reverse by omitting
them from the returned args. Add explicit rejection for those flags alongside
the existing rejectArchiveFlag/rejectArchiveBooleanFlag checks in the create
argument parsing path, so invalid invocations fail with a help-linked error
instead of being accepted and dropped.

---

Outside diff comments:
In `@src/cli/archive.ts`:
- Around line 464-501: The temp directory cleanup in createEmptyArchive is only
protected after DirectoryDocument.open, so a failure there can leak the
directory created by createWikiGraphTempDirectory. Move the
DirectoryDocument.open handling inside the existing cleanup try/finally (or add
an outer finally around it) so directoryPath is always removed, and make sure
document.release is still called only when open succeeds.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dcaf47f1-9ba4-496a-8e3c-ca7120220bc9

📥 Commits

Reviewing files that changed from the base of the PR and between a77e725 and c55e5a3.

📒 Files selected for processing (17)

• data/help/commands/maintenance/chapter.jinja
• data/help/commands/maintenance/chapter/add.jinja
• data/help/commands/maintenance/chapter/set-source.jinja
• data/help/commands/predicate.jinja
• data/help/commands/transform.jinja
• data/help/topics/format.jinja
• data/help/topics/recipe.jinja
• data/help/topics/runtime.jinja
• data/help/topics/uri.jinja
• src/archive/query/archive-view.ts
• src/cli/archive-chapter.ts
• src/cli/archive.ts
• src/cli/args.ts
• test/archive/query/archive-view.test.ts
• test/cli/archive-chapter.test.ts
• test/cli/archive.test.ts
• test/cli/args.test.ts