Site promotion tools

.github/copilot-instructions.md

@@ -0,0 +1,18 @@
+# Workspace Instructions
+
+Use this file only for rules that apply across the whole repository.
+
+## Scope
+
+- Keep site-specific or server-specific operational procedures out of this file.
+- Put per-site deployment and SSH rules in `.github/instructions/*.instructions.md` files.
+- Name site-specific instruction files clearly so the target host or site is obvious.
+
+## Current Site-Specific Instructions
+
+- `83.149.164.4` deployment and promotion rules live in `.github/instructions/regalamiunsorriso-83-149-164-4.instructions.md`.
+
+## Deployment Documentation
+
+- When deployment procedures change, update the matching site-specific instruction file.
+- Keep operational manifests such as `sync/www-deploy-manifest.md` aligned with the latest validated workflow.

.github/instructions/instructions.instructions.md

@@ -0,0 +1,270 @@
+---
+description: 'Guidelines for creating high-quality custom instruction files for GitHub Copilot'
+applyTo: '**/*.instructions.md'
+---
+
+# Custom Instructions File Guidelines
+
+Instructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating domain-specific code and following project conventions.
+
+## Project Context
+
+- Target audience: Developers and GitHub Copilot working with domain-specific code
+- File format: Markdown with YAML frontmatter
+- File naming convention: lowercase with hyphens (e.g., `react-best-practices.instructions.md`)
+- Location: `.github/instructions/` directory
+- Purpose: Provide context-aware guidance for code generation, review, and documentation
+
+## Required Frontmatter
+
+Every instruction file must include YAML frontmatter with the following fields:
+
+```yaml
+---
+description: 'Brief description of the instruction purpose and scope'
+applyTo: 'glob pattern for target files (e.g., **/*.ts, **/*.py)'
+---
+```
+
+### Frontmatter Guidelines
+
+- **description**: Single-quoted string, 1-500 characters, clearly stating the purpose
+- **applyTo**: Glob pattern(s) specifying which files these instructions apply to
+  - Single pattern: `'**/*.ts'`
+  - Multiple patterns: `'**/*.ts, **/*.tsx, **/*.js'`
+  - Specific files: `'src/**/*.py'`
+  - All files: `'**'`
+
+## File Structure
+
+A well-structured instruction file should include the following sections:
+
+### 1. Title and Overview
+
+- Clear, descriptive title using `#` heading
+- Brief introduction explaining the purpose and scope
+- Optional: Project context section with key technologies and versions
+
+### 2. Core Sections
+
+Organize content into logical sections based on the domain:
+
+- **General Instructions**: High-level guidelines and principles
+- **Best Practices**: Recommended patterns and approaches
+- **Code Standards**: Naming conventions, formatting, style rules
+- **Architecture/Structure**: Project organization and design patterns
+- **Common Patterns**: Frequently used implementations
+- **Security**: Security considerations (if applicable)
+- **Performance**: Optimization guidelines (if applicable)
+- **Testing**: Testing standards and approaches (if applicable)
+
+### 3. Examples and Code Snippets
+
+Provide concrete examples with clear labels:
+
+```markdown
+### Good Example
+\`\`\`language
+// Recommended approach
+code example here
+\`\`\`
+
+### Bad Example
+\`\`\`language
+// Avoid this pattern
+code example here
+\`\`\`
+```
+
+### 4. Validation and Verification (Optional but Recommended)
+
+- Build commands to verify code
+- Linting and formatting tools
+- Testing requirements
+- Verification steps
+
+## Content Guidelines
+
+### Writing Style
+
+- Use clear, concise language
+- Write in imperative mood ("Use", "Implement", "Avoid")
+- Be specific and actionable
+- Avoid ambiguous terms like "should", "might", "possibly"
+- Use bullet points and lists for readability
+- Keep sections focused and scannable
+
+### Best Practices
+
+- **Be Specific**: Provide concrete examples rather than abstract concepts
+- **Show Why**: Explain the reasoning behind recommendations when it adds value
+- **Use Tables**: For comparing options, listing rules, or showing patterns
+- **Include Examples**: Real code snippets are more effective than descriptions
+- **Stay Current**: Reference current versions and best practices
+- **Link Resources**: Include official documentation and authoritative sources
+
+### Instruction Altitude (Goldilocks Zone)
+
+- Start with the minimum rule set that fully defines expected outcomes
+- Add constraints after observed failures, not hypothetical edge cases
+- Prefer high-signal examples over exhaustive decision tables
+
+| Altitude | Failure Mode | Result |
+| --- | --- | --- |
+| Over-specified | Brittle if-else prose | Breaks on unlisted cases |
+| Under-specified | Assumes shared context | Generic outputs |
+| Right altitude | Heuristics + examples | Stable, generalizable quality |
+
+### Common Patterns to Include
+
+1. **Naming Conventions**: How to name variables, functions, classes, files
+2. **Code Organization**: File structure, module organization, import order
+3. **Error Handling**: Preferred error handling patterns
+4. **Dependencies**: How to manage and document dependencies
+5. **Comments and Documentation**: When and how to document code
+6. **Version Information**: Target language/framework versions
+
+## Patterns to Follow
+
+### Bullet Points and Lists
+
+```markdown
+## Security Best Practices
+
+- Always validate user input before processing
+- Use parameterized queries to prevent SQL injection
+- Store secrets in environment variables, never in code
+- Implement proper authentication and authorization
+- Enable HTTPS for all production endpoints
+```
+
+### Tables for Structured Information
+
+```markdown
+## Common Issues
+
+| Issue            | Solution            | Example                       |
+| ---------------- | ------------------- | ----------------------------- |
+| Magic numbers    | Use named constants | `const MAX_RETRIES = 3`       |
+| Deep nesting     | Extract functions   | Refactor nested if statements |
+| Hardcoded values | Use configuration   | Store API URLs in config      |
+```
+
+### Code Comparison
+
+```markdown
+### Good Example - Using TypeScript interfaces
+\`\`\`typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+function getUser(id: string): User {
+  // Implementation
+}
+\`\`\`
+
+### Bad Example - Using any type
+\`\`\`typescript
+function getUser(id: any): any {
+  // Loses type safety
+}
+\`\`\`
+```
+
+### Conditional Guidance
+
+```markdown
+## Framework Selection
+
+- **For small projects**: Use Minimal API approach
+- **For large projects**: Use controller-based architecture with clear separation
+- **For microservices**: Consider domain-driven design patterns
+```
+
+## Patterns to Avoid
+
+- **Overly verbose explanations**: Keep it concise and scannable
+- **Outdated information**: Always reference current versions and practices
+- **Ambiguous guidelines**: Be specific about what to do or avoid
+- **Missing examples**: Abstract rules without concrete code examples
+- **Contradictory advice**: Ensure consistency throughout the file
+- **Copy-paste from documentation**: Add value by distilling and contextualizing
+- **Hypothetical-rule inflation**: Do not add rules for failures that have not occurred
+
+## Testing Your Instructions
+
+Before finalizing instruction files:
+
+1. **Test with Copilot**: Try the instructions with actual prompts in VS Code
+2. **Verify Examples**: Ensure code examples are correct and run without errors
+3. **Check Glob Patterns**: Confirm `applyTo` patterns match intended files
+
+## Example Structure
+
+Here's a minimal example structure for a new instruction file:
+
+```markdown
+---
+description: 'Brief description of purpose'
+applyTo: '**/*.ext'
+---
+
+# Technology Name Development
+
+Brief introduction and context.
+
+## General Instructions
+
+- High-level guideline 1
+- High-level guideline 2
+
+## Best Practices
+
+- Specific practice 1
+- Specific practice 2
+
+## Code Standards
+
+### Naming Conventions
+- Rule 1
+- Rule 2
+
+### File Organization
+- Structure 1
+- Structure 2
+
+## Common Patterns
+
+### Pattern 1
+Description and example
+
+\`\`\`language
+code example
+\`\`\`
+
+### Pattern 2
+Description and example
+
+## Validation
+
+- Build command: `command to verify`
+- Linting: `command to lint`
+- Testing: `command to test`
+```
+
+## Maintenance
+
+- Review instructions when dependencies or frameworks are updated
+- Update examples to reflect current best practices
+- Remove outdated patterns or deprecated features
+- Add new patterns as they emerge in the community
+- Keep glob patterns accurate as project structure evolves
+
+## Additional Resources
+
+- [Custom Instructions Documentation](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
+- [Awesome Copilot Instructions](https://github.com/github/awesome-copilot/tree/main/instructions)
+- [System Prompt Altitude — Effective Context Engineering for AI Agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents#the-anatomy-of-effective-context)

.github/instructions/regalamiunsorriso-83-149-164-4.instructions.md

@@ -0,0 +1,131 @@
+---
+description: 'Use when: deploying, staging, copying, or promoting regalamiunsorriso site files on server 83.149.164.4, especially for sync/** and www/** changes.'
+applyTo: 'sync/**, www/**'
+---
+
+# Regalami Un Sorriso Server 83.149.164.4
+
+Instructions in this file are specific to the `regalamiunsorriso` site hosted on server `83.149.164.4` over SSH port `410`.
+
+## Server Access
+
+- SSH user: `marco`
+- SSH key: `C:\Users\Maddo\.ssh\id_rsa`
+- SSH port: `410`
+- Direct SSH login works with the key above.
+- The login banner before authentication is expected.
+
+## Preferred SSH Workflow
+
+Use an interactive TTY when a command may need sudo:
+
+```powershell
+ssh -tt -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4
+```
+
+For root access, use:
+
+```tcsh
+sudo tcsh
+```
+
+If you need a single elevated command:
+
+```powershell
+ssh -tt -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4 "sudo tcsh -c 'command here'"
+```
+
+## Shell Behavior On This Host
+
+- The remote login shell behaves as `tcsh`.
+- POSIX shell constructs like `for ...; do ...; done` fail unless you explicitly run them through `sh -c`.
+- The server `sh` does not support `-l`, so use `sh -c`, not `sh -lc`.
+- If `sudo` reports that a terminal is required, reconnect with `-tt`.
+
+## MCP Limitation
+
+- The MCP SSH tools have not been reliable for this host and previously failed authentication or transport checks.
+- Prefer direct terminal SSH commands for this server unless the MCP path is revalidated.
+
+## Site Paths
+
+- Incoming staging root: `/home/marco/regalamiunsorriso/incoming/www`
+- Live site root: `/home/sites/regalamiunsorriso/www`
+
+## Staging Workflow
+
+When `www/**` files need deployment:
+
+1. Build the file list from git changes after the initial `www` import baseline.
+2. Include any required uncommitted working tree files explicitly if they must be deployed.
+3. Copy the selected files into `/home/marco/regalamiunsorriso/incoming/www`, preserving the `www/...` directory structure.
+4. Prefer a streamed tar transfer over SSH for batches of files.
+
+Example staging command pattern:
+
+```powershell
+tar -cf - -C K:\various\regalamiunsorriso <file-list-under-www> | ssh -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4 "tar -xf - -C /home/marco/regalamiunsorriso/incoming"
+```
+
+## Promotion Rules
+
+- Promotion to the live site must happen through `sudo tcsh`.
+- Do not copy directly as `marco` into `/home/sites/regalamiunsorriso/www`.
+- Before replacing an existing live file, capture its exact owner, group, and mode.
+- After copy, restore the same owner, group, and mode exactly.
+- For new files, use the permissions of surrounding live files of the same type in the same directory.
+- If same-extension files in the directory have mixed modes, choose an explicit metadata source file and reuse its owner, group, and mode.
+
+## Promotion Automation
+
+Use these scripts for this site:
+
+- Local helper: `sync/promote-file.sh`
+- Local batch helper: `sync/promote-www-remaining.sh`
+- Remote helper: `/home/marco/promote-file.sh`
+- Remote batch helper: `/home/marco/promote-www-remaining.sh`
+
+### Single File Promotion
+
+Run:
+
+```powershell
+ssh -tt -i C:\Users\Maddo\.ssh\id_rsa -p 410 marco@83.149.164.4 "sudo tcsh -c '/home/marco/promote-file.sh <staged-path> <live-path> [metadata-source]'"
+```
+
+Behavior of `promote-file.sh`:
+
+- If the destination already exists, it copies the file and restores that destination file's original owner, group, and mode.
+- If the destination does not exist, it can use an optional third argument as the metadata source file.
+- If no third argument is provided for a new file, it falls back to sampling sibling files in the destination directory.
+
+### New PHP Files In Live Root
+
+Root-level PHP files on this site do not all share one mode.
+
+- `/home/sites/regalamiunsorriso/www/_inc_footer.php` is `jenkins:www` with mode `775`
+- `/home/sites/regalamiunsorriso/www/gallery1.php` is `jenkins:www` with mode `775`
+- `/home/sites/regalamiunsorriso/www/test.php` is `jenkins:www` with mode `644`
+
+For the `faceai_*.php` files, use `/home/sites/regalamiunsorriso/www/_inc_footer.php` as the explicit metadata source.
+
+## Verification
+
+After staging or promotion, verify with:
+
+- `ls -l` for owner, group, and visible mode
+- `stat -f` for exact metadata
+- `cksum` to compare staged and live file contents
+
+Run verification commands separately if a parallel terminal run becomes unreliable.
+
+## Documentation Expectations
+
+When performing deployments or promotions for this site:
+
+- Record the list of changed files being deployed.
+- Distinguish updated files from new files.
+- Note whether any deployed file came from the working tree instead of a commit.
+- Document every shell quirk or command failure encountered.
+- Document the metadata source used for any new live file.
+- Update `sync/www-deploy-manifest.md` when the deployment set or procedure changes.