shipcraft 0.0.0-stage → 2.16.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# Shipcraft
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A seatbelt for test-driven development with coding agents.**
+
+Code is cheap now. Judgment isn't. Shipcraft makes sure the judgment you put into a test can't be quietly undone by the code that is supposed to satisfy it, and it stays out of the way the rest of the time.
+
+```text
+$ git commit -m "fix rounding"
+shipcraft refused: locked test tests/test_invoice.py changed after RED (index)
+Why: RED is the contract: GREEN changes the code, not the test that judges it
+Next: undo the change in tests/test_invoice.py; if the test looks wrong, stop and tell the RED author
+```
+
+---
+
+## Why
+
+A coding agent asked to make a failing test pass has two ways to do it: fix the code, or "fix" the test. Most of the time it fixes the code. Sometimes, under pressure from a hard bug, a confusing assertion or a long session, it edits the assertion, skips the case, deletes the file, or changes the runner config so the suite goes green. Every one of those looks like progress in the diff summary.
+
+Prose rules in `AGENTS.md` ("never edit the tests") help, but nothing enforces them. Shipcraft turns that rule into a mechanical check that runs where agents can't argue with it: in the git hook and again in CI.
+
+## How it works
+
+Work is split into two roles, and they should be different agents (or an agent and you):
+
+- **RED** writes the tests that describe the change and runs `shipcraft red`. Shipcraft runs the suite, requires it to **fail on assertions**, and writes a **lock** with a hash of every test file, the config and the failing cases. The lock is committed with the tests.
+- **GREEN** writes the code. While the lock is open, any commit that changes, deletes or skips a locked test, or touches the config, is refused. The first commit where every locked case passes **closes the lock by itself**.
+
+```mermaid
+flowchart LR
+    A[RED writes tests] --> B["shipcraft red<br/>suite must fail"]
+    B --> C[lock committed: open]
+    C --> D[GREEN writes code]
+    D --> E{git commit}
+    E -- locked test changed --> F[refused, 3 lines]
+    F --> D
+    E -- locked cases still red --> D
+    E -- all locked cases pass --> G[lock closes in a commit right after]
+    G --> H["shipcraft pr<br/>CI + review"]
+    H --> I["shipcraft merge"]
+```
+
+The hook only runs the locked cases, so commits stay fast. `shipcraft ci` then repeats every check on every commit of the branch, from a clean checkout, and runs the full suite. A commit made with `--no-verify` or with an edited hook is caught there.
+
+Every refusal is three lines: **what happened, why it matters, and the next step**. Most "Next" lines contain the exact command to run, so an agent that has never heard of Shipcraft can recover on its own.
+
+## What it guarantees, and what it doesn't
+
+**It guarantees** that a branch cannot reach your main through `shipcraft merge` (or through required status checks on GitHub) if any commit changed, removed or skipped a test that was locked at RED, or changed the config that decides how tests run, while the lock was open.
+
+**The threat model is the honest agent that makes mistakes or takes shortcuts.** It is not an adversary rewriting Shipcraft itself. Shipcraft does not sandbox anything, and a determined human with admin rights can always merge around it. When that happens, `shipcraft ci` on main reports the merges that skipped the gate.
+
+**It does not judge whether your tests are good.** That's the RED's job, and the review layer's. Shipcraft protects the judgment once it has been made.
+
+## Quick start
+
+```bash
+# A Node/TypeScript project (macOS): pin Shipcraft in the project, like any dev dependency
+pnpm add -D shipcraft          # or: npm i -D shipcraft
+pnpm exec shipcraft init       # the hooks call this project's install
+
+# macOS (Apple silicon or Intel), any language: the latest release, checksum-verified, into ~/.local/bin
+gh repo clone victorassisalves/shipcraft && bash shipcraft/install.sh
+
+# or build from source (macOS or Linux, Rust toolchain)
+git clone https://github.com/victorassisalves/shipcraft && cd shipcraft
+cargo install --path nucleo
+```
+
+`install.sh --version <v>` pins a version and `install.sh --uninstall` removes the binary. It needs `gh` logged in.
+
+Then, in your project:
+
+```bash
+shipcraft init          # detects the language, writes .shipcraft.toml, wires the hook
+git add .shipcraft.toml && git commit -m "add shipcraft"
+```
+
+A cycle:
+
+```bash
+# RED: write the failing tests, then lock them
+shipcraft red
+git add -A && git commit -m "red: invoice rounding"
+
+# GREEN: write the code; commit as often as you like
+git commit -am "fix rounding"      # the lock closes on the first fully green commit
+
+# open the PR: CI and review run, and their statuses are published
+shipcraft pr --title "Invoice rounding"
+
+# merge only when both are green
+shipcraft merge 42
+```
+
+`shipcraft status` shows the open locks and how protected the repository really is.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `shipcraft init [--lang python\|node\|go] [--github]` | Detects the language and test runner, writes `.shipcraft.toml`, and wires the hook into your hook manager. |
+| `shipcraft --version` | Prints the version and build commit. |
+| `shipcraft red` | Runs the suite, requires assertion failures, and writes the lock in `.shipcraft/locks/<id>.json`. |
+| `shipcraft check [--commit-msg <file>]` | Called by the hook. Judges the commit being made against open locks and closes a lock when its cases pass. |
+| `shipcraft close` | Closes a lock in its own commit; the post-commit hook runs it, and you can run it by hand. |
+| `shipcraft ci --base <ref> [--pr]` | Re-checks every commit in `<ref>..HEAD` and runs the full suite on HEAD. Runs locally or in GitHub Actions. |
+| `shipcraft pr [--title <t>] [--body <file>]` | Pushes the branch, opens or updates the PR, runs CI and review, and publishes the `shipcraft/ci` and `shipcraft/review` statuses. |
+| `shipcraft review [--pr <n>]` | Runs the review on the local HEAD (to catch blockers before opening the PR) or on any PR. |
+| `shipcraft merge <pr> [--no-review "<reason>"]` | Merges only when CI and review are green on the PR's head. `--no-review "<reason>"` is the recorded way out, and the reason shows up in the PR and in the numbers. |
+| `shipcraft status` | The open locks, and how protected the repository really is (branch protection or only `shipcraft merge`). |
+
+## Languages, runners and hook managers
+
+| | Supported |
+|---|---|
+| Languages | Python, TypeScript/JavaScript, Go, and any runner that writes JUnit XML through a generic suite |
+| Runners | pytest, vitest, jest, `go test` / gotestsum, anything else via `[[suite]]` |
+| Hook managers | plain git hooks, lefthook, husky, pre-commit |
+| Repositories | single package or monorepo (several `[[suite]]` entries), TypeScript project references (`[build]`) |
+| CI | local (on your machine, no runner needed) or GitHub Actions |
+| Review | a separate agent session: Codex, Claude or Gemini CLI |
+
+When `init` finds a hook manager, it integrates with it instead of overwriting it. Shipcraft never edits your test files, your runner config or your existing hooks.
+
+## Configuration
+
+`shipcraft init` writes `.shipcraft.toml`. In `command`, `{junit}` is replaced by the path where the runner writes its JUnit report. A typical file:
+
+```toml
+shipcraft_min = "2.0"
+
+[[suite]]
+name = "api"
+root = "packages/api"
+command = "npx --no -- vitest run --reporter=junit --outputFile={junit}"
+globs = ["**/*.test.ts", "vitest.config.*"]
+
+[execution]
+ci = "local"        # local | github | off
+review = "local"    # local | off
+
+[roles]
+review = "codex"    # codex | claude | gemini
+```
+
+Two rules keep the config honest:
+
+- **The config is part of the lock.** It can't change while a lock is open.
+- **A PR is judged by the config on the base branch,** not by its own. A PR can't switch off its own review.
+
+**Adding a package with a new suite.** Once the base branch has a `.shipcraft.toml`, a `[[suite]]` added in the same PR as its first tests doesn't run in CI, and `shipcraft ci` refuses its locked cases as missing. Bring the suite first, in a PR of its own: the package, its `[[suite]]` entry and one passing test. Once that's merged, rebase and write the RED. `shipcraft red` warns when changed test files match no suite's globs, or when the lock has cases in a suite the base doesn't have.
+
+A layer that is switched off is labeled "off in .shipcraft.toml" on every PR, so nobody mistakes it for a check that ran.
+
+## The layers
+
+| Layer | When it runs | What it catches |
+|---|---|---|
+| Hook | every commit | edits to locked tests or config, skipped or missing cases; closes the lock when green |
+| CI | every PR | everything the hook checks, on every commit, from a clean checkout, plus the full suite |
+| Review | every PR, after CI is green | a different agent reads the diff against the spec and the PR body, and runs its own checks. A blocker counts only if the reviewer reproduced it and it breaks a quoted spec rule or crashes. Errors, timeouts and quota failures are never an approval. |
+| Merge gate | `shipcraft merge` | refuses unless CI and review are green on the PR head |
+
+A PR that changes only docs (a `*.md` at the root, or anything under `docs/`) still gets every commit checked, but skips the build and the suites, so specs and docs reach main in seconds. Any doubt, such as a Markdown file a suite reads as a test, runs everything.
+
+On a public repository (or a paid GitHub plan), `shipcraft init --github` also marks both statuses as required, so the platform enforces the gate too.
+
+## Measured, not asserted
+
+Shipcraft records every hook, CI and review run in `.git/shipcraft/runs.jsonl`: layer, result, refusal code and time. Nothing is sent anywhere. `shipcraft pr` puts the branch's numbers in the PR summary. `shipcraft report` reads the same log and gives, per lock, the times from RED to close and to merge, with daily runs, refusals and hook times (`--json` for scripts).
+
+Every rule in Shipcraft has to pay for itself. It ships with the metric that justifies it and the condition that removes it. Rules that don't catch anything in practice get deleted.
+
+## Working with coding agents
+
+Agents don't need a plugin, an MCP server or a skill. They find Shipcraft the same way they find every other project constraint:
+
+- `git commit` runs the hook, and refusals say exactly what to do next;
+- `shipcraft init` writes a short block in `AGENTS.md` that tells agents to run `shipcraft red` after writing tests. In our trials (four runs per arm, a small sample) this took agents from 0/4 to 4/4 running `shipcraft red` before the first commit.
+
+Give the RED and the GREEN to different sessions. They can be the same model; separate context is what matters.
+
+## Status and limits
+
+Shipcraft 2 is a rewrite of an earlier internal version, built and measured in public from here on.
+
+- **Binaries:** prebuilt for macOS (Apple silicon and Intel) through `install.sh`; on Linux, build from source with `cargo install --path nucleo`.
+- **Windows:** not supported.
+- **Fork PRs** are refused by the local review. The good-faith model doesn't hold for code from outside.
+- **Not yet:** a hosted review layer (`review = "github"`), and other CI providers.
+
+## Development
+
+```bash
+cargo build --release --manifest-path nucleo/Cargo.toml -j 4
+bash acceptance/run.sh nucleo/target/release/shipcraft all   # the full acceptance battery
+```
+
+Shipcraft is developed with Shipcraft: specs in `docs/`, RED and GREEN by separate agents, and every change gated by the battery and a review.
+
+## License
+
+[Apache License 2.0](LICENSE)

