pi-fff-non-ascii-guard

Pi extension that detects and renames non-ASCII filenames before fff-core can panic on UTF-8 byte boundaries.

Packages

Package details

extension

Install pi-fff-non-ascii-guard from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:pi-fff-non-ascii-guard

Package: pi-fff-non-ascii-guard
Version: 0.1.1
Published: May 25, 2026
Downloads: not available
Author: eiei114
License: MIT
Types: extension
Size: 10 KB
Dependencies: 0 dependencies · 2 peers

Pi manifest JSON

{
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

# pi-fff-non-ascii-guard

Pi extension that prevents fff-core panics caused by non-ASCII filenames.

Problem

fff-core can panic when it slices UTF-8 paths at byte offsets that are not character boundaries, for example paths containing Japanese characters.

Example:

thread '<unnamed>' panicked at crates\fff-core\src\constraints.rs:73:13:
byte index 65 is not a char boundary

What this extension does

Scans the current Pi workspace on session_start.
Warns when non-ASCII filenames are found.
Registers a sanitize_filenames tool that can preview or execute safe ASCII slug renames.
Skips noisy/internal folders such as .git, .obsidian, .pi, .claude, .scratch, and node_modules.

Install

pi install git:github.com/eiei114/pi-fff-non-ascii-guard

For project-local install:

pi install -l git:github.com/eiei114/pi-fff-non-ascii-guard

Tool

sanitize_filenames

Parameters:

{
  "dryRun": true
}

dryRun: true previews planned renames.
dryRun: false performs renames.

Notes

This does not patch fff-core itself. It prevents the known crash by keeping scanned filenames ASCII-safe.

Real incident that motivated this extension

This extension was created after Pi crashed while updating .pi/monofold.yaml in an Obsidian vault that contained Japanese PDF filenames.

The observed error was:

thread '<unnamed>' panicked at crates\fff-core\src\constraints.rs:73:13:
byte index 65 is not a char boundary; it is inside 'イ' (bytes 63..66) of `2_Literature\2_Tools\Pi Coding Agent - 初心者向け比較ガイド - slides.pdf`
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

A second non-ASCII PDF filename was also present:

2_Literature/PKM/3倍Zettelkasten - AI支援による直列高速化.pdf

Both files were renamed to ASCII slugs:

2_Literature/2_Tools/pi-coding-agent-beginner-guide-slides.pdf
2_Literature/PKM/3x-zettelkasten-ai-serial-acceleration.pdf

The immediate workaround was to rename the files manually. This extension codifies that workaround so future projects get an early warning before fff-core touches paths that may trigger the same UTF-8 boundary panic.