@jml6m/skeletor 0.1.0-alpha.1 → 0.1.0-alpha.2

package/templates/java/AGENTS.md

@@ -0,0 +1,9 @@
+# Java Project — Agent Guidelines
+
+**Project:** {{PROJECT_NAME}}
+**Language:** Java (Maven)
+
+- Build with `mvn clean compile`, test with `mvn test`.
+- Use JUnit 5 for tests.
+- Follow standard package naming and clean architecture.
+- Update this file with any team-specific Java conventions.

package/templates/java/README.md

@@ -0,0 +1,12 @@
+# {{PROJECT_NAME}}
+
+{{DESCRIPTION}}
+
+## Development
+
+```bash
+mvn clean compile
+mvn test
+```
+
+Standard Maven Java 17+ project.

package/templates/java/pom.xml

@@ -0,0 +1,38 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.example</groupId>
+    <artifactId>{{PROJECT_NAME}}</artifactId>
+    <version>0.1.0</version>
+    <packaging>jar</packaging>
+
+    <name>{{PROJECT_NAME}}</name>
+    <description>{{DESCRIPTION}}</description>
+
+    <properties>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>5.10.2</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>3.2.5</version>
+            </plugin>
+        </plugins>
+    </build>
+</project>

package/templates/java/src/main/java/com/example/App.java

@@ -0,0 +1,16 @@
+package com.example;
+
+/**
+ * {{PROJECT_NAME}}
+ *
+ * {{DESCRIPTION}}
+ */
+public class App {
+    public static void main(String[] args) {
+        System.out.println(hello("world"));
+    }
+
+    public static String hello(String name) {
+        return String.format("Hello, %s from {{PROJECT_NAME}}!", name);
+    }
+}

package/templates/java/src/test/java/com/example/AppTest.java

@@ -0,0 +1,12 @@
+package com.example;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+class AppTest {
+
+    @Test
+    void helloReturnsGreeting() {
+        assertEquals("Hello, tester from {{PROJECT_NAME}}!", App.hello("tester"));
+    }
+}

package/templates/java/template.json

@@ -0,0 +1,10 @@
+{
+  "id": "java",
+  "name": "Java (Maven)",
+  "description": "Standard Maven Java project with pom.xml, src/main/java structure, and basic JUnit tests.",
+  "language": "java",
+  "verifyCommands": [
+    "mvn clean compile",
+    "mvn test"
+  ]
+}

package/templates/javascript/.editorconfig

@@ -0,0 +1,16 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.js]
+quote_type = single
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/templates/javascript/.eslintrc.json

@@ -0,0 +1,82 @@
+{
+  "env": {
+    "node": true,
+    "es2021": true,
+    "commonjs": true,
+    "jest": true
+  },
+  "extends": ["eslint:recommended", "plugin:import/recommended"],
+  "plugins": ["unused-imports", "import"],
+  "parserOptions": {
+    "ecmaVersion": "latest"
+  },
+  "settings": {
+    "import/resolver": {
+      "jsconfig": {
+        "config": "jsconfig.json",
+        "extensions": [".js", ".json"]
+      }
+    }
+  },
+  "rules": {
+    "no-unused-vars": "off",
+    "unused-imports/no-unused-imports": "error",
+    "unused-imports/no-unused-vars": [
+      "warn",
+      {
+        "vars": "all",
+        "varsIgnorePattern": "^_",
+        "args": "after-used",
+        "argsIgnorePattern": "^_"
+      }
+    ],
+    "no-restricted-syntax": [
+      "warn",
+      {
+        "selector": "CallExpression[callee.object.name='logger'][callee.property.name=/^(info|warn|error|debug|http|log)$/] > TemplateLiteral:first-child",
+        "message": "Avoid template literals in logger messages. Use a static string and pass variables as metadata: logger.info('Event description', { key: value })"
+      }
+    ],
+    "no-console": "warn",
+    "no-empty": ["error", { "allowEmptyCatch": false }],
+    "no-undef": "error",
+    "no-restricted-imports": [
+      "error",
+      {
+        "patterns": [
+          {
+            "group": ["../*"],
+            "message": "Do not use parent imports. Use architectural aliases (e.g. @services, @utils) or sibling imports (./)."
+          }
+        ]
+      }
+    ],
+    "no-restricted-properties": [
+      "error",
+      {
+        "object": "process",
+        "property": "env",
+        "message": "Use @config (or equivalent) instead of process.env directly."
+      },
+      {
+        "object": "process",
+        "property": "exit",
+        "message": "Direct process.exit() is discouraged. Use error handling or a dedicated shutdown utility."
+      }
+    ]
+  },
+  "overrides": [
+    {
+      "files": ["knip.config.js", "release.js", "scripts/**/*.js", "tests/**/*.js"],
+      "rules": {
+        "no-console": "off"
+      }
+    },
+    {
+      "files": ["release.js", "scripts/**/*.js", "tests/support/**/*.js"],
+      "rules": {
+        "no-restricted-properties": "off"
+      }
+    }
+  ]
+}

