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

package/README.md

@@ -1,11 +1,144 @@
 # 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 (when running interactively without `--yes`)
+- Confirmation step
+- Proper cancel handling and nice spinners/intro/outro
+
+`--yes` stays fully non-interactive for scripts/CI.
+
+## 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 origin main`
+
+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 shell 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 --owner jml6m
+
+# Non-interactive (CI / scripts)
+npx @jml6m/skeletor new my-service --yes --template go
+```
+
+Common flags:
+- `--template <id>` (javascript, typescript, python, go, rust, java, csharp, ...)
+- `--owner`
+- `--description`
+- `--yes` (skip all prompts)
+- `--no-git`
+
+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 --yes
+
+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.
+
+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 origin main`
+
+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,42 @@
 {
   "name": "@jml6m/skeletor",
-  "version": "0.1.0-alpha.1",
-  "description": "Efficient scaffolding for custom development",
+  "version": "0.1.0-alpha.2",
+  "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"
+  },
+  "files": [
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "keywords": [
+    "scaffolding",
+    "generator",
+    "yeoman",
+    "template",
+    "eslint",
+    "prettier",
+    "knip"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^0.9.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
   "author": "",
-  "license": "ISC"
+  "license": "ISC",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1"
+  }
 }

package/src/index.js

@@ -1,7 +1,318 @@
 #!/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>     Template to use (e.g. javascript, typescript, python)
+                        Omit to choose interactively (or use --yes for default)
+  --owner <user>        GitHub owner/org for release scripts (default: jml6m)
+  --description <text>  Short project description
+  --yes                 Non-interactive, use defaults + first available template
+  --no-git              Skip git init
+
+Examples:
+  skeletor new my-api --template typescript
+  skeletor new my-lib --yes
+  skeletor new my-tool
+`;
+
+
+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
+    owner: 'jml6m',
+    description: 'A new project scaffolded with skeletor.',
+    yes: 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 === '--owner' || a === '-o') result.owner = args[++i] || 'jml6m';
+      else if (a === '--description' || a === '-d') result.description = args[++i] || result.description;
+      else if (a === '--yes' || a === '-y') result.yes = 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;
+}
+
+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 or .git inside templates
+      if (entry === 'node_modules' || entry === '.git') continue;
+      copyAndRender(path.join(src, entry), path.join(dest, entry), 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, isYes) {
+  if (isYes || templates.length === 0) {
+    return templates[0] ? templates[0].id : null;
+  }
+
+  if (!process.stdout.isTTY) {
+    return templates[0] ? templates[0].id : 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: 'Choose a template',
+    options,
+  });
+
+  if (p.isCancel(selected)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  return selected;
+}
+
+async function runNew(opts) {
+  const { name, git, yes } = 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 = opts.owner || 'jml6m';
+  let finalDesc = opts.description || 'A new project scaffolded with skeletor.';
+
+  const isInteractive = !yes && process.stdout.isTTY;
+
+  if (!chosenTemplateId) {
+    chosenTemplateId = await chooseTemplateInteractively(allTemplates, yes);
+  }
+
+  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);
+  }
+
+  // Richer interactive prompts for missing details (only when not --yes)
+  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 repoName = name;
+  const vars = {
+    PROJECT_NAME: name,
+    REPO_OWNER: finalOwner,
+    REPO_NAME: repoName,
+    DESCRIPTION: finalDesc,
+    YEAR: new Date().getFullYear(),
+  };
+
+  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,
+  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 {{PROJECT_NAME | replace('-', '_')}};
+
+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 {{PROJECT_NAME | replace('-', '_')}};
+
+public class ProgramTests
+{
+    [Fact]
+    public void Hello_ReturnsGreeting()
+    {
+        Assert.Equal("Hello, tester from {{PROJECT_NAME}}!", Program.Hello("tester"));
+    }
+}

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/csharp/{{PROJECT_NAME}}.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <RootNamespace>{{PROJECT_NAME | replace('-', '_')}}</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/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

@@ -0,0 +1,5 @@
+module {{PROJECT_NAME}}
+
+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)
+}

package/templates/go/main_test.go

@@ -0,0 +1,11 @@
+package main
+
+import "testing"
+
+func TestHello(t *testing.T) {
+	got := hello("tester")
+	want := "Hello, tester from {{PROJECT_NAME}}!"
+	if got != want {
+		t.Errorf("hello() = %q, want %q", got, want)
+	}
+}

package/templates/go/template.json

@@ -0,0 +1,11 @@
+{
+  "id": "go",
+  "name": "Go",
+  "description": "Standard Go module with go.mod, main package, basic CLI structure, and tests. Uses go test for verification.",
+  "language": "go",
+  "verifyCommands": [
+    "go mod tidy",
+    "go build .",
+    "go test ./..."
+  ]
+}