backend-conventions

CLI & Data Conventions

worclaude is a CLI tool, not a backend service. This skill covers the patterns that serve a similar role to backend conventions: data access (filesystem), external service interaction (npm registry), configuration management, and data format handling (JSON).

Filesystem Access Patterns

All file operations use fs-extra (not raw fs):

• fs.ensureDir() for creating directories (idempotent)
• fs.copy() for template-to-project file copying
• fs.readJson() / fs.writeJson() for JSON files
• fs.pathExists() for existence checks before operations

Cross-platform rules:

• Always path.join() — never concatenate with /
• Normalize CRLF before hashing (content.replace(/\r\n/g, '\n'))
• Use os.platform() for OS-specific behavior (notification commands)

File utilities live in src/utils/file.js: copyDirectory(), removeDirectory().

npm Registry Interaction

Single external dependency: https://registry.npmjs.org/worclaude

// Shared utility: src/utils/npm.js — getLatestNpmVersion()
// - 5-second timeout (AbortController)
// - Returns null on any error (offline, timeout, 404)
// - Used by: upgrade command (self-update check), status command (version display)

No auth tokens. No environment variables. Plain HTTPS fetch. Graceful degradation — every caller handles null return.

JSON Handling

Settings builder flow

Read template JSON → JSON.parse() → merge objects → replaceHookCommands() → JSON.stringify()

Critical: replaceHookCommands() operates on the parsed object's string values, not on the full JSON string. The formatter command and notification command are replaced inside individual hook command strings after parsing.

Settings merge (append-only)

mergeSettingsPermissionsAndHooks():

• Permissions: append new rules to existing array, deduplicate by string equality
• Hooks: append new hooks, check for matcher conflicts before adding
• Never removes or replaces existing user rules