Implement file management operations and add a demo for them

These are the basic ones for now. `diff`/`patch` will be handled similarly to the `match` mode I think.

demo/file-management/.gitignore

@@ -0,0 +1,2 @@
+file-name-external.txt
+file-name-internal.txt

demo/file-management/readme.md

@@ -0,0 +1,70 @@
+# File management
+
+## Create, replace
+
+This creates a new file with the below content:
+
+`file-name-external.txt`:
+
+```
+Hello, world! (External)
+```
+
+It can be shortened by specifying the file name inline with the `..` prefix:
+
+```txt ..file-name-internal.txt
+Hello, world! (Internal)
+```
+
+## Append
+
+Use the `!` sigil to signify the content code block is to be added to the file
+and not replace it altogether:
+
+`file-name-external.txt`:
+
+```txt !
+Hello, world! (External again)
+```
+
+This can be shortened as well by specifying the file name inline but using the
+`!!` prefix instead of the `..` one for creation.
+
+```txt !!file-name-internal.txt
+Hello, world! (Internal again)
+```
+
+## Check
+
+When needing to highligt a file in its entirety, the match sigil can be used.
+It will compare the file's contents on the disk with the code block content and
+will error if they do not match.
+
+`file-name-external.txt`:
+
+```txt ??
+Hello, world! (External)
+
+Hello, world! (External again)
+
+```
+
+```txt ??file-name-internal.txt
+Hello, world! (Internal)
+
+Hello, world! (Internal again)
+
+```
+
+The prefix to use here is `??`.
+
+## Move, delete
+
+Deleting and moving files is relegated to the shell handler, e.g.:
+
+~~~
+```sh
+mv file-name.ext file-name-moved.ext
+rm file-name-moved.ext
+```
+~~~

processBlocks.ts

@@ -40,15 +40,24 @@ export default async function processBlocks(blocks: Block[]) {
       continue;
     }
 
+    // Bypass the handlers if the block mode is 'match' and just check the text
+    if (block.path && block.mode === 'match') {
+      const file = Bun.file(block.path);
+      const text = await file.text();
+      if (block.code !== text) {
+        console.error(`'${block.path} does not match the expected content`);
+      }
+
+      continue;
+    }
+
     try {
       // See https://github.com/oven-sh/bun/issues/14874 for a better option
       const originalConsoleLog = console.log;
       const originalConsoleError = console.error;
 
       if (block.path) {
-        // TODO: Add `{ flags: 'a' }` if this should be an append operation as
-        // determined by nascent code block flags for file handling
-        const file = fs.createWriteStream(block.path);
+        const file = fs.createWriteStream(block.path, { flags: block.mode === 'append' ? 'a' : undefined });
         console.log = (...args: any[]) => file.write(args.join(' ') + '\n');
         console.error = (...args: any[]) => file.write(args.join(' ') + '\n');
       }
@@ -58,7 +67,7 @@ export default async function processBlocks(blocks: Block[]) {
       }
       else {
         if (block.meta) {
-          console.error(`Warning: ${tag} language tag handler does not support block meta`);
+          console.error(`'${tag}' language tag handler does not support block meta`);
         }
 
         await handlerWithoutMeta(block.code);

readme.md

@@ -160,10 +160,12 @@ It is a worthwhile trade-off for now, but should be improved down the line.
 One option to solve this would be to require the paths to start with a period
 like in ESM path module specifiers, but I don't like that option too much.
 
-### Respect the file management sigils on `Block` (`append` and `match`)
+### Add unit tests for the demo files
 
-We're parsing these now but we have yet to start honoring them in the file
-management handling code.
+Create a wrapper to catch `console.log` and `console.error` calls like I already
+do in `processBlocks` and compare the expected output with the real output.
+
+In file management demos, also check the files on disk and clean up after.
 
 ### Consider how to implement the `patch` and `diff` language tags