script-rules

Script Rules

Rule (CRITICAL)

When creating scripts, follow this priority order:

1. First choice: Shell script one-liners
2. Second choice: TypeScript with Deno (only when variables or complex branching are necessary)
3. Prohibited: Node.js and Python

Decision Flow

1. Can it be done with a shell one-liner? -> Use shell script
2. Does it need variables or complex logic? -> Use TypeScript with Deno (execute with deno run <file>)
3. Never use Node.js or Python

Shebang (REQUIRED)

All script files MUST include a shebang line. This ensures scripts are executable with the correct interpreter.

Bash

#!/bin/bash

Deno

Include required permissions directly in the shebang:

#!/usr/bin/env -S deno run --allow-read --allow-write

After adding the shebang, make the script executable with chmod +x <file>.

Priority 1: Shell Script One-Liners (PREFERRED)

Use shell script one-liners for simple operations:

# File operations
find . -name "*.js" -type f | xargs grep "pattern"

# Text processing
grep "pattern" file.txt | sed 's/old/new/g'

# File counting
find . -maxdepth 1 -type f | wc -l

# Directory operations
mkdir -p path/to/dir && cd path/to/dir

# Conditional execution
[ -f file.txt ] && echo "exists" || echo "not found"

Priority 2: TypeScript with Deno (When Necessary)

Use TypeScript with Deno only when:

• Variables are needed for complex logic
• Complex branching/conditionals are required
• Error handling beyond simple shell constructs is needed

Execution: Always use deno run <file> to execute Deno scripts.

// Example: Complex script with variables and branching
const files = Deno.readDirSync('.')
const results: string[] = []

for (const file of files) {
  if (file.isFile && file.name.endsWith('.ts')) {
    const content = Deno.readTextFileSync(file.name)
    if (content.includes('pattern')) {
      results.push(file.name)
    }
  }
}

console.log(results.join('\n'))

Execute with:

deno run --allow-read script.ts

Deno Import Rules

Three principles for Deno scripts:

1. Avoid URL imports — never import from https://deno.land/...
2. Use npm: / jsr: prefixes — for all external packages
   • Prefer jsr: over npm: when the package is available on both registries
3. Minimize dependencies — prefer Deno built-in APIs

Correct Import Format

// jsr packages (preferred)
import { Hono } from 'jsr:@hono/hono@4.0.0'
import { HttpException } from 'jsr:@hono/hono@4.0.0/http-exception'

// Deno standard library (via jsr)
import { join } from 'jsr:@std/path@1.0.0'
import { parse } from 'jsr:@std/yaml@1.0.0'

// npm packages (when not available on jsr)
import { z } from 'npm:zod@3.22.4'
import express from 'npm:express@4.21.0'

Incorrect Import Format

// NG: URL imports
import { serve } from 'https://deno.land/std@0.208.0/http/server.ts'
import { z } from 'https://deno.land/x/zod@v3.22.4/mod.ts'

Prefer Deno Built-in APIs

Before using external packages, check if Deno built-in APIs can accomplish the task:

// File operations
const content = await Deno.readTextFile('./data.json')
await Deno.writeTextFile('./output.txt', result)

// Directory operations
await Deno.mkdir('./output', { recursive: true })
for await (const entry of Deno.readDir('./src')) {
  console.log(entry.name)
}

// Environment variables
const apiKey = Deno.env.get('API_KEY')

// Command execution
const command = new Deno.Command('git', {
  args: ['status'],
  stdout: 'piped',
})
const { stdout } = await command.output()

Prohibited Technologies

The following are strictly prohibited:

• Node.js: node script.js, npm run, etc.
• Python: python script.py, python3 script.py, pip install, etc.

Additional Resources

• Deno.* API Reference - Deno built-in API reference