package/templates/javascript/.github/workflows/README.md

@@ -0,0 +1,7 @@
+# GitHub Workflows
+
+Basic CI is included (lint + test + health).
+
+Customize as needed (add build step, matrix for Node versions, deployment jobs, etc.).
+
+See the root AGENTS.md for policies around releases and agent usage of these workflows.

package/templates/javascript/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint
+
+      - name: Run tests
+        run: npm test
+
+      - name: Run health checks (knip / dupes / circular)
+        run: npm run health:full || true

package/templates/javascript/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Husky v9 + lint-staged pre-commit
+# Runs format/lint on staged files only. Fast feedback before commit.
+npx lint-staged

package/templates/javascript/.prettierrc.json

@@ -0,0 +1,24 @@
+{
+  "tabWidth": 2,
+  "printWidth": 165,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "plugins": ["prettier-plugin-organize-imports", "prettier-plugin-pkg"],
+  "overrides": [
+    {
+      "files": ["*.json", "*.jsonc", "*.json5"],
+      "options": {
+        "parser": "json",
+        "tabWidth": 2
+      }
+    },
+    {
+      "files": "*.md",
+      "options": {
+        "tabWidth": 2
+      }
+    }
+  ]
+}

package/templates/javascript/AGENTS.md

@@ -0,0 +1,110 @@
+# 🤖 Agent & AI Protocols (All Agents)
+
+**Project:** {{PROJECT_NAME}} <br />
+**Runtime:** Node.js (>=20.19.0) <br />
+**Testing:** Jest
+
+> **📌 Single Source of Truth**: This document is the authoritative reference for all coding standards, architecture rules, and project policies in this repository. If there is a conflict between this document and any other file, `AGENTS.md` takes precedence.
+
+This document defines the operational parameters, architectural standards, and safety protocols for all AI agents working within this repository.
+
+---
+
+## 🛑 Critical Protocols (Read First)
+
+### 1. The "Three Strike" Rule (Loop Prevention)
+
+For unsupervised runs (e.g. automated fixes or refactors):
+- If you attempt to fix an error and the **same** error persists after **3 attempts**:
+  - **STOP**.
+  - Revert to the last functioning state.
+  - Mark the test/code with `// FIXME: Agent worker failed` or `.skip`.
+  - Log the failure and move on.
+
+### 2. Versioning & Release Policy
+
+- **One PR = One Bump**: Version bump happens **once** using `npm run release:patch` when creating the PR.
+- `npm run release:minor` only for substantial new features (coordinate with admin).
+- ⛔ `npm run release:major` is **human-only**.
+
+### 3. Command Execution Safety
+
+**STRICTLY PROHIBITED for agents:**
+- `npm publish`
+- `git push` (agents propose; humans / CI push)
+- Running migrations or prod start commands without explicit request
+- Direct edits to core bootstrap / auth / secret-handling files (see Exclusions below)
+
+### 4. Code Review & PR Interaction
+
+- The agent **MUST** respond to comments from the primary (human) reviewer or when explicitly @-tagged.
+- **No passive "Acknowledged" / "Will fix"**. Either make the change or discuss with technical reasoning.
+- Human reviewer comments always take priority over bot threads.
+
+### 5. Cross-Repo Coordination (when applicable)
+
+When work spans multiple repositories, create paired issues and cross-link PRs in both Coordination sections.
+
+---
+
+## 📐 Architecture & Coding Standards
+
+- **Module aliases over relatives**: Never use `../`. Use `@src`, `@utils`, `@config`, `@services`, etc. (enforced by ESLint + jsconfig).
+- **Configuration SSoT**: Never read `process.env` directly in feature code. Centralize in `@config`.
+- **Layered architecture** (recommended): Routes/Controllers (thin) → Services (business logic) → Models/Mechanics (pure functions).
+- **Zod where helpful**: Use for config validation and request/input schemas.
+- **Logging**: Use a structured logger (Winston or equivalent). Static message strings + metadata object. Never `console.log` in production paths.
+- **Error handling**: Use explicit `AppError` / error classes with constants for consistent responses.
+
+See `docs/CODING_STANDARDS.md` (if present) for expanded examples.
+
+### Code Style (enforced)
+
+- Prettier (see `.prettierrc.json`): 2 spaces, single quotes, semicolons, printWidth 165, organize-imports.
+- File names: `kebab-case.js` or `kebab-case.test.js`.
+- Functions: `camelCase`, classes `PascalCase`, constants `SCREAMING_SNAKE_CASE`.
+
+### ESLint highlights (see .eslintrc.json)
+
+- `unused-imports/no-unused-imports`: error
+- `no-restricted-imports`: `../*` forbidden
+- `no-restricted-properties`: `process.env` and `process.exit` (with documented exceptions)
+- `no-console`: warn (scripts/tests/config overrides allowed)
+
+---
+
+## 🛡️ Logging & Error Handling (summary)
+
+- Import the shared logger.
+- Messages are **static strings**; data goes in the 2nd (metadata) argument.
+- For errors: always log `{ error: err.message, stack: err.stack }`.
+- See the full patterns in active reference projects (local-land-server etc.).
+
+---
+
+## 🧪 Testing
+
+- Unit tests: heavily mock external deps (DB, network, time).
+- Integration: use in-memory or test harnesses where available.
+- Follow AAA. Keep tests readable and deterministic.
+- Run `npm run health:full` before opening PRs.
+
+---
+
+## 🛑 Excluded Source Code (for AI context size & security)
+
+The following are intentionally **not** provided in full to agents by default. Ask for snippets if you need to propose changes.
+
+- `src/index.js` (or main entry / bootstrap)
+- Authentication / token / JWT utilities
+- Any file that would require hard-coding real secrets
+
+**Never** output real secrets, tokens, or keys. Use config + env.
+
+---
+
+## Additional Resources
+
+- Your personal conventions are derived from analysis of multiple active GitHub-linked workspaces.
+- Update this file when the project's architecture or policies evolve.
+- `npm run prompt:gen` (or with `--all`) can be used to produce a full context dump for complex tasks.

