feat(miner): scaffold gittensory-miner package

packages/gittensory-engine/lib/index.d.ts

@@ -0,0 +1 @@
+export {};

packages/gittensory-engine/lib/index.js

@@ -0,0 +1 @@
+export {};

packages/gittensory-engine/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@jsonbored/gittensory-engine",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "description": "Shared pure engine helpers for Gittensory miner and gate logic.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JSONbored/gittensory.git",
+    "directory": "packages/gittensory-engine"
+  },
+  "homepage": "https://github.com/JSONbored/gittensory#readme",
+  "bugs": {
+    "url": "https://github.com/JSONbored/gittensory/issues"
+  },
+  "keywords": [
+    "gittensor",
+    "gittensory",
+    "engine",
+    "shared",
+    "miner"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./lib/index.js",
+  "exports": "./lib/index.js",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "node --check lib/index.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

packages/gittensory-miner/README.md

@@ -0,0 +1,33 @@
+# @jsonbored/gittensory-miner
+
+Foundation CLI for the local Gittensory miner runtime.
+
+This package is the future home of the autonomous discover → analyze → plan → prepare → create → manage miner workflow. In this foundation phase it only provides the package scaffold and a minimal CLI surface for `--help` and `--version`.
+
+## Status
+
+Current scope is intentionally small:
+
+- workspace package wiring
+- CLI entry point
+- `--help` and `version` commands
+
+Real miner commands land in follow-up issues.
+
+## Install
+
+From a local checkout:
+
+```sh
+npm install
+npm --workspace @jsonbored/gittensory-miner run build
+```
+
+## Commands
+
+```sh
+gittensory-miner --help
+gittensory-miner help
+gittensory-miner --version
+gittensory-miner version
+```

packages/gittensory-miner/bin/gittensory-miner.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { printHelp, printVersion, runCli } from "../lib/cli.js";
+
+const cliArgs = process.argv.slice(2);
+const require = createRequire(import.meta.url);
+const packageName = "@jsonbored/gittensory-miner";
+const packageVersion = require("../package.json").version;
+
+if (cliArgs.length === 0 || cliArgs.includes("--help") || cliArgs.includes("-h") || cliArgs[0] === "help") {
+  printHelp({ packageName });
+  process.exit(0);
+}
+
+if (cliArgs.includes("--version") || cliArgs.includes("-v") || cliArgs[0] === "version") {
+  printVersion({ packageName, packageVersion });
+  process.exit(0);
+}
+
+const exitCode = runCli(cliArgs, { packageName });
+process.exit(exitCode);

packages/gittensory-miner/lib/cli.d.ts

@@ -0,0 +1,12 @@
+export type VersionPrintInput = {
+  packageName: string;
+  packageVersion: string;
+};
+
+export type HelpPrintInput = {
+  packageName: string;
+};
+
+export declare function printVersion(input: VersionPrintInput): void;
+export declare function printHelp(input: HelpPrintInput): void;
+export declare function runCli(cliArgs: string[], input: HelpPrintInput): number;

packages/gittensory-miner/lib/cli.js

@@ -0,0 +1,25 @@
+export function printVersion(input) {
+  console.log(`${input.packageName}/${input.packageVersion} (node ${process.version})`);
+}
+
+export function printHelp(input) {
+  console.log(
+    [
+      input.packageName,
+      "",
+      "Foundation CLI for the local Gittensory miner runtime.",
+      "",
+      "Usage:",
+      "  gittensory-miner --help",
+      "  gittensory-miner --version",
+      "  gittensory-miner help",
+      "  gittensory-miner version",
+    ].join("\n"),
+  );
+}
+
+export function runCli(cliArgs, input) {
+  const command = cliArgs[0] ?? "";
+  console.error(`Unknown command: ${command}. Run ${input.packageName} --help.`);
+  return 1;
+}

packages/gittensory-miner/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@jsonbored/gittensory-miner",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "description": "Foundation CLI for the local Gittensory miner runtime.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JSONbored/gittensory.git",
+    "directory": "packages/gittensory-miner"
+  },
+  "homepage": "https://github.com/JSONbored/gittensory#readme",
+  "bugs": {
+    "url": "https://github.com/JSONbored/gittensory/issues"
+  },
+  "keywords": [
+    "gittensor",
+    "gittensory",
+    "miner",
+    "cli",
+    "agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "gittensory-miner": "bin/gittensory-miner.js"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "scripts": {
+    "build": "node --check bin/gittensory-miner.js && node --check lib/cli.js"
+  },
+  "dependencies": {
+    "@jsonbored/gittensory-engine": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

test/unit/miner-cli.test.ts

@@ -0,0 +1,34 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { printHelp, printVersion, runCli } from "../../packages/gittensory-miner/lib/cli.js";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("gittensory-miner CLI helpers", () => {
+  it("prints the package version with the node runtime", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    printVersion({ packageName: "@jsonbored/gittensory-miner", packageVersion: "0.1.0" });
+    expect(log).toHaveBeenCalledWith(expect.stringContaining("@jsonbored/gittensory-miner/0.1.0"));
+    expect(log).toHaveBeenCalledWith(expect.stringContaining(process.version));
+  });
+
+  it("prints help text with the supported commands", () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    printHelp({ packageName: "@jsonbored/gittensory-miner" });
+    const text = log.mock.calls[0]?.[0];
+    expect(text).toContain("gittensory-miner --help");
+    expect(text).toContain("gittensory-miner version");
+  });
+
+  it("returns exit code 1 for unknown commands", () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(runCli(["mystery"], { packageName: "@jsonbored/gittensory-miner" })).toBe(1);
+    expect(error).toHaveBeenCalledWith("Unknown command: mystery. Run @jsonbored/gittensory-miner --help.");
+  });
+
+  it("keeps the CLI version source aligned with package metadata", async () => {
+    const packageJson = await import("../../packages/gittensory-miner/package.json", { with: { type: "json" } });
+    expect(packageJson.default.version).toBe("0.1.0");
+  });
+});

test/unit/miner-package-contract.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from "vitest";
+
+describe("miner package workspace contracts", () => {
+  it("allows importing @jsonbored/gittensory-engine by package name", async () => {
+    const mod = await import("@jsonbored/gittensory-engine");
+    expect(Object.keys(mod)).toEqual([]);
+  });
+});