Bash Refactor Plan 1

Scope: Create the Write_Typescript skill and forge-bash project scaffold

Spec: Bash Refactor Spec

Prior plan: None

---

Task 1 — Create Write_Typescript Skill

Spec Section 3: “A new skill at Forge/Skills/Write_Typescript/SKILL.md captures the TypeScript conventions from Section 1.”

Create the skill file at Forge/Skills/Write_Typescript/SKILL.md with these conventions:

1. Runtime & build: esbuild bundles src/index.ts to dist/index.js — a single-file ESM bundle executed with node dist/index.js. No node_modules at runtime.
2. Module system: ESM only ("type": "module" in package.json).
3. MCP SDK: McpServer from @modelcontextprotocol/sdk/server/mcp.js, StdioServerTransport from @modelcontextprotocol/sdk/server/stdio.js.
4. Schema validation: Zod via zod/v4 import.
5. Project structure: src/index.ts entry, dist/ output (gitignored), package.json, tsconfig.json.
6. Build command: esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js
7. Type checking: tsc --noEmit (separate from build; esbuild doesn’t type-check).
8. Error handling: Tools return { content: [{ type: 'text', text: error }], isError: true }.
9. Logging: console.error() for debug/diagnostic output (stdout is reserved for MCP protocol).
10. Naming: kebab-case for directories and file names; PascalCase for TypeScript types/interfaces.
11. Railway env: Shared utility for reading /proc/1/environ to inject Railway environment variables.

The skill follows the standard format: procedure outline and essential rules in SKILL.md (≤500 words). No references/ directory needed unless extended examples are required later.

Add sidebar entry using the Update_Sidebar skill. Build to verify.

---

Task 2 — Create forge-bash Project Scaffold

Spec Sections 1–2: Project layout and TypeScript implementation standard.

Create the directory structure at Forge/Configs-debian/mcp-servers/forge-bash/:

forge-bash/
├── src/
│   └── index.ts
├── dist/          # gitignored
├── package.json
├── tsconfig.json
└── README.md

package.json contents:

• "name": "forge-bash", "version": "1.0.0", "type": "module"
• Scripts: "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js", "typecheck": "tsc --noEmit"
• Dependencies: @modelcontextprotocol/sdk, zod, @cfworker/json-schema (peer dep of SDK)
• Dev dependencies: esbuild, typescript, @types/node

tsconfig.json contents:

• "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext"
• "strict": true, "outDir": "dist", "rootDir": "src"
• "include": ["src"]

README.md: Brief description of forge-bash, build instructions, and link to the Spec.

src/index.ts: Stub — just the McpServer setup with a placeholder run tool that returns “not yet implemented”. This validates the build pipeline works end-to-end:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod/v4';

const server = new McpServer({ name: 'forge-bash', version: '1.0.0' });

server.registerTool(
  'run',
  {
    description: 'Execute a shell command or pipeline in /workspace. Supports operators: | (pipe), && (and), || (or), ; (sequence). rm is blocked — use uvilo-trash instead. All commands are audit-logged.',
    inputSchema: z.object({
      command: z.string().describe('Full command string, including pipes and chain operators.'),
    }),
  },
  async ({ command }) => {
    return { content: [{ type: 'text', text: 'Not yet implemented' }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

After creating files, install dependencies and build:

1. cd Forge/Configs-debian/mcp-servers/forge-bash && npm install
2. npm run build
3. npm run typecheck

Add dist/ to .gitignore (append to repo root .gitignore if not already present).

No sidebar entry needed for non-markdown source files (file-view pages are auto-generated).