package/templates/javascript/README.md

@@ -0,0 +1,38 @@
+# {{PROJECT_NAME}}
+
+{{DESCRIPTION}}
+
+## Standards
+
+This project was scaffolded with [skeletor](https://github.com/jml6m/skeletor) and follows personal conventions extracted from active workspaces:
+
+- Prettier + organize-imports + pkg plugin (printWidth 165, 2 spaces, single quotes)
+- ESLint + unused-imports (strict), no parent relative imports (`../*`)
+- Knip (dead code), jscpd (dupes), madge (circular) via `npm run health:full`
+- Custom `release.js` (one bump per PR, major gates via GitHub issue labels `vN-required`)
+- AGENTS.md as the Single Source of Truth for coding standards + AI agent protocols
+- Path aliases (`@src`, `@utils`, etc.) enforced at lint + runtime (module-alias)
+
+See [AGENTS.md](./AGENTS.md) for the full contract.
+
+## Quick start
+
+```bash
+npm install
+npm run format
+npm run lint
+npm test
+npm run health:full
+```
+
+## Release flow (per conventions)
+
+- Open PR → run `npm run release:patch` **once** at PR creation
+- `npm run release:minor` only for substantial features (coordinate)
+- Majors are human-only and gated by open issues labeled `vX-required`
+
+## Tooling scripts
+
+- `npm run npm:reinstall` — clean node_modules + lock then fresh install
+- `npm run prompt:gen` — build prompt.md for AI context (respects excludes)
+- `npm run health:*` — quality gates

package/templates/javascript/docs/CODING_STANDARDS.md

@@ -0,0 +1,14 @@
+# Coding Standards — {{PROJECT_NAME}}
+
+See [AGENTS.md](../AGENTS.md) for the authoritative rules.
+
+This document can be expanded with project-specific examples for:
+
+- Layered architecture (routes / controllers / services / mechanics)
+- Zod schema patterns for config + validation
+- Logging examples (static msg + metadata)
+- Alias usage and module-alias setup
+- Error constants + AppError usage
+- Jest testing patterns + test harness
+
+Pull the detailed examples from reference projects (local-land-server, etc.) when you need them and adapt here.

package/templates/javascript/jest.config.js

@@ -0,0 +1,7 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.js', '**/__tests__/**/*.js'],
+  collectCoverageFrom: ['src/**/*.js'],
+  coveragePathIgnorePatterns: ['/node_modules/'],
+};

