spec-spine 0.1.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 2026 The spec-spine Authors
+
+   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

@@ -0,0 +1,75 @@
+# spec-spine (npm)
+
+**The [`spec-spine`](https://github.com/bartekus/spec-spine) CLI, distributed as a
+prebuilt binary through npm. No Rust toolchain required.**
+
+spec-spine turns a markdown spec corpus into a deterministic, hash-verifiable
+authority ledger and refuses code that drifts from its owning spec at PR time.
+This package lets a TypeScript/JS repo install and run the CLI like any other dev
+tool.
+
+```sh
+npm i -D spec-spine
+npx spec-spine --version
+```
+
+```sh
+npx spec-spine init                                  # scaffold a spec corpus
+npx spec-spine compile                               # specs/*/spec.md -> registry.json
+npx spec-spine index                                 # codebase index
+npx spec-spine lint --fail-on-warn                   # corpus conformance
+npx spec-spine couple --base origin/main --head HEAD # the PR-time drift gate
+```
+
+Add it to your CI / package scripts like any other binary CLI:
+
+```json
+{
+  "scripts": {
+    "spec:check": "spec-spine compile && spec-spine index check && spec-spine lint --fail-on-warn"
+  }
+}
+```
+
+## How it works
+
+This is a **binary-distribution shim, not a native (napi) addon**. The package's
+`bin` is a tiny Node launcher that resolves the one prebuilt binary matching your
+platform and runs it as a child process, forwarding arguments and the exit code.
+
+The binaries ship as **optional dependencies** (`@spec-spine/cli-<os>-<cpu>`),
+each gated by npm's `os`/`cpu` fields so only the one for your machine is
+installed. There is **no `postinstall` script, no network access at install time,
+and no archive extraction**, so it works under `npm ci --ignore-scripts` and
+fully offline (from a warm cache or a private mirror).
+
+## Supported platforms
+
+| OS | Arch | Notes |
+|---|---|---|
+| macOS | arm64, x64 | |
+| Linux | x64, arm64 | **glibc only** (see below) |
+| Windows | x64 | |
+
+**Linux binaries are glibc, not musl.** On **Alpine** or any musl host the
+launcher refuses with a clear message: use a glibc-based image, or install from
+source with `cargo install spec-spine-cli`. The same applies to any platform
+without a prebuilt binary (Windows on ARM, 32-bit, …).
+
+## Versioning
+
+The npm version equals the binary release tag it ships: `spec-spine@0.1.0` runs
+the binary built from `v0.1.0`. There is no floating range, so a pinned npm
+version always runs a known binary.
+
+## Alternatives (no npm)
+
+```sh
+cargo install spec-spine-cli                                          # from crates.io
+curl -fsSL https://raw.githubusercontent.com/bartekus/spec-spine/main/install.sh | sh
+```
+
+## License
+
+Apache-2.0. See the [repository](https://github.com/bartekus/spec-spine) for full
+documentation, the Rust library API, and the design docs.

package/bin/spec-spine.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+'use strict';
+
+// Spec: specs/007-distribution/spec.md
+//
+// The launcher. Resolves the prebuilt binary for this host (see lib/platform.js)
+// and exec's it, forwarding argv and the child's exit code. It is a pure
+// translation layer: no flags added, no arguments rewritten, nothing printed on
+// the success path. `spec-spine <args>` through npm is identical to the native
+// binary. NOT a native addon; the Rust engine runs as a child process.
+
+const { execFileSync } = require('node:child_process');
+const { resolveBinaryPath } = require('../lib/platform.js');
+
+let binPath;
+try {
+  binPath = resolveBinaryPath();
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  process.exit(1);
+}
+
+try {
+  execFileSync(binPath, process.argv.slice(2), { stdio: 'inherit' });
+} catch (err) {
+  if (typeof err.status === 'number') {
+    process.exit(err.status); // forward the binary's own exit code
+  }
+  if (err.signal) {
+    process.stderr.write(`spec-spine: binary terminated by signal ${err.signal}\n`);
+    process.exit(1);
+  }
+  process.stderr.write(`spec-spine: failed to run binary: ${err.message}\n`);
+  process.exit(1);
+}

package/lib/platform.js

@@ -0,0 +1,122 @@
+'use strict';
+
+// Spec: specs/007-distribution/spec.md
+//
+// The pure (process.platform, process.arch) -> platform-package mapping behind
+// the launcher (bin/spec-spine.js). No I/O on the mapping path, so it is
+// unit-tested directly (test/platform.test.js). Resolution of the installed
+// binary is the one filesystem touch, and it takes injectable seams so the
+// tests stay network- and disk-free.
+
+const path = require('node:path');
+
+// The five supported (platform-arch) targets. This table is one fact shared
+// with release.yml's build matrix and install.sh's detection; keep all three in
+// lockstep (specs/007-distribution/spec.md sec 3.2).
+const SUPPORTED = {
+  'darwin-arm64': '@spec-spine/cli-darwin-arm64',
+  'darwin-x64': '@spec-spine/cli-darwin-x64',
+  'linux-x64': '@spec-spine/cli-linux-x64',
+  'linux-arm64': '@spec-spine/cli-linux-arm64',
+  'win32-x64': '@spec-spine/cli-win32-x64',
+};
+
+class UnsupportedPlatformError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UnsupportedPlatformError';
+  }
+}
+
+// The in-archive binary name: `.exe` on Windows, bare elsewhere (matches the
+// names release.yml stages into each archive).
+function binaryName(platform) {
+  return platform === 'win32' ? 'spec-spine.exe' : 'spec-spine';
+}
+
+// Pure resolution: (platform, arch, { muslLinux }) -> { key, packageName, binaryName }.
+// Throws UnsupportedPlatformError on any host without a prebuilt binary.
+function targetFor(platform, arch, opts = {}) {
+  if (platform === 'linux' && opts.muslLinux === true) {
+    throw new UnsupportedPlatformError(unsupportedMessage(platform, arch, 'musl'));
+  }
+  const key = `${platform}-${arch}`;
+  const packageName = SUPPORTED[key];
+  if (!packageName) {
+    throw new UnsupportedPlatformError(unsupportedMessage(platform, arch));
+  }
+  return { key, packageName, binaryName: binaryName(platform) };
+}
+
+function unsupportedMessage(platform, arch, reason) {
+  const host = reason === 'musl' ? `${platform}-${arch} (musl libc)` : `${platform}-${arch}`;
+  const lines = [
+    `spec-spine: no prebuilt binary for ${host}.`,
+    'Prebuilt binaries cover darwin-arm64, darwin-x64, linux-x64 (glibc),',
+    'linux-arm64 (glibc), and win32-x64. Install from source instead:',
+    '    cargo install spec-spine-cli',
+  ];
+  if (reason === 'musl') {
+    lines.push('(Alpine/musl: use a glibc-based image, or cargo install spec-spine-cli.)');
+  }
+  return lines.join('\n');
+}
+
+function missingPackageMessage(packageName) {
+  return [
+    `spec-spine: the prebuilt binary package '${packageName}' is not installed.`,
+    'It is an optional dependency, so this happens with `npm install --no-optional`,',
+    'on an unsupported platform, or when its download failed.',
+    'Reinstall without --no-optional, or install from source:',
+    '    cargo install spec-spine-cli',
+  ].join('\n');
+}
+
+// Detect a musl (non-glibc) Linux. Returns false off Linux. Uses process.report's
+// glibcVersionRuntime, which is present on glibc and absent on musl. Permissive
+// on error: if we cannot tell, assume glibc and let resolution fail loudly later.
+function isMuslLinux(proc = process) {
+  if (proc.platform !== 'linux') {
+    return false;
+  }
+  try {
+    if (!proc.report || typeof proc.report.getReport !== 'function') {
+      return false; // cannot tell; assume glibc and let resolution fail loudly if wrong
+    }
+    const report = proc.report.getReport();
+    const glibc = report && report.header ? report.header.glibcVersionRuntime : undefined;
+    return !glibc; // report present but no glibc runtime => musl
+  } catch {
+    return false;
+  }
+}
+
+// Resolve the absolute path to the platform binary on this host. `process` and
+// `resolve` are injectable for tests; `resolve` defaults to this module's
+// require.resolve so optional platform packages are found from the main package.
+// Throws UnsupportedPlatformError when the matching optional package is absent.
+function resolveBinaryPath(opts = {}) {
+  const proc = opts.process || process;
+  const resolve = opts.resolve || ((request) => require.resolve(request));
+  const { packageName, binaryName: bin } = targetFor(proc.platform, proc.arch, {
+    muslLinux: isMuslLinux(proc),
+  });
+  let manifest;
+  try {
+    manifest = resolve(`${packageName}/package.json`);
+  } catch {
+    throw new UnsupportedPlatformError(missingPackageMessage(packageName));
+  }
+  return path.join(path.dirname(manifest), 'bin', bin);
+}
+
+module.exports = {
+  SUPPORTED,
+  UnsupportedPlatformError,
+  binaryName,
+  targetFor,
+  unsupportedMessage,
+  missingPackageMessage,
+  isMuslLinux,
+  resolveBinaryPath,
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "spec-spine",
+  "version": "0.1.0",
+  "description": "The spec-spine CLI: compile a markdown spec corpus into a deterministic authority ledger and refuse code that drifts from its owning spec. Ships the prebuilt binary; no Rust toolchain required.",
+  "keywords": [
+    "spec",
+    "specification",
+    "authority",
+    "governance",
+    "coupling",
+    "cli",
+    "rust",
+    "deterministic"
+  ],
+  "homepage": "https://github.com/bartekus/spec-spine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bartekus/spec-spine.git",
+    "directory": "npm"
+  },
+  "bugs": {
+    "url": "https://github.com/bartekus/spec-spine/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "The spec-spine Authors",
+  "type": "commonjs",
+  "bin": {
+    "spec-spine": "bin/spec-spine.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "generate": "node scripts/generate-platform-packages.js",
+    "smoke": "scripts/smoke-test.sh"
+  },
+  "optionalDependencies": {
+    "@spec-spine/cli-darwin-arm64": "0.1.0",
+    "@spec-spine/cli-darwin-x64": "0.1.0",
+    "@spec-spine/cli-linux-x64": "0.1.0",
+    "@spec-spine/cli-linux-arm64": "0.1.0",
+    "@spec-spine/cli-win32-x64": "0.1.0"
+  },
+  "spec-spine": {
+    "spec": "007-distribution"
+  }
+}