Write File Special Characters Workaround (with TypeScript Verification)

Problem

The write_file tool may fail with [ERROR] unknown error when file content contains special characters such as:

• Apostrophes / single quotes (')
• Backticks (`)
• Template literals (`${variable}`) common in TypeScript/JavaScript
• Complex combinations of quotes and escape sequences

This is especially common when writing TypeScript, JavaScript, shell scripts, or any source file with string interpolation syntax.

Additionally, after writing TypeScript files, you need to verify they are type-correct — but common methods like npx tsc or ./node_modules/.bin/tsc can fail with [ERROR] unknown error due to timeout or symlink resolution issues. The reliable method is to call the TypeScript binary directly.

Solution: Python Heredoc Workaround + Direct TSC Verification

Phase 1: Write Files via Python Heredoc

Write a small Python script to /tmp/ that uses triple-quoted strings to embed the file content, then execute it with python3.

Step-by-Step

1. Compose a Python writer script using triple-quoted strings ("""...""").
2. Write the Python script itself to /tmp/ — its content is plain enough that write_file will succeed (no problematic characters in the wrapper).
3. Execute the script with run_shell: python3 /tmp/write_<name>.py

Escaping Rules Inside the Python Script

Character	How to handle
Backslash \	Escape as \\
Triple double-quote """	Escape as \"\"\" or use ''' strings instead
Everything else (backticks, $, ', {})	No escaping needed

Template

#!/usr/bin/env python3
content = """
<YOUR FILE CONTENT HERE>
""".lstrip("\n")

with open("/path/to/target/file.ts", "w") as f:
    f.write(content)

print("File written successfully.")

Concrete Example

Suppose you need to write a TypeScript file with template literals and apostrophes that causes write_file to fail:

Step 1 — Write the Python helper to /tmp/:

Use write_file with path /tmp/write_greeting.py and content:

#!/usr/bin/env python3
content = """
export function greet(name: string): string {
  const msg = `Hello, ${name}! It's a great day.`;
  console.log(`Greeting: ${msg}`);
  return msg;
}
""".lstrip("\n")

with open("/app/src/greeting.ts", "w") as f:
    f.write(content)

print("Written: /app/src/greeting.ts")

Step 2 — Execute the helper:

python3 /tmp/write_greeting.py

Step 3 — Verify the file was created:

cat /app/src/greeting.ts

Phase 2: TypeScript Type-Checking (Reliable Method)

After writing TypeScript files, always verify they introduce zero new type errors. Use the direct binary path — not npx or .bin symlinks, which are prone to timeout and path-resolution failures.

The Reliable TSC Command

node node_modules/typescript/bin/tsc --noEmit 2>&1 | grep "src/greeting.ts"

Key points:

• node node_modules/typescript/bin/tsc — invokes TypeScript directly via node, bypassing npx overhead and symlink resolution entirely.
• --noEmit — type-checks only; does not write output files.
• 2>&1 — merges stderr into stdout so grep can filter everything.
• | grep "<filename>" — filters output to only lines mentioning your newly-written file(s), so pre-existing errors in other files do not create false alarms.

Why Not npx or .bin Symlinks?

Method	Risk
npx tsc --noEmit	Frequently returns [ERROR] unknown error (timeout, network, PATH issues)
./node_modules/.bin/tsc --noEmit	Symlink resolution can fail in some environments
node node_modules/typescript/bin/tsc --noEmit	Reliable — direct JS execution, no symlinks, no network

Filtering for Multiple New Files

When you've written several files, pipe through a more specific grep pattern:

node node_modules/typescript/bin/tsc --noEmit 2>&1 | grep -E "src/(greeting|utils|component)\.ts"

Or use a directory prefix to catch all new files in one folder:

node node_modules/typescript/bin/tsc --noEmit 2>&1 | grep "src/myfeature/"

Interpreting the Output

• No output / empty result — grep found no errors in your new files. ✅ The files are type-correct (pre-existing errors elsewhere are unrelated).
• Lines printed — type errors exist in your new files. ❌ Fix and re-check.

Example clean output (no new errors):

(no output)

Example with errors:

src/greeting.ts(3,14): error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

Full End-to-End Example

Writing multiple TypeScript files and verifying them

Step 1 — Write the Python helper to /tmp/:

Use write_file with path /tmp/write_settings_files.py:

#!/usr/bin/env python3
import os

files = {
    "/app/src/settings/settings-keys.ts": """
export const SETTINGS_KEYS = {
  theme: 'app.theme',
  language: 'app.language',
} as const;

export type SettingKey = keyof typeof SETTINGS_KEYS;
""".lstrip("\n"),

    "/app/src/settings/settings-store.ts": """
import { SETTINGS_KEYS, SettingKey } from './settings-keys';

export class SettingsStore {
  private data: Record<string, string> = {};

  get(key: SettingKey): string | undefined {
    return this.data[SETTINGS_KEYS[key]];
  }

  set(key: SettingKey, value: string): void {
    this.data[SETTINGS_KEYS[key]] = value;
  }
}
""".lstrip("\n"),
}

for path, content in files.items():
    os.makedirs(os.path.dirname(path), exist_ok=True)
    with open(path, "w") as f:
        f.write(content)
    print(f"Written: {path}")

Step 2 — Execute the helper:

python3 /tmp/write_settings_files.py

Step 3 — Verify file contents:

cat /app/src/settings/settings-keys.ts
cat /app/src/settings/settings-store.ts

Step 4 — Type-check only the new files:

cd /app && node node_modules/typescript/bin/tsc --noEmit 2>&1 | grep "src/settings/"

Expected output if all is well: (empty — no errors in the new files)

Step 5 — Optional cleanup:

rm /tmp/write_settings_files.py

When to Use This Pattern

• write_file returns [ERROR] unknown error for a specific file.
• The file contains TypeScript/JavaScript template literals.
• The file contains mixed quote styles or shell-like special characters.
• Any time direct file writing fails and content cannot be easily sanitized.
• After writing TypeScript files and needing reliable type-checking.

Multiple Files

For writing several problematic files in one pass, consolidate them into a single Python script:

#!/usr/bin/env python3
import os

files = {
    "/app/src/component.tsx": """
import React from 'react';

const App = () => (
  <div className={`container`}>
    <h1>It's working!</h1>
  </div>
);

export default App;
""".lstrip("\n"),

    "/app/src/utils.ts": """
export const format = (val: number) => `Value: ${val.toFixed(2)}`;
""".lstrip("\n"),
}

for path, content in files.items():
    os.makedirs(os.path.dirname(path), exist_ok=True)
    with open(path, "w") as f:
        f.write(content)
    print(f"Written: {path}")

Key Advantages

• No shell escaping required — Python triple-quoted strings are literal.
• Handles all TypeScript syntax — template literals, generics, JSX, etc.
• Atomic — the target file is only created if the Python script succeeds.
• Debuggable — the intermediate .py file can be inspected if needed.
• Reliable type-checking — direct node invocation avoids npx/symlink failures.
• Targeted verification — grep filtering isolates errors in new files only, preventing pre-existing project errors from masking or confusing results.
• Cleanup (optional): rm /tmp/write_*.py after all files are written.