cloneproof 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to Cloneproof will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows semantic versioning while it matures toward a stable API.
+
+## [0.1.0] - 2026-05-11
+
+### Added
+
+- Initial TypeScript CLI package with the `cloneproof` binary.
+- `cloneproof run [target]` command for local paths, GitHub HTTPS URLs, and `org/repo` shorthand.
+- Fresh temporary workspace creation for first-time setup checks.
+- Local repository copy flow that excludes `.git`, dependency folders, build output, and real `.env` files.
+- Remote repository clone flow using `git clone --depth 1`.
+- Node.js detection with npm, pnpm, and Yarn package manager detection.
+- Node install, build, and test command execution.
+- Python, Go, Rust, and generic repository diagnosis.
+- README, env example, runtime pin, and Docker file setup checks.
+- Structured JSON report with scoring, warnings, suggestions, and step details.
+- Human-readable terminal output and Markdown rendering for GitHub job summaries.
+- GitHub composite action.
+- Unit and integration tests.
+- JSON schema for Cloneproof reports.
+- CI workflow for typecheck, tests, build, CLI help, and Cloneproof self-check.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NMSOfficial
+
+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,173 @@
+# cloneproof
+
+**Test your repo like a first-time contributor.**
+
+Cloneproof is CI for first-time setup. It creates a fresh temporary workspace, clones or copies your repository into it, detects the project type, installs dependencies, runs the checks a new contributor would naturally try, and reports whether the repo can go from clone to green.
+
+## Why Cloneproof?
+
+A passing build is not the same thing as a passing fresh clone.
+
+Most CI jobs run inside a repository that already has the right checkout path, cached dependencies, configured secrets, and contributor knowledge baked into scripts or docs. A new contributor starts from a colder place: they clone the repo, install dependencies, discover missing environment variables, wonder which runtime version to use, and try to run tests.
+
+Cloneproof tests that first-time path directly so setup drift becomes visible before someone loses an afternoon to it.
+
+## Installation
+
+Cloneproof is designed to be published to npm later:
+
+```sh
+npm install --save-dev cloneproof
+```
+
+For local development in this repository:
+
+```sh
+npm install
+npm run build
+node dist/cli.js --help
+```
+
+## CLI Usage
+
+```sh
+cloneproof run [target]
+```
+
+`target` can be:
+
+- `.` or another local path
+- a GitHub HTTPS URL such as `https://github.com/org/repo`
+- a GitHub shorthand such as `org/repo`
+
+Examples:
+
+```sh
+cloneproof run .
+cloneproof run NMSOfficial/cloneproof
+cloneproof run https://github.com/NMSOfficial/cloneproof --json
+cloneproof run . --write-report cloneproof-report.json --soft-fail
+```
+
+Options:
+
+```text
+--json                 Print the structured JSON report
+--write-report <path>  Write the JSON report to a file
+--timeout <seconds>    Per-command timeout, default 600
+--soft-fail            Always exit 0 while still reporting failures
+--skip-tests           Do not run detected test commands
+--skip-build           Do not run detected build commands
+--verbose              Print command progress to stderr
+--no-color             Disable colored terminal output
+```
+
+## GitHub Action Usage
+
+Add a workflow such as:
+
+```yaml
+name: Cloneproof
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  cloneproof:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: NMSOfficial/cloneproof@v0.1.0
+        with:
+          target: .
+          write_report: cloneproof-report.json
+```
+
+The action writes a Markdown report to the GitHub job summary and stores the JSON report at the configured path. It intentionally does not post PR comments in v0.1.0.
+
+## Example Report
+
+```text
+Cloneproof report
+
+Target: NMSOfficial/cloneproof
+Fresh clone: failed
+Score: 43/100
+
+Passed:
+- clone
+- detect project
+
+Failed:
+- install: pnpm install --frozen-lockfile failed
+
+Warnings:
+- DATABASE_URL is used but missing from .env.example
+- Node version is not pinned
+
+Suggested fixes:
+1. Add DATABASE_URL to .env.example
+2. Add packageManager to package.json
+3. Pin Node version with .nvmrc or engines.node
+```
+
+The JSON report includes timestamps, duration, detected project types, package manager, steps, warnings, and suggestions.
+
+## JSON Schema
+
+The report format is documented in [`schemas/cloneproof-report.schema.json`](schemas/cloneproof-report.schema.json). Use it to validate reports written by:
+
+```sh
+cloneproof run . --write-report cloneproof-report.json
+```
+
+## Supported Ecosystems
+
+Cloneproof v0.1.0 supports:
+
+- **Node.js**: detects `package.json`, npm, pnpm, and Yarn; installs dependencies; runs `build` and `test` scripts when present.
+- **Python**: detects `pyproject.toml`, `requirements.txt`, and `Pipfile`; installs simple projects; runs `pytest` when tests are present and pytest is installed.
+- **Go**: detects `go.mod`; runs `go mod download` and `go test ./...`.
+- **Rust**: detects `Cargo.toml`; runs `cargo test`.
+- **Generic repositories**: reports that no supported project type was found and suggests adding package metadata or setup instructions.
+
+It also checks for README files, missing `.env.example` entries for Node `process.env.X` usage, runtime version pins, and Docker-related files. Docker services are detected but not started in v0.1.0.
+
+## Roadmap
+
+- Optional service orchestration for Docker Compose.
+- Repository-specific configuration file.
+- Richer framework detection.
+- Dependency cache controls for CI.
+- Pull request annotations and comments.
+- More ecosystems and package managers.
+
+## Launch Kit
+
+Planning to share Cloneproof? See [docs/launch.md](docs/launch.md) for positioning, launch copy, and suggested GitHub repository metadata.
+
+## Contributing
+
+Contributions are welcome. Start by running:
+
+```sh
+npm install
+npm run typecheck
+npm test
+npm run build
+node dist/cli.js run . --soft-fail --verbose
+```
+
+Keep changes focused on helping repositories become easier to clone, install, and verify.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local development and pull request guidance.
+
+## Security
+
+Cloneproof executes install, build, and test commands in a temporary workspace. Review [SECURITY.md](SECURITY.md) before running it on untrusted repositories.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/action.yml

