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

package/README.md

@@ -1,11 +1,143 @@
 # Skeletor
-Efficient scaffolding for custom development
+Efficient scaffolding for custom development.
 
-## Status: Active Development
-This project is currently in its early alpha stage. The global `skeletor` command is reserved for active development. 
+Generates empty (or lightly stubbed) projects pre-configured with **your** rules and recommendations, derived from analysis of many GitHub-linked workspaces (local-land-client/server, cuda-sandbox, x-app-skeleton, etc.).
+
+## Available Templates
+
+Skeletor lets you **pick** the kind of project you want. Run `skeletor new my-project` (omit `--template`) for an interactive selector, or pass `--template <id>`.
+
+Current templates (standard main libraries + your flavors where they existed):
+
+- `javascript` — Your exact CJS conventions (Prettier 165, ESLint+unused-imports, aliases, health tools, release gates, AGENTS.md, husky+lint-staged, etc.)
+- `typescript` — Modern ESM + flat ESLint + TypeScript, tsconfig, build, your quality gates + AGENTS.md
+- `python` — Best-practice defaults (pyproject.toml + ruff for lint+format, pytest, mypy, src layout)
+- `go` — Standard Go module (`go.mod` + main + tests)
+- `rust` — Standard Cargo binary crate
+- `java` — Maven + JUnit 5 structure
+- `csharp` — .NET 8 console + xUnit
+
+Each template includes a `template.json` manifest that declares `verifyCommands` — the exact steps (3 & 4) a developer should run after scaffolding. The test suite discovers templates and validates this contract.
+
+> New languages/stacks: Drop a directory under `templates/<id>/` with a `template.json` + conventional source/build/test files using `{{PROJECT_NAME}}` etc. tokens. The CLI, listing, and tests pick it up automatically.
+
+## Rich Interactive CLI
+
+We use `@clack/prompts` for a modern experience:
+- Beautiful template selector with descriptions/hints when you omit `--template`
+- Prompts for owner and description (interactive mode only)
+- Confirmation step
+- Proper cancel handling and nice spinners/intro/outro
+
+`--auto` stays fully non-interactive for scripts (requires `--template`; uses default owner/description).
+
+## Pushing to GitHub
+
+**Pushing is not automatic.** After every set of changes (new templates, CLI updates, tests, docs), you **must** explicitly:
+1. `git add -A`
+2. `git commit -m "..."` (good message)
+3. `git push -u origin HEAD`
+
+See the root `AGENTS.md` for the standing instruction given to agents working on this repo. This ensures the GitHub repo (`https://github.com/jml6m/skeletor`) stays in sync with every request. There is no special Grok Build setting that auto-pushes; it must be done via explicit git commands in the agent loop (or documented in project instructions like AGENTS.md).
+
+## Usage (alpha)
 