package/templates/javascript/jsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es2021",
+    "checkJs": true,
+    "baseUrl": ".",
+    "paths": {
+      "@root/*": ["./*"],
+      "@src/*": ["src/*"],
+      "@config/*": ["src/config/*"],
+      "@constants/*": ["src/constants/*"],
+      "@config": ["src/config/index.js"],
+      "@services/*": ["src/services/*"],
+      "@mechanics/*": ["src/mechanics/*"],
+      "@utils/*": ["src/utils/*"]
+    }
+  },
+  "exclude": ["node_modules", "**/node_modules/*"]
+}

package/templates/javascript/knip.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": ["src/index.js"],
+  "project": ["src/**/*.js", "tests/**/*.js"],
+  "ignore": ["db/**", "migrations/**", "scripts/**"],
+  "ignoreExportsUsedInFile": true
+}

package/templates/javascript/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{DESCRIPTION}}",
+  "main": "src/index.js",
+  "license": "UNLICENSED",
+  "scripts": {
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "prepare": "husky",
+    "start": "node src/index.js",
+    "test": "jest --verbose",
+    "test:coverage": "jest --coverage --verbose",
+    "release:patch": "node release.js patch",
+    "release:minor": "node release.js minor",
+    "release:major": "node release.js major",
+    "npm:reinstall": "node scripts/reinstall.js",
+    "prompt:gen": "node scripts/generate-context.js",
+    "health:dead": "knip --no-exit-code",
+    "health:dupes": "jscpd src || node -e \"process.exit(0)\"",
+    "health:circular": "madge --circular --extensions js src || node -e \"process.exit(0)\"",
+    "health:full": "npm-run-all --sequential health:dead health:dupes health:circular"
+  },
+  "dependencies": {
+    "module-alias": "^2.3.4"
+  },
+  "devDependencies": {
+    "cross-env": "^10.1.0",
+    "eslint": "^8.57.0",
+    "eslint-import-resolver-jsconfig": "^1.1.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "jscpd": "^4.0.0",
+    "knip": "^5.86.0",
+    "lint-staged": "^15.2.0",
+    "madge": "^8.0.0",
+    "npm-run-all": "^4.1.5",
+    "prettier": "^3.3.3",
+    "prettier-plugin-organize-imports": "^4.3.0",
+    "prettier-plugin-pkg": "^0.21.2"
+  },
+  "_moduleAliases": {
+    "@root": ".",
+    "@src": "src",
+    "@config": "src/config",
+    "@constants": "src/constants",
+    "@utils": "src/utils",
+    "@services": "src/services",
+    "@mechanics": "src/mechanics"
+  },
+  "lint-staged": {
+    "*.{js,json,md,yml,yaml}": "prettier --write"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}