skeleton-framework 0.1.0__tar.gz

skeleton_framework-0.1.0/LICENSE

@@ -0,0 +1,146 @@
+# Skeleton Framework Proprietary Licence
+
+**Copyright © 2026 lambdadotjoburg. All rights reserved.**
+
+This licence applies to Skeleton Framework, including its original source code,
+framework components, documentation, templates, configuration files,
+and associated materials owned by the copyright holder (collectively, the "Software").
+
+By accessing, downloading, installing, or using the Software, you acknowledge the terms of this licence.
+
+## 1. Ownership and Copyright
+
+The Software is proprietary software. All copyright and other intellectual property rights
+in the Software remain with the copyright holder, except for third-party materials governed
+by their respective licences.
+
+No ownership rights are transferred to any user by this licence.
+All rights not expressly granted are reserved by the copyright holder.
+
+## 2. Permitted Personal and Educational Use
+
+Subject to the terms of this licence, the copyright holder grants individuals a limited,
+non-exclusive, non-transferable, revocable licence to access and use the Software solely
+for personal learning, educational activities, experimentation, and non-commercial evaluation.
+
+This permission includes running the Software and making modifications reasonably necessary
+for the permitted non-commercial purposes, provided that the Software or modifications are
+not used for commercial purposes or redistributed without written permission.
+
+This permission does not grant any right to commercially deploy, sell, sublicense,
+distribute, or provide the Software as part of a commercial product or service.
+
+## 3. Commercial Use Requires a Paid Licence
+
+Commercial use is not permitted under the free personal and educational licence.
+
+Any commercial use requires a separate written commercial licence issued by
+the copyright holder and payment of the applicable licence fees, as specified in that agreement.
+
+Commercial use includes, without limitation:
+
+- Using the Software in a business, commercial product, or revenue-generating service.
+- Deploying the Software for a commercial organisation or its customers.
+- Incorporating the Software into a product or service offered for sale or commercial advantage.
+- Providing access to the Software or a framework-based service as part of a paid offering.
+
+The copyright holder may offer different commercial licence terms, fees,
+usage limits, and support arrangements under separate written agreements.
+
+## 4. Modification
+
+Modification is permitted only within the scope of an applicable licence.
+
+Users operating under the free personal and educational licence may modify
+the Software solely for the permitted non-commercial purposes described in Section 2.
+
+Commercial modifications, modifications outside the permitted scope,
+and any other use not expressly authorised by this licence require
+separate written permission or an applicable commercial licence.
+
+Modifications do not transfer ownership of the original Software to
+the person making them. Ownership and licensing of independently created
+modifications will be determined by applicable law and any separate written agreement.
+
+## 5. Redistribution and Sublicensing
+
+Redistribution of the Software, in source-code or compiled form, requires the copyright holder's prior written permission.
+
+Without that permission, you may not:
+
+- Republish or distribute copies of the Software.
+- Bundle or redistribute the Software with another product or package.
+- Mirror or host copies of the Software for third-party distribution.
+- Sublicense, sell, rent, lease, or otherwise transfer rights to the Software.
+- Distribute modified versions of the Software.
+
+Access to a public repository or package registry does not, by itself, grant permission to redistribute the Software.
+
+## 6. Contributions
+
+No contribution transfers copyright ownership to the copyright holder merely because it is submitted.
+
+Contributions intended for inclusion in the Software must be accompanied by a separate written agreement,
+or other expressly accepted contribution terms, establishing the rights necessary for the copyright holder
+to use, modify, distribute, and license the contribution as intended.
+
+Contributors remain responsible for ensuring they have the rights necessary to submit their contributions.
+
+## 7. Third-Party Components
+
+The Software may include or depend on third-party software, packages, libraries, or other materials.
+
+Such components remain subject to their own applicable licences.
+This licence does not override third-party licence obligations
+or grant rights that the copyright holder does not possess.
+
+Users are responsible for complying with applicable third-party licence terms.
+
+## 8. Restrictions
+
+Except as expressly authorised by this licence or applicable law,
+you may not use the Software outside the scope of the permissions granted,
+remove or misrepresent copyright notices, or claim ownership of the original Software.
+
+Nothing in this licence excludes rights that cannot lawfully be excluded or restricted under applicable law.
+
+## 9. Termination
+
+Permission under this licence terminates automatically if you materially breach its terms.
+Upon termination, you must cease the use that is no longer authorised and comply with applicable legal obligations.
+
+Termination does not extinguish rights or obligations that have accrued before termination or provisions that by their nature continue to apply.
+
+## 10. Disclaimer of Warranty
+
+To the maximum extent permitted by applicable law, the Software is provided "AS IS"
+and without warranties of any kind, whether express or implied, including warranties
+of merchantability, fitness for a particular purpose, and non-infringement.
+
+The copyright holder does not guarantee that the Software will be error-free, secure, uninterrupted, or suitable for any particular purpose.
+
+## 11. Limitation of Liability
+
+To the maximum extent permitted by applicable law, the copyright holder
+will not be liable for indirect, incidental, special, consequential,
+or exemplary damages arising from the use of, or inability to use, the Software.
+
+Nothing in this section excludes or limits liability that cannot lawfully be excluded or limited.
+
+## 12. Commercial Licensing and Contact
+
+For commercial licensing, written permissions, redistribution requests, or contribution agreements, contact:
+
+**Copyright holder:** lambdadotjoburg
+**Email:** lambdadotjoburg@gmail.com
+
+No commercial licence or redistribution permission is granted unless expressly agreed in writing by the copyright holder.
+
+## 13. Governing Law
+
+The governing law and jurisdiction for this licence should be specified
+in a separate written agreement or, where applicable, determined under applicable law.
+
+---
+
+**All rights reserved.**