-## Installation
-You can run the alpha placeholder using npx:
 ```bash
-npx skeletor
-```
+# Interactive (recommended for exploration)
+node src/index.js new my-project
+
+# Or specify
+node src/index.js new my-api --template typescript
+
+# Non-interactive (scripts)
+npx @jml6m/skeletor new my-service --auto --template go
+```
+
+Common flags:
+- `--template <id>` (javascript, typescript, python, go, rust, java, csharp, ...)
+- `--auto` (skip all prompts; requires `--template`)
+- `--no-git` (skip git init; git is on by default)
+
+After scaffolding, follow the `verifyCommands` from that template's `template.json` (shown in the success message). E.g. for most JS/TS: `npm install && npm run health:full` etc.
+
+Run `skeletor` (or `node src/index.js`) with no args to see current templates.
+
+## Philosophy / Goals
+
+- Developers **pick** the scaffolding they want (language + flavor).
+- Your personal conventions (from the workspaces analysis) are encoded in the relevant templates (javascript/typescript for now).
+- Everything else starts from clean "standard main library" best practices and can be refined later.
+- The `template.json` manifest per template is the contract for post-generation steps (this is what the test suite validates as steps 3 & 4).
+- Easy to evolve: add/edit under `templates/<id>/`. New templates are auto-discovered by the CLI and tests.
+
+## Status
+
+Active. Multiple language templates + rich clack-based interactive UI. Test suite validates generation + manifest contracts for every template.
+
+Run `skeletor` (or `node src/index.js`) with no args for current help and template list.
+
+## For Testers & Reviewers
+
+### Quick try (no install needed)
+
+```bash
+# From a clone of this repo
+node src/index.js new my-test-project --auto --template javascript
+
+cd my-test-project
+npm install
+npm run format
+npm run lint
+npm test
+npm run health:full
+```
+
+Inspect the generated files, especially:
+- `AGENTS.md`
+- `release.js` (owner/repo substituted)
+- `.prettierrc.json`, `.eslintrc.json`, `knip.json`
+- `.husky/pre-commit` and `lint-staged` config
+- `.github/workflows/ci.yml`
+- `src/` structure + alias usage in `src/index.js`
+- `package.json` scripts and `_moduleAliases`
+
+### Running the unit + integration test suite
+
+```bash
+npm install          # pulls jest (devDep)
+npm test
+```
+
+The tests cover:
+- CLI argument parsing
+- Template token rendering (`{{PROJECT_NAME}}` etc.)
+- Full generation into temp dirs (verifies file presence, JSON validity, token substitution, new husky/github artifacts, refusal to overwrite, etc.)
+- The generated projects are exercised for basic structure (no full `npm install` of heavy tools in every test to keep it fast).
+
+All tests are in `tests/`.
+
+### Updating / Adding Templates
+
+The source of truth lives in `templates/<id>/` (each with its own `template.json`).
+
+- Edit files inside an existing template → next generation gets the change.
+- Add a whole new `templates/newlang/` with `template.json` + files → it appears in the picker, help, and tests automatically.
+- **Ecosystem manifest files** (e.g. `package.json`, `pyproject.toml`, `Cargo.toml`, `pom.xml`, `*.csproj`, `go.mod`) must be named with a `.tmpl` suffix inside the template (e.g. `package.json.tmpl`). The generator strips the suffix on output, so the generated project sees the conventional filename. This prevents GitHub's dependency graph from treating template dependencies as skeletor's own.
+
+Always run `npm test` after template work.
+
+When happy, commit + push (see root `AGENTS.md` for the standing rule).
+
+### GitHub push & external review
+
+Pushing is **explicit** (not automatic). After changes:
+- Run tests
+- `git add -A && git commit -m "..." && git push -u origin HEAD`
+
+See the root `AGENTS.md` (the instruction file for agents) for the exact rule.
+
+The repo lives at https://github.com/jml6m/skeletor.
+
+Open issues/PRs with feedback on new templates, UI, etc.
+
+Now, finish the UI polish if needed and do the push.

package/package.json

@@ -1,13 +1,44 @@
 {
   "name": "@jml6m/skeletor",
-  "version": "0.1.0-alpha.1",
-  "description": "Efficient scaffolding for custom development",
+  "version": "0.1.0-alpha.5",
+  "description": "Efficient scaffolding for custom development. Generates projects wired with personal lint/format/health/release/alias/AGENTS.md conventions.",
   "main": "src/index.js",
   "type": "module",
   "bin": {
     "skeletor": "src/index.js"
   },
-  "keywords": [],
+  "scripts": {
+    "test": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --watch",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jml6m/skeletor.git"
+  },
+  "files": [
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "keywords": [
+    "scaffolding",
+    "generator",
+    "yeoman",
+    "template",
+    "eslint",
+    "prettier",
+    "knip"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.5.1"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
   "author": "",
-  "license": "ISC"
+  "license": "ISC",
+  "engines": {
+    "node": ">=20.19.0"
+  }
 }

package/src/index.js

@@ -1,7 +1,347 @@
 #!/usr/bin/env node
+/**
+ * Skeletor — Efficient scaffolding for custom development
+ * Generates projects pre-configured with personal standards derived from
+ * local-land-*, cuda-sandbox, x-app-skeleton and similar workspaces.
+ */
 
-console.log("\n💀 Skeletor CLI — Alpha Release");
-console.log("================================");
-console.log("This tool is currently under active development.");
-console.log("Please check back later or view our progress on GitHub:\n");
-console.log("👉 https://github.com/jml6m/skeletor\n");
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+import * as p from '@clack/prompts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, '..');
+const TEMPLATES_DIR = path.join(ROOT, 'templates');
+
+const USAGE = `
+💀 skeletor — pick your scaffolding
+
+Usage:
+  skeletor new <name> [options]
+  skeletor --help
+
+Options:
+  --template <name>     Stack to scaffold (javascript, typescript, python, go, …)
+                        Omit for an interactive language/stack picker (TTY required)
+  --auto                Non-interactive; requires --template (uses defaults — edit
+                        owner/description in generated files afterward)
+  --no-git              Skip git init (git is initialized by default)
+
+Examples:
+  skeletor new my-api                    # interactive: pick stack, owner, description
+  skeletor new my-api --template typescript
+  skeletor new my-lib --auto --template go
+  skeletor new my-lib --auto --template go --no-git
+`;
+
+
+function log(msg) { console.log(msg); }
+function logError(msg) { console.error(msg); }
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const result = {
+    command: null,
+    name: null,
+    template: null, // resolved later, can be interactive
+    auto: false,
+    git: true,
+  };
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    result.command = 'help';
+    return result;
+  }
+
+  if (args[0] === 'new') {
+    result.command = 'new';
+    result.name = args[1];
+    for (let i = 2; i < args.length; i++) {
+      const a = args[i];
+      if (a === '--template' || a === '-t') result.template = args[++i] || null;
+      else if (a === '--auto') result.auto = true;
+      else if (a === '--no-git') result.git = false;
+      else if (!a.startsWith('-') && !result.name) result.name = a;
+    }
+  } else {
+    result.command = 'help';
+  }
+
+  return result;
+}
+
+function render(content, vars) {
+  let out = content;
+  for (const [k, v] of Object.entries(vars)) {
+    const token = new RegExp(`\\{\\{${k}\\}\\}`, 'g');
+    out = out.replace(token, String(v));
+  }
+  return out;
+}
+
+/** Sanitize a segment for use in Java groupId / Go module paths. */
+function sanitizeIdentifierSegment(value) {
+  return String(value).replace(/[^a-zA-Z0-9]/g, '').toLowerCase() || 'example';
+}
+
+/** Build the full token map passed to copyAndRender. */
+function buildRenderVars({ name, owner, description }) {
+  const repoOwner = owner || 'jml6m';
+  const ownerSegment = sanitizeIdentifierSegment(repoOwner);
+  const namespace = String(name).replace(/-/g, '_');
+  return {
+    PROJECT_NAME: name,
+    REPO_OWNER: repoOwner,
+    REPO_NAME: name,
+    DESCRIPTION: description || 'A new project scaffolded with skeletor.',
+    YEAR: new Date().getFullYear(),
+    NAMESPACE: namespace,
+    GROUP_ID: `io.github.${ownerSegment}`,
+    GO_MODULE: `github.com/${repoOwner}/${name}`,
+  };
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function copyAndRender(src, dest, vars) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    ensureDir(dest);
+    for (const entry of fs.readdirSync(src)) {
+      // never copy node_modules, .git, or skeletor manifest inside templates
+      if (entry === 'node_modules' || entry === '.git' || entry === 'template.json') continue;
+      // strip .tmpl suffix from output filename so e.g. package.json.tmpl → package.json
+      const outEntry = entry.endsWith('.tmpl') ? entry.slice(0, -'.tmpl'.length) : entry;
+      copyAndRender(path.join(src, entry), path.join(dest, outEntry), vars);
+    }
+    return;
+  }
+
+  // text file -> render
+  let content = fs.readFileSync(src, 'utf8');
+  content = render(content, vars);
+  ensureDir(path.dirname(dest));
+  fs.writeFileSync(dest, content, 'utf8');
+}
+
+function getAvailableTemplates() {
+  if (!fs.existsSync(TEMPLATES_DIR)) return [];
+  return fs.readdirSync(TEMPLATES_DIR).filter((d) => {
+    const p = path.join(TEMPLATES_DIR, d);
+    return fs.statSync(p).isDirectory();
+  });
+}
+
+function loadTemplateManifest(templateId) {
+  const dir = path.join(TEMPLATES_DIR, templateId);
+  const manifestPath = path.join(dir, 'template.json');
+  let manifest = {
+    id: templateId,
+    name: templateId,
+    description: 'A custom template.',
+    language: templateId,
+    verifyCommands: [],
+  };
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      manifest = { ...manifest, ...raw };
+    } catch (e) {
+      // ignore bad manifest, fall back to defaults
+    }
+  }
+  return { ...manifest, dir };
+}
+
+function getTemplatesWithManifests() {
+  const ids = getAvailableTemplates();
+  return ids.map((id) => loadTemplateManifest(id));
+}
+
+async function chooseTemplateInteractively(templates) {
+  if (templates.length === 0) {
+    return null;
+  }
+
+  p.intro('💀 Skeletor — pick your scaffolding');
+
+  const options = templates.map((t) => ({
+    value: t.id,
+    label: t.name,
+    hint: t.description.length > 60 ? t.description.slice(0, 57) + '...' : t.description,
+  }));
+
+  const selected = await p.select({
+    message: 'What language or stack are you building?',
+    options,
+  });
+
+  if (p.isCancel(selected)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  return selected;
+}
+
+const DEFAULT_OWNER = 'jml6m';
+const DEFAULT_DESCRIPTION = 'A new project scaffolded with skeletor.';
+
+async function runNew(opts) {
+  const { name, git, auto } = opts;
+
+  if (!name || name === '.' || name === '..') {
+    logError('❌ Please provide a valid project name (e.g. "my-api").');
+    process.exit(1);
+  }
+
+  const allTemplates = getTemplatesWithManifests();
+  if (allTemplates.length === 0) {
+    logError('❌ No templates found in templates/ directory.');
+    process.exit(1);
+  }
+
+  let chosenTemplateId = opts.template;
+  let finalOwner = DEFAULT_OWNER;
+  let finalDesc = DEFAULT_DESCRIPTION;
+
+  const isInteractive = !auto && process.stdout.isTTY;
+
+  if (!chosenTemplateId) {
+    if (auto) {
+      logError('❌ --auto requires --template <id>. Pick a stack interactively by omitting --auto.');
+      logError(`   Available: ${allTemplates.map((t) => t.id).join(', ')}`);
+      process.exit(1);
+    }
+    if (!process.stdout.isTTY) {
+      logError('❌ No --template provided and this is not an interactive terminal.');
+      logError('   Use --auto --template <id> for scripts and piped environments.');
+      logError(`   Available: ${allTemplates.map((t) => t.id).join(', ')}`);
+      process.exit(1);
+    }
+    chosenTemplateId = await chooseTemplateInteractively(allTemplates);
+  } else if (!process.stdout.isTTY && !auto) {
+    logError('❌ --template requires --auto when not running in an interactive terminal.');
+    logError(`   Example: skeletor new ${name} --auto --template ${chosenTemplateId}`);
+    process.exit(1);
+  }
+
+  const templateInfo = allTemplates.find((t) => t.id === chosenTemplateId);
+  if (!templateInfo) {
+    const available = allTemplates.map((t) => t.id).join(', ');
+    logError(`❌ Unknown template "${chosenTemplateId}". Available: ${available}`);
+    process.exit(1);
+  }
+
+  // Owner, description, and confirm — interactive only (--auto uses defaults above)
+  if (isInteractive) {
+    const ownerInput = await p.text({
+      message: 'GitHub owner / org',
+      placeholder: finalOwner,
+      initialValue: finalOwner,
+    });
+    if (p.isCancel(ownerInput)) { p.cancel('Cancelled.'); process.exit(0); }
+    finalOwner = ownerInput || finalOwner;
+
+    const descInput = await p.text({
+      message: 'Project description',
+      placeholder: finalDesc,
+      initialValue: finalDesc,
+    });
+    if (p.isCancel(descInput)) { p.cancel('Cancelled.'); process.exit(0); }
+    finalDesc = descInput || finalDesc;
+
+    const shouldContinue = await p.confirm({
+      message: `Scaffold "${name}" as ${templateInfo.name}?`,
+      initialValue: true,
+    });
+    if (p.isCancel(shouldContinue) || !shouldContinue) {
+      p.cancel('Scaffolding cancelled.');
+      process.exit(0);
+    }
+  }
+
+  const targetDir = path.resolve(process.cwd(), name);
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    logError(`❌ Target directory "${name}" already exists and is not empty.`);
+    process.exit(1);
+  }
+
+  const vars = buildRenderVars({ name, owner: finalOwner, description: finalDesc });
+
+  p.log.info(`Creating "${name}" using ${templateInfo.name}...`);
+
+  copyAndRender(templateInfo.dir, targetDir, vars);
+
+  if (git) {
+    try {
+      execSync('git init -q', { cwd: targetDir, stdio: 'ignore' });
+      execSync('git add -A', { cwd: targetDir, stdio: 'ignore' });
+      execSync('git commit -q -m "chore: initial commit from skeletor"', { cwd: targetDir, stdio: 'ignore' });
+      p.log.success('Git repository initialized');
+    } catch (e) {
+      p.log.warn('Git init skipped (git not available or failed)');
+    }
+  }
+
+  p.outro('✅ Done!');
+
+  console.log(`   cd ${name}`);
+  const suggested = templateInfo.verifyCommands && templateInfo.verifyCommands.length
+    ? templateInfo.verifyCommands[0]
+    : 'Run your language-specific install + test commands';
+  console.log(`   ${suggested}`);
+  console.log('   Then run the other steps from the template manifest (lint, test, etc.)');
+  console.log('\n   Edit AGENTS.md (or equivalent) to customize the AI contract.');
+  console.log('   Happy scaffolding. Your rules, your choice of stack.\n');
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+
+  if (opts.command === 'help' || !opts.command) {
+    log(USAGE.trim());
+    const tmpls = getTemplatesWithManifests();
+    if (tmpls.length) {
+      log('\nAvailable templates:');
+      tmpls.forEach((t) => log(`  • ${t.id} — ${t.name}: ${t.description}`));
+    } else {
+      log('\n(No templates found yet — run from a full skeletor checkout with templates/ )');
+    }
+    process.exit(0);
+  }
+
+  if (opts.command === 'new') {
+    runNew(opts).catch((e) => {
+      logError('❌ Generation failed: ' + (e?.message || e));
+      process.exit(1);
+    });
+  }
+}
+
+// Exports for testing / programmatic use
+export {
+  parseArgs,
+  render,
+  buildRenderVars,
+  sanitizeIdentifierSegment,
+  getAvailableTemplates,
+  getTemplatesWithManifests,
+  loadTemplateManifest,
+  ensureDir,
+  copyAndRender,
+  runNew,
+  USAGE,
+};
+
+const isTestEnv = process.env.SKELETOR_CLI_TEST === '1' || process.env.JEST_WORKER_ID != null;
+if (!isTestEnv) {
+  main();
+}

package/templates/csharp/AGENTS.md

@@ -0,0 +1,10 @@
+# C# Project — Agent Guidelines
+
+**Project:** {{PROJECT_NAME}}
+**Language:** C# (.NET)
+
+- Build: `dotnet build`, test: `dotnet test`.
+- Use modern C# features (records, pattern matching, nullable).
+- Prefer xUnit for tests.
+- Keep Program.cs or entry points minimal.
+- Update this file with any additional .NET conventions.

package/templates/csharp/Program.cs

@@ -0,0 +1,18 @@
+// {{PROJECT_NAME}}
+// {{DESCRIPTION}}
+
+namespace {{NAMESPACE}};
+
+class Program
+{
+    static void Main(string[] args)
+    {
+        var name = args.Length > 0 ? args[0] : "world";
+        Console.WriteLine(Hello(name));
+    }
+
+    public static string Hello(string name)
+    {
+        return $"Hello, {name} from {{PROJECT_NAME}}!";
+    }
+}

package/templates/csharp/ProgramTests.cs

@@ -0,0 +1,12 @@
+using Xunit;
+
+namespace {{NAMESPACE}};
+
+public class ProgramTests
+{
+    [Fact]
+    public void Hello_ReturnsGreeting()
+    {
+        Assert.Equal("Hello, tester from {{PROJECT_NAME}}!", Program.Hello("tester"));
+    }
+}

package/templates/csharp/Project.csproj.tmpl

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <RootNamespace>{{NAMESPACE}}</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
+    <PackageReference Include="xunit" Version="2.6.6" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.6" />
+  </ItemGroup>
+
+</Project>

package/templates/csharp/README.md

@@ -0,0 +1,12 @@
+# {{PROJECT_NAME}}
+
+{{DESCRIPTION}}
+
+## Development
+
+```bash
+dotnet build
+dotnet test
+```
+
+Standard .NET 8 console + xUnit project.

package/templates/csharp/template.json

@@ -0,0 +1,10 @@
+{
+  "id": "csharp",
+  "name": "C# (.NET)",
+  "description": "Standard .NET console project with .csproj, Program.cs, and xUnit tests.",
+  "language": "csharp",
+  "verifyCommands": [
+    "dotnet build",
+    "dotnet test"
+  ]
+}

package/templates/go/AGENTS.md

@@ -0,0 +1,9 @@
+# Go Project — Agent Guidelines
+
+**Project:** {{PROJECT_NAME}}
+**Language:** Go
+
+- Use `go build`, `go test`, `go mod tidy`.
+- Keep packages small and well-tested.
+- Follow standard Go conventions (gofmt, effective go).
+- Update this file + README when standards evolve.

package/templates/go/README.md

@@ -0,0 +1,13 @@
+# {{PROJECT_NAME}}
+
+{{DESCRIPTION}}
+
+## Development
+
+```bash
+go mod tidy
+go build .
+go test ./...
+```
+
+This is a standard Go project scaffold.

package/templates/go/go.mod.tmpl

@@ -0,0 +1,5 @@
+module {{GO_MODULE}}
+
+go 1.22
+
+toolchain go1.22.0

package/templates/go/main.go

@@ -0,0 +1,20 @@
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+// main is the entry point for {{PROJECT_NAME}}.
+func main() {
+	name := "world"
+	if len(os.Args) > 1 {
+		name = os.Args[1]
+	}
+	fmt.Println(hello(name))
+}
+
+// hello returns a greeting. Extracted for easy testing.
+func hello(name string) string {
+	return fmt.Sprintf("Hello, %s from {{PROJECT_NAME}}!", name)
+}