@study-lenses/create-package 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @codeschoolinabox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @study-lenses/create-package
+
+[![npm version](https://img.shields.io/npm/v/@study-lenses/create-package.svg)](https://www.npmjs.com/package/@study-lenses/create-package)
+[![CI](https://github.com/codeschoolinabox/sl-create-package/actions/workflows/ci.yml/badge.svg)](https://github.com/codeschoolinabox/sl-create-package/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+> CLI scaffolder that generates new `@study-lenses` packages from the standard template,
+> replacing all placeholders with user-provided values.
+
+## Pedagogical Purpose
+
+**Neutral infrastructure:** This package generates the boilerplate for new `@study-lenses`
+packages. It makes no pedagogical decisions — those belong in the packages it creates.
+
+## Who Is This For
+
+**Primary — Educational tool developers:** Creating new `@study-lenses` packages. Instead
+of forking `sl-starter` and manually finding/replacing ~15 placeholders across 8+ files,
+run one command and get a correct package on first try.
+
+## Install
+
+Not installed as a dependency. Run directly:
+
+```bash
+npm create @study-lenses
+# or
+npx @study-lenses/create-package
+```
+
+## Quick Start
+
+```bash
+npm create @study-lenses
+# Package name (e.g., utils-normalize): utils-normalize
+# Description: Config normalization utilities
+# Author (@codeschoolinabox):
+#
+# Creating @study-lenses/utils-normalize in /path/to/sl-utils-normalize...
+# Done!
+```
+
+The CLI asks three questions, then generates `sl-{name}/` with all files from the
+standard template, all placeholders replaced, git initialized, and dependencies installed.
+
+## Design Principles
+
+### What this package provides
+
+- Generates a complete `@study-lenses` package directory from the standard template
+- Replaces all placeholder tokens (CHANGEME, @study-lenses/CHANGEME, OWNER/REPO, OWNER, REPO, PACKAGE_DESCRIPTION, [YEAR], [NAME])
+- Initializes git and runs `npm install`
+- Validates package name against npm naming rules
+
+### What this package does NOT do
+
+- No `--update` mode (re-generating templates in existing packages is deferred)
+- No interactive file selection (all template files are always generated)
+- No custom template support (uses the single standard template)
+
+## API Reference
+
+Generated from TSDoc comments in source. Run `npm run docs` locally, or see the
+[hosted API docs](https://codeschoolinabox.github.io/sl-create-package/).
+
+## Architecture
+
+The CLI is a three-step pipeline:
+
+1. **Collect Input** (`collect-input.ts`) — collects package name, description, author via readline
+2. **Derive** (`derive-variables.ts`) — computes all template variables from the three answers
+3. **Generate** (`generate.ts`) — walks `templates/` directory, replaces tokens, writes files
+
+Templates are shipped as real files in the `templates/` directory (not embedded strings).
+Token replacement uses `String.prototype.replaceAll()` in a specific order to avoid
+substring collisions (e.g., `@study-lenses/CHANGEME` before bare `CHANGEME`).
+
+See [DEV.md](./DEV.md) for full architecture, conventions, and the TDD workflow.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [DEV.md](./DEV.md).
+
+## License
+
+MIT © 2026 @codeschoolinabox

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@study-lenses/create-package",
+  "version": "0.1.0",
+  "description": "Scaffold new @study-lenses packages from the standard template",
+  "type": "module",
+  "bin": {
+    "create-package": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"**/*.{ts,js,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,md}\"",
+    "type-check": "tsc --noEmit",
+    "validate": "npm run lint && npm run type-check && npm run test",
+    "docs": "typedoc",
+    "prepare": "husky"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "study-lenses",
+    "scaffolder",
+    "create",
+    "template"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codeschoolinabox/sl-create-package"
+  },
+  "author": "@codeschoolinabox",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "lint-staged": {
+    "*.{ts,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/ui": "^2.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-boundaries": "^5.4.0",
+    "eslint-plugin-functional": "^9.0.2",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-security": "^3.0.1",
+    "eslint-plugin-sonarjs": "^3.0.6",
+    "eslint-plugin-unicorn": "^62.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.0.0",
+    "prettier": "^3.0.0",
+    "ts-api-utils": "^2.4.0",
+    "typedoc": "^0.28.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.53.1",
+    "vitest": "^2.0.0"
+  }
+}

package/templates/.editorconfig

@@ -0,0 +1,15 @@
+# EditorConfig - consistent formatting across all editors
+# https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,91 @@
+name: Bug Report
+description: Report a bug
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting a bug. Please fill out the sections below
+        so we can reproduce and fix the issue.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of what the bug is.
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: |
+        Minimal code example that demonstrates the bug.
+        Include the exact code, configuration, and function calls.
+      placeholder: |
+        ```javascript
+        import { trace } from '@study-lenses/CHANGEME';
+
+        const result = trace(...);
+        // Expected: [...]
+        // Actual: [...]
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include error messages if any.
+    validations:
+      required: true
+
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js Version
+      description: "Run `node --version` and paste the output."
+      placeholder: "v22.0.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: package-version
+    attributes:
+      label: Package Version
+      description: "The version from your package.json or `npm ls @study-lenses/CHANGEME`."
+      placeholder: "1.0.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, or information.
+    validations:
+      required: false

package/templates/.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,68 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting an improvement.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: |
+        What problem does this feature solve? Describe the limitation or
+        pain point you are experiencing.
+      placeholder: "I'm trying to [...] but currently [...]"
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: |
+        How do you think this should work? Include API examples if possible.
+      placeholder: |
+        ```javascript
+        // Example of how the feature would be used:
+        const result = doThing({ newOption: true });
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: |
+        What other approaches did you consider? Why is this approach better?
+    validations:
+      required: false
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Feature Scope
+      description: Which part of this package does this affect?
+      options:
+        - API
+        - Core logic
+        - Configuration
+        - Types / TypeScript
+        - Testing
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: |
+        Any other context, examples from other tools, research references, etc.
+    validations:
+      required: false

package/templates/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## Summary
+
+<!-- What does this PR do? 1-3 bullet points. -->
+
+## Changes
+
+<!-- Key files changed and why. -->
+
+## Code Review Checklist
+
+### Automated (ESLint + TypeScript)
+
+- [ ] `npm run validate` passes with no errors
+
+### Manual Review
+
+- [ ] Named function/const, then `export default` at bottom
+- [ ] Direct imports from source files (no barrel imports), always with `.js` extension
+- [ ] Named `function` declarations (arrows only for inline single-expression callbacks)
+- [ ] No `this` keyword, no mutable closures
+- [ ] Default empty object `= {}` on all destructured parameters
+- [ ] Verb-first naming; predicates prefixed with `is`/`has`/`can`/`should`
+- [ ] Tests in `tests/` subdirectory (not alongside source files), `.test.ts` suffix
+- [ ] One assertion per `it`; nested `describe` for grouping
+- [ ] JSDoc on public functions; inline comments explain "why" not "what"
+- [ ] Every modified directory has `README.md`
+- [ ] No future-proofing or "nice-to-haves" beyond what was requested

package/templates/.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      dev-dependencies:
+        dependency-type: development

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

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  pull_request:
+  workflow_dispatch:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run validate

package/templates/.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run docs
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs

package/templates/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [created]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish --provenance

package/templates/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/templates/.prettierrc.json

@@ -0,0 +1,15 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "quoteProps": "as-needed",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "embeddedLanguageFormatting": "auto",
+  "singleAttributePerLine": false
+}

package/templates/.vscode/extensions.json

@@ -0,0 +1,11 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "editorconfig.editorconfig",
+    "vitest.explorer",
+    "streetsidesoftware.code-spell-checker",
+    "yoavbls.pretty-ts-errors"
+  ],
+  "unwantedRecommendations": []
+}

package/templates/.vscode/launch.json

@@ -0,0 +1,34 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Current Test File",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "test", "--", "--reporter=verbose", "${relativeFile}"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen",
+      "skipFiles": ["<node_internals>/**", "**/node_modules/**"]
+    },
+    {
+      "name": "Debug All Tests",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "test"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen",
+      "skipFiles": ["<node_internals>/**", "**/node_modules/**"]
+    },
+    {
+      "name": "Debug Current Script",
+      "type": "node",
+      "request": "launch",
+      "program": "${file}",
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen",
+      "skipFiles": ["<node_internals>/**", "**/node_modules/**"]
+    }
+  ]
+}

package/templates/.vscode/settings.json

@@ -0,0 +1,28 @@
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "editor.rulers": [100],
+  "editor.wordWrap": "bounded",
+  "editor.wordWrapColumn": 100,
+  "editor.tabSize": 2,
+  "editor.insertSpaces": true,
+  "files.eol": "\n",
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true,
+
+  "typescript.preferences.importModuleSpecifierEnding": "js",
+  "typescript.suggest.includeAutomaticOptionalChainCompletions": true,
+  "typescript.updateImportsOnFileMove.enabled": "always",
+
+  "eslint.validate": ["javascript", "typescript"],
+  "eslint.useFlatConfig": true,
+
+  "search.exclude": {
+    "**/dist": true,
+    "**/coverage": true,
+    "**/docs": true
+  }
+}