pi-fff-non-ascii-guard

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

See the Roadmap for the maintenance direction and planned work.

What this is

A Pi extension that detects and renames non-ASCII filenames before fff-core can panic on UTF-8 byte boundaries. It scans your workspace on session start, warns about problematic filenames, and provides a tool to safely rename them to ASCII slugs.

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:

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

This extension prevents the known crash by keeping scanned filenames ASCII-safe.

Features

• Session-start scan — automatically detects non-ASCII paths when a Pi session begins
• fff tool gate — blocks known tools (grep, find_files, and fff_multi_grep) and conservatively guards unknown fff_* tools while non-ASCII paths remain (prevents fff-core panic)
• Warning notification — alerts the LLM when problematic paths are found
• list_non_ascii_paths tool — list files and directories with non-ASCII path segments
• sanitize_filenames tool — preview or execute safe ASCII slug renames for files
• Smart exclusions — skips .git, .obsidian, .pi, .claude, .scratch, and node_modules
• Collision disambiguation — when two files slug to the same name, appends -2, -3, … and continues

Install

For the published npm package (recommended):

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

For project-local install:

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

To install the latest source from GitHub instead:

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

Quick start

1. Install the extension (see Install).
2. Start a Pi session in a workspace that may contain non-ASCII filenames.
3. If non-ASCII filenames are detected, Pi shows a warning with the file list.
4. Ask the LLM to call sanitize_filenames with dryRun: true to preview, then dryRun: false to execute.
5. After paths are ASCII-safe, known fff tools and unknown fff_* tools work again.

While non-ASCII paths exist, Pi blocks known fff search tools and unknown fff_* tools, returning a fix hint instead of crashing. The prefix guard is intentionally conservative so newly added fff tools cannot bypass the protection.

Usage summary

list_non_ascii_paths tool

Lists every file and directory whose relative path contains non-ASCII characters. No parameters.

sanitize_filenames tool

Preview renames:

{ "dryRun": true }

Execute renames:

{ "dryRun": false }

Dry-run output is a stable report of each relative source path and its proposed destination path:

Dry run -- 2 file(s) to rename:
  scripts/SpreadsheetToJson_wrapあり・nullなし.gs -> scripts/spreadsheettojson_wrap-null.gs
  scripts/SpreadsheetToJson_wrapなし・nullあり.gs -> scripts/spreadsheettojson_wrap-null-2.gs

No filesystem changes made.

Conflict preview (auto-suffixed -2, -3, ... when needed):
  [slug collision] scripts/spreadsheettojson_wrap-null.gs <- scripts/SpreadsheetToJson_wrapあり・nullなし.gs, scripts/SpreadsheetToJson_wrapなし・nullあり.gs; planned: scripts/spreadsheettojson_wrap-null.gs, scripts/spreadsheettojson_wrap-null-2.gs

If two files would collide after slug conversion, or if the first-choice destination already exists on disk, the conflict preview flags the risk before you run apply mode. The current behavior is to auto-suffix planned destinations (-2, -3, …) so the batch can proceed without manual renaming. Future collision-policy work may tune those suffix rules; for now, treat the preview as the source of truth and manually rename files first if the proposed suffixes are not what you want.

Apply mode returns a list of completed renames and any errors.

Package contents

The npm package contains the files below; development tooling such as tests/, scripts/, and docs/ remains in the repository but is not included in the published tarball.

pi-fff-non-ascii-guard/
├── CHANGELOG.md
├── LICENSE
├── README.md
├── ROADMAP.md
├── SECURITY.md
├── extensions/
│   └── pi-fff-non-ascii-guard.ts
├── lib/
│   ├── ascii-slug.ts
│   ├── block-warning.ts
│   ├── constants.ts
│   ├── non-ascii-scan.ts
│   ├── rename-plan.ts
│   └── scan-cache.ts
└── package.json

Development

Clone and validate:

git clone https://github.com/eiei114/pi-fff-non-ascii-guard.git
cd pi-fff-non-ascii-guard
npm run typecheck   # type-check all TypeScript sources
npm test            # smoke tests
npm run check       # typecheck + tests + actual Pi smoke + npm pack --dry-run
BASE_REF=origin/main npm run version:check  # PR-only semver/CHANGELOG guard
npm run smoke:pi    # actual pinned Pi host and native-shell compatibility checks
node scripts/bench-scan.mjs              # compare scan performance on local fixtures

Release

Planned maintenance work is tracked in ROADMAP.md. Merging a version bump does not create tags or GitHub releases, publish to npm, or dispatch a publication workflow. Releases are an explicit authorized action.

Publication requires all of the following, independently:

1. workflow_dispatch only. auto-release.yml has no push or release trigger, so a merge runs CI only.
2. The protected release environment. The job declares environment: release, whose deployment branch policy allows only main. The environment can additionally require reviewer approval before the job starts.
3. release_authorized: true. The dispatch input is required and defaults to false.

A github.ref condition inside branch-editable workflow code is not a security boundary on its own; the environment is what makes the privileged steps unreachable from an ordinary branch. tests/release-hold.test.mjs enforces this shape and fails if any one of the three barriers is removed.

To release:

gh workflow run auto-release.yml --ref main -f release_authorized=true

Security

See SECURITY.md for vulnerability reporting.

• No network requests.
• No environment variables or secrets read.
• Only renames files within the current Pi workspace directory.
• Skips hidden and internal directories (.git, .obsidian, .pi, .claude, .scratch, node_modules).

Real incidents

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

Another crash while editing AGENTS.md in a Roblox repo with Google Apps Script files:

thread '<unnamed>' panicked at crates\fff-core\src\constraints.rs:73:13:
byte index 44 is not a char boundary; it is inside 'な' (bytes 43..46) of
`scripts\SpreadsheetToJson_wrapあり・nullなし.gs`

The fff tool gate blocks grep, find_files, and fff_multi_grep until those paths are renamed.

Observed error:

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`

Both offending 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

Links

• Repository: https://github.com/eiei114/pi-fff-non-ascii-guard
• npm: https://www.npmjs.com/package/pi-fff-non-ascii-guard
• Issues: https://github.com/eiei114/pi-fff-non-ascii-guard/issues

License

MIT © Keisu