@@ -0,0 +1,108 @@
+name: Cloneproof
+description: Test a repository like a first-time contributor from fresh clone to green.
+author: NMSOfficial
+branding:
+  icon: check-circle
+  color: green
+inputs:
+  target:
+    description: Local path, GitHub HTTPS URL, or org/repo shorthand to test.
+    required: false
+    default: "."
+  soft_fail:
+    description: Always exit successfully while still reporting cloneproof failures.
+    required: false
+    default: "false"
+  skip_tests:
+    description: Skip detected test commands.
+    required: false
+    default: "false"
+  skip_build:
+    description: Skip detected build commands.
+    required: false
+    default: "false"
+  timeout:
+    description: Per-command timeout in seconds.
+    required: false
+    default: "600"
+  write_report:
+    description: Path for the JSON report, relative to the workflow workspace unless absolute.
+    required: false
+    default: cloneproof-report.json
+runs:
+  using: composite
+  steps:
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 20
+    - name: Install action dependencies
+      shell: bash
+      working-directory: ${{ github.action_path }}
+      run: npm ci
+    - name: Build action CLI
+      shell: bash
+      working-directory: ${{ github.action_path }}
+      run: npm run build
+    - name: Run Cloneproof
+      shell: bash
+      working-directory: ${{ github.workspace }}
+      env:
+        INPUT_TARGET: ${{ inputs.target }}
+        INPUT_SOFT_FAIL: ${{ inputs.soft_fail }}
+        INPUT_SKIP_TESTS: ${{ inputs.skip_tests }}
+        INPUT_SKIP_BUILD: ${{ inputs.skip_build }}
+        INPUT_TIMEOUT: ${{ inputs.timeout }}
+        INPUT_WRITE_REPORT: ${{ inputs.write_report }}
+      run: |
+        set +e
+        args=("run" "$INPUT_TARGET" "--write-report" "$INPUT_WRITE_REPORT" "--timeout" "$INPUT_TIMEOUT" "--no-color")
+        if [ "$INPUT_SOFT_FAIL" = "true" ]; then
+          args+=("--soft-fail")
+        fi
+        if [ "$INPUT_SKIP_TESTS" = "true" ]; then
+          args+=("--skip-tests")
+        fi
+        if [ "$INPUT_SKIP_BUILD" = "true" ]; then
+          args+=("--skip-build")
+        fi
+        node "$GITHUB_ACTION_PATH/dist/cli.js" "${args[@]}"
+        status=$?
+        echo "CLONEPROOF_EXIT_CODE=$status" >> "$GITHUB_ENV"
+        exit 0
+    - name: Write job summary
+      if: always()
+      shell: bash
+      working-directory: ${{ github.workspace }}
+      env:
+        INPUT_WRITE_REPORT: ${{ inputs.write_report }}
+      run: |
+        node --input-type=module <<'NODE'
+        import { appendFileSync, existsSync, readFileSync } from "node:fs";
+        import { isAbsolute, resolve } from "node:path";
+        import { pathToFileURL } from "node:url";
+
+        const reportPath = isAbsolute(process.env.INPUT_WRITE_REPORT)
+          ? process.env.INPUT_WRITE_REPORT
+          : resolve(process.env.GITHUB_WORKSPACE, process.env.INPUT_WRITE_REPORT);
+
+        if (!existsSync(reportPath)) {
+          appendFileSync(process.env.GITHUB_STEP_SUMMARY, "## Cloneproof report\n\nNo report file was produced.\n");
+          process.exit(0);
+        }
+
+        const report = JSON.parse(readFileSync(reportPath, "utf8"));
+        const moduleUrl = pathToFileURL(`${process.env.GITHUB_ACTION_PATH}/dist/index.js`).href;
+        const { renderMarkdownReport } = await import(moduleUrl);
+        appendFileSync(process.env.GITHUB_STEP_SUMMARY, renderMarkdownReport(report));
+        NODE
+    - name: Enforce Cloneproof result
+      if: always()
+      shell: bash
+      env:
+        INPUT_SOFT_FAIL: ${{ inputs.soft_fail }}
+      run: |
+        if [ "$INPUT_SOFT_FAIL" = "true" ]; then
+          exit 0
+        fi
+        exit "${CLONEPROOF_EXIT_CODE:-1}"

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node