skeleton_framework-0.1.0/PKG-INFO

@@ -0,0 +1,440 @@
+Metadata-Version: 2.4
+Name: skeleton-framework
+Version: 0.1.0
+Summary: A full-stack app framework: Python orchestration + FastAPI + WebPack frontend.
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: uvicorn
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Requires-Dist: watchfiles
+Dynamic: license-file
+
+# Skeleton Framework
+
+<img width="200px" src ="./skeleton.png"/>
+
+Skeleton is a full-stack application framework that combines Python orchestration, a FastAPI reverse-proxy gateway, a Python backend, and a TypeScript frontend.
+
+It provides a structured development workflow for configuring, initializing, installing, running, and building full-stack applications.
+
+## Features
+
+- **Python orchestration** for application setup and service execution.
+- **FastAPI gateway** for centralized request routing and communication with backend services.
+- **Python backend** for application APIs.
+- **TypeScript frontend** with React and Webpack tooling.
+- **Configurable project structure** through JSON configuration files.
+- **Separate environments** for framework development and client application dependencies.
+- **Command-line tooling** for initialization, development, building, and cleanup.
+
+## Architecture
+
+Skeleton separates the application into cooperating layers:
+
+| Layer | Technology |
+|---|---|
+| Orchestration and CLI | Python |
+| Gateway and backend APIs | FastAPI |
+| HTTP server | Uvicorn |
+| HTTP communication | HTTPX |
+| Frontend | TypeScript and React |
+| Frontend bundling | Webpack |
+| Development file watching | watchfiles |
+| Dependency management | pip and npm |
+
+The gateway provides a central entry point for browser requests and coordinates communication between the frontend and backend.
+
+## Requirements
+
+Before getting started, install:
+
+- Python 3.11 or later.
+- Node.js and npm.
+- pip, included with standard Python installations.
+
+## Installation
+
+Install Skeleton from PyPI:
+
+```bash
+python -m pip install skeleton-framework
+```
+
+The installed Python distribution provides the `skeleton` command.
+
+## Quickstart
+
+Create or enter an empty directory for your application:
+
+```bash
+mkdir my-app
+cd my-app
+```
+
+Configure the project, initialize its files, and install its dependencies:
+
+```bash
+skeleton --quickstart
+```
+
+This combines the configuration, initialization, and installation stages.
+
+To run the application:
+
+```bash
+skeleton --start
+```
+
+Follow the terminal output for service startup information and open the application at the configured local address.
+
+## Client project workflow
+
+Skeleton also exposes the individual stages when you want to configure the application before installing dependencies.
+
+### 1. Generate configuration
+
+```bash
+skeleton --config
+```
+
+This generates the project's configuration files:
+
+- `skeleton-layout.json` — defines the application layout.
+- `skeleton-dependencies.json` — declares frontend and backend dependencies.
+- `skeleton-schemas.json` — provides schema configuration.
+- `skeleton-servers.json` — defines server configuration.
+- `.gitignore` — establishes ignore rules for generated files.
+
+Review and customize these files before initialization if necessary.
+
+### 2. Initialize the project
+
+```bash
+skeleton --init
+```
+
+Initialization creates the configured frontend and backend structure from the framework's templates, prepares dependency manifests, and configures the local frontend tooling packages.
+
+### 3. Install dependencies
+
+```bash
+skeleton --install
+```
+
+This installs frontend dependencies using npm and backend Python dependencies into the backend's `.venv` environment.
+
+### 4. Start services
+
+```bash
+skeleton --start
+```
+
+You can also explicitly select services:
+
+```bash
+skeleton --start frontend gateway packages --open
+```
+
+The selected services and runtime options determine which processes are started.
+
+## Frontend commands
+
+Run these commands from the client project root:
+
+| Command | Purpose |
+|---|---|
+| `skeleton --serve` | Start the frontend development server. |
+| `skeleton --build` | Build the frontend for distribution. |
+| `skeleton --preview` | Run the configured frontend preview script. |
+| `skeleton --clean` | Remove generated frontend build artifacts. |
+| `skeleton --purge` | Remove frontend build artifacts and disposable development dependencies. |
+
+These commands invoke the corresponding scripts defined in the configured frontend directory's `package.json`.
+
+## Default development ports
+
+The default development configuration uses the following ports:
+
+| Service | Address |
+|---|---|
+| Gateway / reverse proxy | `http://127.0.0.1:8000` |
+| Backend API | `http://127.0.0.1:8080` |
+| Frontend development server | `http://127.0.0.1:3000` |
+
+The gateway is the normal entry point for browser access.
+
+For example, the test API endpoint can be accessed through:
+
+```text
+http://127.0.0.1:8000/api/test
+```
+
+The corresponding backend endpoint may be available directly at:
+
+```text
+http://127.0.0.1:8080/test
+```
+
+Actual routes depend on the application's server and gateway configuration.
+
+## Project structure
+
+A generated client project follows the configured layout. A typical structure is:
+
+```text
+my-app/
+├── skeleton-layout.json
+├── skeleton-dependencies.json
+├── skeleton-schemas.json
+├── skeleton-servers.json
+├── frontend/
+├── backend/
+└── .skeleton/
+```
+
+The frontend contains the TypeScript application and its npm tooling. The backend contains the Python application and its own virtual environment. The `.skeleton/` directory holds local framework tooling and generated assets.
+
+The exact structure depends on the project's configuration.
+
+## Cleanup
+
+Run `skeleton --clean` to remove generated frontend build outputs.
+
+Run `skeleton --purge` when you want to remove the generated build outputs and disposable frontend development dependencies.
+
+**Warning:** Purging is destructive. It may remove `node_modules`, lockfiles, and generated local tooling artifacts. Dependencies may need to be installed again.
+
+## Troubleshooting
+
+### The command is not found
+
+Confirm that Skeleton is installed in the Python environment whose scripts directory is available on your terminal's `PATH`.
+
+```bash
+python -m pip show skeleton-framework
+```
+
+### Frontend or backend dependencies are missing
+
+From the client project root, run:
+
+```bash
+skeleton --install
+```
+
+If the project has not yet been initialized, run `skeleton --init` first.
+
+### Application startup fails
+
+Check that:
+
+- The project has been configured and initialized.
+- Dependencies have been installed.
+- The selected services are included in the startup command.
+- The required ports are available.
+- The server configuration matches the configured project layout.
+
+### Framework tooling packages are missing
+
+If working directly from the framework source repository, run the framework's packaging command before initializing a client project:
+
+```bash
+python run.py --pack
+```
+
+## Framework development
+
+These commands are intended for contributors working in the Skeleton framework source repository, not ordinary client projects.
+
+Initialize the framework development environment:
+
+```bash
+python run.py --bootstrap
+```
+
+Prepare the framework's distributable tooling packages:
+
+```bash
+python run.py --pack
+```
+
+Build the Python distribution:
+
+```bash
+python run.py --build
+```
+
+Additional development and cleanup commands are available:
+
+```bash
+python run.py --init
+python run.py --install
+python run.py --clean
+python run.py --purge
+```
+
+The framework's Python development environment and root `requirements.txt` are separate from the environments created for client applications.
+
+## Project status
+
+Skeleton is an experimental framework under active development. Its goal is to provide a clear, reproducible foundation for full-stack application development while keeping configuration, orchestration, frontend tooling, and backend services independently manageable.
+
+## Framework development
+
+These commands are intended for contributors working in the Skeleton framework source repository, not ordinary client projects.
+
+### Initialize the framework development environment
+
+```bash
+python run.py --bootstrap
+```
+
+This combines `--init` and `--install` to initialize and install the framework's development environment.
+
+### Build the framework distribution
+
+```bash
+python run.py --dist
+```
+
+This combines `--pack` and `--build`. It prepares the distributable tooling packages and builds the Python distribution in `dist/`.
+
+### Cleanup
+
+```bash
+python run.py --clean
+python run.py --purge
+```
+
+The framework's Python development environment and root `requirements.txt` are preserved by framework cleanup.
+
+## Framework Developer: Testing a Local Installation
+
+Use this workflow to test the locally built `skeleton-framework` distribution in a separate client project. This verifies that the installed package works independently of the framework source repository.
+
+### 1. Build the distribution
+
+From the framework repository root:
+
+```bash
+python run.py --dist
+```
+
+The generated wheel will be located in the framework's `dist/` directory.
+
+### 2. Create a separate test project
+
+From the framework repository root, create a sibling directory outside the framework source tree:
+
+```bash
+mkdir -p ../skeleton-test-project
+cd ../skeleton-test-project
+```
+
+### 3. Create and activate the test environment
+
+```bash
+python -m venv .venv
+source .venv/Scripts/activate
+```
+
+On macOS or Linux, use:
+
+```bash
+source .venv/bin/activate
+```
+
+### 4. Install the locally built wheel
+
+From the test project directory:
+
+```bash
+python -m pip install --force-reinstall ../framework/dist/skeleton_framework-0.1.0-py3-none-any.whl
+```
+
+Adjust the relative path, wheel filename, and version to match your framework checkout and build output.
+
+The `--force-reinstall` option reinstalls the wheel even if that version is already present. `--no-deps` prevents pip from reinstalling the package's dependencies; use this option when those dependencies are already available in the environment. Otherwise, omit `--no-deps`.
+
+### 5. Verify the installation
+
+```bash
+python -m pip show skeleton-framework
+python -m pip show -f skeleton-framework
+```
+
+The first command displays the installed distribution's metadata. The second lists its installed files.
+
+### 6. Test the installed CLI
+
+From the test project root, run the complete client setup:
+
+```bash
+skeleton --quickstart
+```
+
+Then start the application:
+
+```bash
+skeleton --start
+```
+
+Alternatively, test the individual setup stages:
+
+```bash
+skeleton --config
+skeleton --init
+skeleton --install
+skeleton --start
+```
+
+You can also test the remaining client commands:
+
+```bash
+skeleton --serve
+skeleton --build
+skeleton --preview
+skeleton --clean
+skeleton --purge
+```
+
+### 7. Test framework changes
+
+Whenever you modify the framework, rebuild the distribution from the framework repository:
+
+```bash
+python run.py --dist
+```
+
+Then reinstall the newly built wheel in the test project's virtual environment using the installation command above.
+
+This workflow lets you test packaging, bundled tooling, configuration files, templates,
+and CLI behavior without running the client project directly from the framework source tree.
+
+**Important:**
+The framework development environment and the test project's `.venv` are independent.
+Install the locally built wheel into the test environment, and run the client commands
+from the test project directory.
+
+## Licence
+
+Skeleton Framework is proprietary software. Copyright © 2026 lambdadotjoburg. All rights reserved.
+
+The source code is publicly available for inspection, but public availability
+does not grant unrestricted rights to use, modify, or redistribute the framework.
+
+Personal learning, educational activities, and non-commercial experimentation are permitted
+under the terms of the root [LICENSE](./LICENSE) file.
+
+Commercial use requires a separate paid licence from the copyright holder.
+Redistribution requires prior written permission.
+
+Third-party dependencies remain subject to their respective licences.
+
+For commercial licensing, redistribution requests, or other permissions,
+contact [lambdadotjoburg@gmail.com](mailto:lambdadotjoburg@gmail.com).
+
+See the [LICENSE](./LICENSE) file for the complete terms.