@sixthsummit/ship-cli 0.0.0-stage → 1.2.0

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@sixthsummit/ship-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "description": "Deterministic application graph and API contract tools for Ship projects",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "bin": {
+    "ship-api": "./lib/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./contract": {
+      "types": "./lib/contract.d.ts",
+      "import": "./lib/contract.js",
+      "default": "./lib/contract.js"
+    },
+    "./graph": {
+      "types": "./lib/graph.d.ts",
+      "import": "./lib/graph.js",
+      "default": "./lib/graph.js"
+    },
+    "./migration": {
+      "types": "./lib/migration.d.ts",
+      "import": "./lib/migration.js",
+      "default": "./lib/migration.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "lib/",
+    "templates/",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@sixthsummit/ship-contract": "^1.3.0",
+    "commander": "^12.0.0",
+    "tsx": "^4.20.3"
+  },
+  "peerDependencies": {
+    "@sixthsummit/ship-core": "^1.1.1"
+  },
+  "devDependencies": {
+    "@sixthsummit/ship-core": "1.1.1",
+    "@sixthsummit/ship-hono": "^1.2.0",
+    "zod": "^4.3.6"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SixthSummit/Ship.git",
+    "directory": "packages/cli"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-package.mjs && tsc -p tsconfig.json && node ../../scripts/build-cli-release-manifest.mjs",
+    "type-check": "tsc --noEmit -p tsconfig.check.json",
+    "test": "vitest run --root ../.. packages/cli/src",
+    "test:coverage": "vitest run --root ../.. packages/cli/src --coverage --coverage.include=packages/cli/src/**"
+  }
 }

package/templates/operation/.github/pull_request_template.md

@@ -0,0 +1,41 @@
+## Why
+
+<!-- State the problem, user impact, or invariant this PR addresses. -->
+
+## What changed
+
+<!-- Describe one logical change and any explicit non-scope. -->
+
+## Contract and architecture
+
+- [ ] Operation IDs, inputs, outputs, statuses, errors, access, transactions, and effects are unchanged.
+- [ ] Changed behavior and its migration path are documented below.
+- [ ] No hidden global state, ambient dependency, or undocumented deep import was introduced.
+
+Contract notes:
+
+## Test evidence
+
+- [ ] AI-generated or AI-assisted tests were reviewed for correctness.
+- [ ] New behavior and edge cases have colocated Vitest coverage.
+- [ ] Tests are deterministic and clean up state.
+- [ ] Changed source meets the 80% coverage threshold.
+- [ ] `pnpm run verify` passes.
+
+Commands and results:
+
+```text
+pnpm run verify
+```
+
+## Security, data, and release
+
+- [ ] Auth, transaction, and external-effect boundaries are explicit or not applicable.
+- [ ] No secret, credential, production data, or unsafe fallback was added.
+- [ ] A Changeset is included for a published contract change, or this application change needs none.
+
+Risk and rollback:
+
+## Reviewer focus
+
+<!-- Identify the assumption or code path reviewers should challenge first. -->

package/templates/operation/AGENTS.md

