@goodfoot/git-mesh 1.0.0 → 1.0.16

package/man/git-mesh.1

@@ -0,0 +1,175 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH git-mesh 1  "git-mesh 1.0.13" 
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH NAME
+git\-mesh \- Track implicit semantic dependencies in a git repo.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH SYNOPSIS
+\fBgit\-mesh\fR [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fIsubcommands\fR]
+.SH DESCRIPTION
+.B git mesh
+tracks implicit semantic dependencies in a Git repository: couplings between
+line ranges (or whole files), in code or prose, that no schema, type, or test
+enforces.
+Each
+.B mesh
+anchors the participating ranges and carries a durable
+.I why
+\[em] one prose sentence that names the relationship the anchored ranges hold
+and survives a rewrite of either side.
+.PP
+The standing question at commit time: did this change create or rely on a
+coupling that is not visible from the lines themselves?
+.PP
+.B Writing the why.
+Name the relationship the ranges hold in one prose sentence, written so it
+survives a rewrite of either side.
+Describe the relationship in role\-words (\(lqthe doc,\(rq \(lqthe parser,\(rq
+\(lqthe runbook,\(rq \(lqthe migration\(rq) rather than repeating filenames.
+For asymmetric relationships, name which side is normative:
+\(lqthe doc is the source of truth when they disagree.\(rq
+Do not restate the mesh name, embed incidental implementation details, or
+bundle ownership and review triggers in the why.
+.PP
+.B Re\-anchoring on drift.
+When
+.B git mesh stale
+reports drift, review the change at each anchor.
+If the relationship still holds, re-anchor with
+.B git mesh add
+and commit.
+If the relationship has changed, update the why with
+.B git mesh why
+before re-anchoring.
+.PP
+Meshes are stored as Git refs under
+.IR refs/meshes/v1/<name> ,
+so they travel with
+.B git fetch
+and
+.B git push
+like branches and tags.
+.B git mesh fetch
+and
+.B git mesh push
+keep remote mirrors in sync.
+.PP
+Bare invocations:
+.RS 4
+.TP
+.B git mesh
+List every mesh in the repository.
+.TP
+.BI git\ mesh\  <name>
+Show one mesh (ranges, why, config).
+.RE
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH SUBCOMMANDS
+.TP
+git\-mesh\-ls(1)
+List files and ranges currently tracked by a mesh
+.TP
+git\-mesh\-stale(1)
+Report ranges whose content has drifted from their anchored state
+.TP
+git\-mesh\-add(1)
+Stage ranges to add on the next mesh commit
+.TP
+git\-mesh\-rm(1)
+Stage ranges to remove on the next mesh commit
+.TP
+git\-mesh\-why(1)
+Read or stage the mesh\*(Aqs why — the durable one\-sentence definition of the relationship the anchored ranges hold
+.TP
+git\-mesh\-commit(1)
+Resolve staged operations and write a mesh commit
+.TP
+git\-mesh\-restore(1)
+Clear the staging area
+.TP
+git\-mesh\-revert(1)
+Fast\-forward a mesh to a past state
+.TP
+git\-mesh\-delete(1)
+Delete a mesh ref
+.TP
+git\-mesh\-mv(1)
+Rename a mesh ref
+.TP
+git\-mesh\-config(1)
+Read or stage mesh\-level resolver options
+.TP
+git\-mesh\-fetch(1)
+Fetch mesh and range refs from a remote
+.TP
+git\-mesh\-push(1)
+Push mesh and range refs to a remote
+.TP
+git\-mesh\-doctor(1)
+Audit the local mesh setup
+.TP
+git\-mesh\-pre\-commit(1)
+Fail the current commit if any drift is visible in the staged tree
+.TP
+git\-mesh\-advice(1)
+Append events and flush session\-scoped advice
+.TP
+git\-mesh\-help(1)
+Print this message or the help of the given subcommand(s)
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.SH VERSION
+v1.0.13
+.SH EXAMPLES
+Anchor a new mesh alongside a code change:
+.PP
+.RS 4
+.nf
+git mesh add billing/charge-request-contract \e
+    docs/api/charge.md#L40-L88 api/charge.ts#L30-L76
+git mesh why billing/charge-request-contract \e
+    -m "The doc states the request body shape the parser honors; \e
+the doc is the source of truth when they disagree."
+git commit -m "Wire checkout to charge API"
+# post-commit hook runs: git mesh commit
+.fi
+.RE
+.PP
+Document an existing relationship anchored at HEAD:
+.PP
+.RS 4
+.nf
+git mesh add auth/token-contract --at HEAD \e
+    packages/auth/token.ts#L88-L104 \e
+    packages/auth/crypto.ts#L12-L40
+git mesh why auth/token-contract \e
+    -m "Token verification depends on signature verification."
+git mesh commit auth/token-contract
+.fi
+.RE
+.PP
+Check for drift and inspect a mesh:
+.PP
+.RS 4
+.nf
+git mesh stale
+git mesh billing/charge-request-contract
+git mesh billing/charge-request-contract --log
+.fi
+.RE
+.SH SEE ALSO
+.BR git (1),
+.BR gitcli (7)

package/package.json

@@ -1,29 +1,34 @@
 {
   "name": "@goodfoot/git-mesh",
-  "version": "1.0.0",
+  "version": "1.0.16",
   "bin": "bin/git-mesh",
+  "man": [
+    "man/git-mesh.1"
+  ],
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
-    "build": "env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=target/build cargo build --release",
-    "build:local": "mkdir -p \"$HOME/.local/bin\" && env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=target/build cargo build --release && install -m 0755 target/build/release/git-mesh \"$HOME/.local/bin/git-mesh\"",
-    "build:clean": "rm -rf target/build target/lint target/test target/typecheck && env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=target/build cargo build --release",
-    "test": "env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=target/test cargo test --quiet -- --test-threads=1",
-    "lint": "env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=target/lint cargo clippy --quiet -- -D warnings",
-    "typecheck": "env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=target/typecheck cargo check --quiet"
+    "build:man": "env CARGO_TARGET_DIR=\"${GIT_MESH_CARGO_TARGET_ROOT:-$HOME/.cache/git-mesh/cargo-target}/build\" cargo run --quiet --bin gen-manpage -- man/git-mesh.1",
+    "build": "yarn build:man && env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_MESH_CARGO_TARGET_ROOT:-$HOME/.cache/git-mesh/cargo-target}/build\" cargo build --release",
+    "build:local": "mkdir -p \"$HOME/.local/bin\" \"$HOME/.local/share/man/man1\" && env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_MESH_CARGO_TARGET_ROOT:-$HOME/.cache/git-mesh/cargo-target}/build\" cargo build --release && install -m 0755 \"${GIT_MESH_CARGO_TARGET_ROOT:-$HOME/.cache/git-mesh/cargo-target}/build/release/git-mesh\" \"$HOME/.local/bin/git-mesh\" && yarn build:man && install -m 0644 man/git-mesh.1 \"$HOME/.local/share/man/man1/git-mesh.1\"",
+    "build:clean": "rm -rf \"${GIT_MESH_CARGO_TARGET_ROOT:-$HOME/.cache/git-mesh/cargo-target}\" && yarn build:man && env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_MESH_CARGO_TARGET_ROOT:-$HOME/.cache/git-mesh/cargo-target}/build\" cargo build --release",
+    "test": "env CARGO_TARGET_DIR=\"${GIT_MESH_CARGO_TARGET_ROOT:-$HOME/.cache/git-mesh/cargo-target}/test\" cargo nextest run --build-jobs 1",
+    "lint": "env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_MESH_CARGO_TARGET_ROOT:-$HOME/.cache/git-mesh/cargo-target}/lint\" cargo clippy --quiet -- -D warnings",
+    "typecheck": "env CARGO_BUILD_JOBS=1 CARGO_TARGET_DIR=\"${GIT_MESH_CARGO_TARGET_ROOT:-$HOME/.cache/git-mesh/cargo-target}/typecheck\" cargo check --quiet --locked"
   },
   "files": [
     "bin/",
+    "man/",
     "scripts/postinstall.js"
   ],
   "optionalDependencies": {
-    "@goodfoot/git-mesh-darwin-arm64": "1.0.0",
-    "@goodfoot/git-mesh-darwin-x64": "1.0.0",
-    "@goodfoot/git-mesh-linux-arm64": "1.0.0",
-    "@goodfoot/git-mesh-linux-x64": "1.0.0",
-    "@goodfoot/git-mesh-win32-x64": "1.0.0"
+    "@goodfoot/git-mesh-darwin-arm64": "1.0.16",
+    "@goodfoot/git-mesh-darwin-x64": "1.0.16",
+    "@goodfoot/git-mesh-linux-arm64": "1.0.16",
+    "@goodfoot/git-mesh-linux-x64": "1.0.16",
+    "@goodfoot/git-mesh-win32-x64": "1.0.16"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/goodfoot-io/git-mesh.git"
   }
-}
+}

package/scripts/postinstall.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 
 const PLATFORM_MAP = {
   linux: 'linux',
@@ -22,6 +23,37 @@ function fail(message, error) {
   process.exit(1);
 }
 
+function buildFromSource(destBinary, binaryName) {
+  const cargoToml = path.join(__dirname, '..', 'Cargo.toml');
+  if (!fs.existsSync(cargoToml)) {
+    fail(`@goodfoot/git-mesh: Binary not found at ${destBinary} and no Cargo.toml available to build from source.`);
+  }
+
+  console.log(`@goodfoot/git-mesh: Prebuilt binary missing; building from source via cargo...`);
+
+  const targetDir = path.join(__dirname, '..', 'target', 'build');
+  const result = spawnSync('cargo', ['build', '--release', '--manifest-path', cargoToml], {
+    stdio: 'inherit',
+    env: { ...process.env, CARGO_BUILD_JOBS: '1', CARGO_TARGET_DIR: targetDir }
+  });
+
+  if (result.error || result.status !== 0) {
+    fail(
+      `@goodfoot/git-mesh: Failed to build binary from source. Install Rust/cargo or publish the platform package.`,
+      result.error
+    );
+  }
+
+  const builtBinary = path.join(targetDir, 'release', binaryName);
+  if (!fs.existsSync(builtBinary)) {
+    fail(`@goodfoot/git-mesh: cargo build succeeded but binary not found at ${builtBinary}.`);
+  }
+
+  fs.mkdirSync(path.dirname(destBinary), { recursive: true });
+  fs.copyFileSync(builtBinary, destBinary);
+  fs.chmodSync(destBinary, 0o755);
+}
+
 function main() {
   const platform = PLATFORM_MAP[process.platform];
   const arch = ARCH_MAP[process.arch];
@@ -42,7 +74,7 @@ function main() {
 
   const sourceBinary = path.join(packageDir, 'bin', sourceBinaryName);
   if (!fs.existsSync(sourceBinary)) {
-    fail(`@goodfoot/git-mesh: Binary not found in ${packageName}. The package may not have been published correctly.`);
+    buildFromSource(sourceBinary, sourceBinaryName);
   }
 
   const binGitMesh = path.join(__dirname, '..', 'bin', 'git-mesh');