package/bin/shipcraft.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// The `shipcraft` command of the npm package: runs the native binary from the
+// platform package npm or pnpm installed next to it (optionalDependencies).
+'use strict';
+const { spawnSync } = require('child_process');
+
+const pkg = `shipcraft-${process.platform}-${process.arch}`;
+let bin;
+try {
+  bin = require.resolve(`${pkg}/bin/shipcraft`);
+} catch {
+  console.error(
+    `shipcraft: no binary for ${process.platform}-${process.arch} (package ${pkg} is not installed).\n` +
+      'Packages exist for macOS (darwin-arm64, darwin-x64); elsewhere build from source: ' +
+      'https://github.com/victorassisalves/shipcraft#quick-start'
+  );
+  process.exit(2);
+}
+const run = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });
+if (run.error) {
+  console.error(`shipcraft: could not run ${bin}: ${run.error.message}`);
+  process.exit(2);
+}
+if (run.signal) process.kill(process.pid, run.signal);
+process.exit(run.status === null ? 1 : run.status);

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "shipcraft",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.16.0",
+  "description": "A seatbelt for test-driven development with coding agents: locks the tests at RED so GREEN cannot quietly undo them.",
+  "license": "Apache-2.0",
+  "repository": { "type": "git", "url": "git+https://github.com/victorassisalves/shipcraft.git" },
+  "homepage": "https://github.com/victorassisalves/shipcraft",
+  "keywords": ["tdd", "testing", "git-hooks", "coding-agents", "ci"],
+  "bin": { "shipcraft": "bin/shipcraft.js" },
+  "files": ["bin/shipcraft.js", "LICENSE", "README.md"],
+  "engines": { "node": ">=18" },
+  "optionalDependencies": {
+    "shipcraft-darwin-arm64": "2.16.0",
+    "shipcraft-darwin-x64": "2.16.0"
+  }
+}