@@ -0,0 +1,46 @@
+# Agent guide
+
+This repository is a ShipAPI operation application. The compiled operation graph,
+not a prompt, folder name, Hono handler, or generated document, defines behavior.
+
+## Start here
+
+1. Run `pnpm ship-api inspect app --format json`.
+2. Inspect the affected module or operation by stable ID.
+3. Read only that module, its declared providers, and colocated tests.
+4. Run `pnpm ship-api affected <kind> <id> --format json` before changing a shared node.
+
+## Structure
+
+- `src/application.ts` is the composition root.
+- `src/modules/<module>/module.ts` owns a bounded feature.
+- `*.operation.ts` declares input, output, errors, access, transaction mode,
+  dependencies, effects, transport, and handler together.
+- `ship.config.ts` exposes the compiled app to deterministic CLI tooling.
+- `.ship/contract.json` and `.ship/openapi.json` are generated projections.
+
+## Invariants
+
+- Keep domain behavior transport-independent; Hono is an adapter.
+- Never read a database, auth provider, clock, queue, or external service from
+  ambient global state. Declare the capability as an operation dependency.
+- A write declares `transaction: "write"`; do not hide writes in read operations.
+- Declare external effects and their delivery semantics. Do not perform them from
+  an unlisted dependency.
+- Expected failures are declared operation errors; do not throw message-shaped
+  protocol responses from handlers.
+- Treat operation IDs and error codes as public compatibility keys.
+- Do not hand-edit generated contract or OpenAPI artifacts.
+
+## Tests and gates
+
+Tests use Vitest, are colocated as `FileName.test.ts`, and verify one behavior per
+test. Generate tests with code, then review their assertions and failure paths.
+
+Run `pnpm run verify` before handing off a change. It checks Biome, the graph,
+TypeScript, unit tests, 80% coverage, HTTP integration, the production build, and
+contract generation. Do not skip a failing gate because older tests look stale;
+change a test only when the declared behavior intentionally changed.
+
+Commits use `<type>(<scope>): <imperative description>`. Keep logical changes
+separate. Use `fix` only for user-facing defects.

package/templates/operation/README.md

@@ -0,0 +1,37 @@
+# {{PROJECT_NAME}}
+
+An operation-native ShipAPI service. One compiled application graph drives direct
+execution, HTTP, client contracts, OpenAPI, and inspection tooling.
+
+## Run
+
+```sh
+pnpm install
+pnpm run verify
+pnpm run dev
+```
+
+`GET http://localhost:3000/health` executes `system.health` through the Hono
+adapter. The same operation runs without HTTP in `src/application.test.ts`.
+
+## Extend
+
+Add a bounded directory under `src/modules/`. Declare operations with stable IDs,
+schemas, errors, access, transaction mode, dependencies, effects, and transport;
+then add the module to `src/application.ts`.
+
+Use the graph before reading the entire repository:
+
+```sh
+pnpm ship-api inspect app
+pnpm ship-api inspect operation system.health
+pnpm ship-api affected module system
+pnpm run contract
+```
+
+Read `AGENTS.md` for the invariants and test workflow. To use the repository commit
+template locally, run:
+
+```sh
+git config commit.template .gitmessage
+```

package/templates/operation/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+lib/
+coverage/
+.env
+.DS_Store

package/templates/operation/_gitmessage

@@ -0,0 +1,12 @@
+# <type>[optional scope]: <imperative description>
+#
+# Why is this change needed?
+#
+# What evidence proves it works?
+#
+# Optional footers:
+# BREAKING CHANGE: <consumer impact and migration path>
+# Refs: <issue, ADR, or RFC>
+#
+# Types: feat, fix, perf, refactor, docs, style, test, build, ci, chore
+# Use fix only for user-facing defects. Changesets, not commit types, control releases.

package/templates/operation/biome.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true,
+    "defaultBranch": "main"
+  },
+  "files": {
+    "includes": ["**", "!!node_modules", "!!lib", "!!coverage", "!!.ship"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  }
+}

package/templates/operation/package.template.json

@@ -0,0 +1,21 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "check": "biome check .",
+    "check:graph": "ship-api check",
+    "type-check": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --exclude '**/*.integration.test.ts'",
+    "test:watch": "vitest --exclude '**/*.integration.test.ts'",
+    "test:coverage": "vitest run --exclude '**/*.integration.test.ts' --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "contract": "ship-api contract --api-version 0.1.0",
+    "verify": "pnpm run check && pnpm run check:graph && pnpm run type-check && pnpm test && pnpm run test:coverage && pnpm run test:integration && pnpm run build && pnpm run contract"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/templates/operation/ship.config.ts

@@ -0,0 +1 @@
+export { app } from "./src/application.js";

package/templates/operation/src/application.integration.test.ts

@@ -0,0 +1,15 @@
+import { createHonoAdapter } from "@sixthsummit/ship-hono";
+import { describe, expect, it } from "vitest";
+import { app } from "./application.js";
+
+describe("{{PROJECT_NAME}} HTTP boundary", () => {
+  it("projects the same health operation onto Hono", async () => {
+    const response = await createHonoAdapter(app).request("/health");
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual({
+      ok: true,
+      service: "{{PACKAGE_NAME}}",
+    });
+  });
+});

package/templates/operation/src/application.test.ts

@@ -0,0 +1,16 @@
+import { createExecutor } from "@sixthsummit/ship-core";
+import { describe, expect, it } from "vitest";
+import { app } from "./application.js";
+
+describe("{{PROJECT_NAME}} application", () => {
+  it("executes the health operation directly", async () => {
+    const result = await createExecutor(app).run("system.health", {}, { requestId: "unit-health" });
+
+    expect(result).toEqual({
+      ok: true,
+      status: 200,
+      data: { ok: true, service: "{{PACKAGE_NAME}}" },
+      requestId: "unit-health",
+    });
+  });
+});

package/templates/operation/src/application.ts

@@ -0,0 +1,7 @@
+import { defineApp } from "@sixthsummit/ship-core";
+import { systemModule } from "./modules/system/module.js";
+
+export const app = defineApp({
+  id: "{{PACKAGE_NAME}}",
+  modules: [systemModule],
+});

package/templates/operation/src/modules/system/health.operation.ts

@@ -0,0 +1,34 @@
+import { contractSchema } from "@sixthsummit/ship-contract/schema";
+import { defineOperation, publicAccess } from "@sixthsummit/ship-core";
+import { http } from "@sixthsummit/ship-hono";
+import { z } from "zod";
+
+const healthOutput = contractSchema(
+  z.object({
+    ok: z.literal(true),
+    service: z.literal("{{PACKAGE_NAME}}"),
+  }),
+  {
+    jsonSchema: {
+      type: "object",
+      required: ["ok", "service"],
+      properties: {
+        ok: { const: true },
+        service: { const: "{{PACKAGE_NAME}}" },
+      },
+    },
+  },
+);
+
+export const readHealth = defineOperation({
+  id: "system.health",
+  transport: http.get("/health"),
+  input: {},
+  output: { 200: healthOutput },
+  successStatus: 200,
+  errors: [],
+  access: publicAccess(),
+  transaction: "none",
+  dependencies: {},
+  handler: async () => ({ ok: true as const, service: "{{PACKAGE_NAME}}" as const }),
+});

package/templates/operation/src/modules/system/module.ts

@@ -0,0 +1,10 @@
+import { defineModule } from "@sixthsummit/ship-core";
+import { readHealth } from "./health.operation.js";
+
+export const systemModule = defineModule({
+  id: "system",
+  operations: [readHealth],
+  providers: [],
+  imports: [],
+  exports: [],
+});

package/templates/operation/src/server.ts

@@ -0,0 +1,13 @@
+import { serve } from "@hono/node-server";
+import { createHonoAdapter } from "@sixthsummit/ship-hono";
+import { app } from "./application.js";
+
+const port = Number.parseInt(process.env.PORT ?? "3000", 10);
+if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+  throw new Error("PORT must be an integer between 1 and 65535");
+}
+
+const http = createHonoAdapter(app);
+serve({ fetch: http.fetch, port }, ({ port: listeningPort }) => {
+  process.stdout.write(`{{PACKAGE_NAME}} listening on ${listeningPort}\n`);
+});

package/templates/operation/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "lib",
+    "rootDir": "src",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.integration.test.ts"]
+}

package/templates/operation/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "ship.config.ts", "vitest.config.ts", "vitest.integration.config.ts"]
+}

package/templates/operation/vitest.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    exclude: ["node_modules/**", "lib/**", "**/*.integration.test.ts"],
+    coverage: {
+      provider: "v8",
+      reportsDirectory: "coverage",
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/*.test.ts", "src/**/*.integration.test.ts", "src/server.ts"],
+      thresholds: {
+        branches: 80,
+        functions: 80,
+        lines: 80,
+        statements: 80,
+      },
+    },
+  },
+});

package/templates/operation/vitest.integration.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.integration.test.ts"],
+  },
+});