@hunsu/core 0.1.0

package/src/port.ts

@@ -0,0 +1,263 @@
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { type Command, type DestinationSeedInput, type HarnessSnapshot } from "@hunsu/protocol";
+import { hasHunsuRuntimeState, loadDomainStore, readDomainEventRefs, writeCommands } from "./domain-store.ts";
+import { GitError } from "./errors.ts";
+import { ensureGitRepository, git } from "./git.ts";
+
+export type HunsuPortInspection = {
+  root: string;
+  isGitRepository: boolean;
+  isHunsuRoadmap: boolean;
+  packageManager?: "pnpm" | "npm" | "yarn" | "bun";
+  packageScripts: Record<string, string>;
+  docker: {
+    dockerfiles: string[];
+    composeFiles: string[];
+  };
+  artifactActions: {
+    configured: boolean;
+    count: number;
+    issues: string[];
+  };
+  env: {
+    files: string[];
+    hardcodedHints: string[];
+  };
+  recommendedFiles: HunsuPortFilePlan[];
+  issues: string[];
+};
+
+export type HunsuPortFilePlan = {
+  path: string;
+  action: "create";
+  reason: string;
+  content: string;
+};
+
+export type HunsuPortPlanInput = {
+  cwd?: string;
+  title?: string;
+  goal?: string;
+  destinations?: DestinationSeedInput[];
+  harness?: HarnessSnapshot;
+};
+
+export type HunsuPortPlan = {
+  root: string;
+  title: string;
+  goal: string;
+  destinations: DestinationSeedInput[];
+  inspection: HunsuPortInspection;
+  files: HunsuPortFilePlan[];
+  commands: Command[];
+};
+
+export type HunsuPortApplyResult = {
+  root: string;
+  plan: HunsuPortPlan;
+  writtenFiles: string[];
+  acceptedEvents: ReturnType<typeof writeCommands>["acceptedEvents"];
+  board: ReturnType<typeof writeCommands>["board"];
+};
+
+type PackageJson = {
+  scripts?: Record<string, string>;
+  packageManager?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+const DEFAULT_PORT_TITLE = "Port Git Project";
+const DEFAULT_PORT_GOAL = "Make this project ready for Hunsu-managed MOVEs and Artifact Actions.";
+
+export function inspectHunsuPort(cwd = process.cwd()): HunsuPortInspection {
+  const target = resolve(cwd);
+  const issues: string[] = [];
+  let root = target;
+  let isGitRepository = false;
+
+  try {
+    root = ensureGitRepository(target);
+    isGitRepository = true;
+  } catch (error) {
+    issues.push("Not a Git repository. Hunsu Port expects an existing Git project.");
+  }
+
+  const packageJson = readPackageJson(root);
+  const packageScripts = packageJson?.scripts ?? {};
+  const packageManager = detectPackageManager(root, packageJson);
+  const dockerfiles = listRootFiles(root, /^Dockerfile(?:\.|$)/);
+  const composeFiles = listRootFiles(root, /^(?:docker-)?compose(?:\.[^.]+)?\.ya?ml$/);
+  const isHunsuRoadmap = isGitRepository && hasHunsuStateOrLegacyRefs(root);
+  const artifactActions = inspectArtifactActions(root);
+  const env = inspectEnvHints(root, packageScripts);
+  const recommendedFiles: HunsuPortFilePlan[] = [];
+
+  if (!packageJson && isGitRepository) {
+    issues.push("No package.json found. Port can still create Roadmap state, but Artifact Actions may need a later Hunsu setup.");
+  }
+  if (isGitRepository && !isHunsuRoadmap) {
+    issues.push("Hunsu runtime state is missing. Port apply will create Initial Team state.");
+  }
+
+  return {
+    root,
+    isGitRepository,
+    isHunsuRoadmap,
+    packageManager,
+    packageScripts,
+    docker: {
+      dockerfiles,
+      composeFiles
+    },
+    artifactActions,
+    env,
+    recommendedFiles,
+    issues
+  };
+}
+
+export function planHunsuPort(input: HunsuPortPlanInput = {}): HunsuPortPlan {
+  const inspection = inspectHunsuPort(input.cwd);
+  if (!inspection.isGitRepository) {
+    throw new Error("Hunsu Port requires an existing Git repository");
+  }
+  const title = input.title?.trim() || basename(inspection.root) || DEFAULT_PORT_TITLE;
+  const goal = input.goal?.trim() || DEFAULT_PORT_GOAL;
+  const destinations = input.destinations && input.destinations.length > 0
+    ? input.destinations
+    : [{ id: "destination_001", title: "Establish artifact-action-ready product execution", priority: 100 }];
+  const commands: Command[] = inspection.isHunsuRoadmap
+    ? []
+    : [{
+        type: "CreateInitialTeam",
+        requestId: createId("req", title),
+        lineId: `run/${createId("req", title)}`,
+        title,
+        goal,
+        destinations,
+        harness: input.harness
+      }];
+  return {
+    root: inspection.root,
+    title,
+    goal,
+    destinations,
+    inspection,
+    files: [],
+    commands
+  };
+}
+
+export function applyHunsuPort(input: HunsuPortPlanInput = {}): HunsuPortApplyResult {
+  const plan = planHunsuPort(input);
+  const writtenFiles: string[] = [];
+  for (const file of plan.files) {
+    const path = join(plan.root, file.path);
+    if (existsSync(path)) {
+      continue;
+    }
+    writeFileSync(path, file.content, "utf8");
+    writtenFiles.push(file.path);
+  }
+  const result = plan.commands.length > 0
+    ? writeCommands(plan.commands, { cwd: plan.root, commitMessage: `hunsu: port ${plan.title}` })
+    : { acceptedEvents: [], board: loadDomainStore(plan.root).board };
+  return {
+    root: plan.root,
+    plan,
+    writtenFiles,
+    acceptedEvents: result.acceptedEvents,
+    board: result.board
+  };
+}
+
+function inspectArtifactActions(root: string): HunsuPortInspection["artifactActions"] {
+  if (!hasHunsuStateOrLegacyRefs(root)) {
+    return {
+      configured: false,
+      count: 0,
+      issues: []
+    };
+  }
+  const board = loadDomainStore(root).board;
+  return {
+    configured: board.artifactActions.length > 0,
+    count: board.artifactActions.length,
+    issues: []
+  };
+}
+
+function detectPackageManager(root: string, packageJson: PackageJson | undefined): HunsuPortInspection["packageManager"] {
+  if (existsSync(join(root, "pnpm-lock.yaml")) || packageJson?.packageManager?.startsWith("pnpm@")) {
+    return "pnpm";
+  }
+  if (existsSync(join(root, "yarn.lock")) || packageJson?.packageManager?.startsWith("yarn@")) {
+    return "yarn";
+  }
+  if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock")) || packageJson?.packageManager?.startsWith("bun@")) {
+    return "bun";
+  }
+  if (existsSync(join(root, "package-lock.json")) || packageJson) {
+    return "npm";
+  }
+  return undefined;
+}
+
+function readPackageJson(root: string): PackageJson | undefined {
+  const path = join(root, "package.json");
+  if (!existsSync(path)) {
+    return undefined;
+  }
+  return JSON.parse(readFileSync(path, "utf8")) as PackageJson;
+}
+
+function listRootFiles(root: string, pattern: RegExp): string[] {
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    return [];
+  }
+  return readdirSync(root)
+    .filter(file => pattern.test(file))
+    .sort();
+}
+
+function hasHunsuStateOrLegacyRefs(root: string): boolean {
+  try {
+    return hasHunsuRuntimeState(root)
+      || readDomainEventRefs(root).length > 0
+      || git(["for-each-ref", "--count=1", "--format=%(refname)", "refs/hunsu"], { cwd: root }).trim().length > 0;
+  } catch (error) {
+    if (error instanceof GitError) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function inspectEnvHints(root: string, scripts: Record<string, string>): HunsuPortInspection["env"] {
+  const files = [".env", ".env.local", ".env.development", ".env.example"].filter(file => existsSync(join(root, file)));
+  const hardcodedHints = Object.entries(scripts)
+    .filter(([, script]) => /\b(?:3000|5173|8080|4187)\b|localhost|127\.0\.0\.1/.test(script))
+    .map(([name]) => `package.json scripts.${name}`);
+  for (const file of ["vite.config.ts", "vite.config.js", "next.config.js", "next.config.mjs"]) {
+    const path = join(root, file);
+    if (!existsSync(path)) {
+      continue;
+    }
+    const text = readFileSync(path, "utf8");
+    if (/\b(?:3000|5173|8080|4187)\b|localhost|127\.0\.0\.1/.test(text)) {
+      hardcodedHints.push(file);
+    }
+  }
+  return { files, hardcodedHints };
+}
+
+function createId(prefix: string, value: string): string {
+  const slug = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 48);
+  return `${prefix}_${slug || "project"}`;
+}

package/src/primitives.ts

@@ -0,0 +1,160 @@
+import { err, ok, type Result } from "@hunsu/protocol";
+import { HunsuError } from "./errors.ts";
+
+export type CoreBrand<T, Name extends string> = T & { readonly __coreBrand: Name };
+
+export type CommitSha = CoreBrand<string, "CommitSha">;
+export type GitRef = CoreBrand<string, "GitRef">;
+export type BranchName = CoreBrand<string, "BranchName">;
+export type RuntimeChecksum = CoreBrand<string, "RuntimeChecksum">;
+export type RuntimeSchemaName = CoreBrand<string, "RuntimeSchemaName">;
+export type GitRunId = CoreBrand<string, "GitRunId">;
+export type GitMoveNumber = CoreBrand<string, "GitMoveNumber">;
+export type GitMoveId = CoreBrand<string, "GitMoveId">;
+export type GitGoal = CoreBrand<string, "GitGoal">;
+export type GitPriority = CoreBrand<string, "GitPriority">;
+export type GitTrailerRole = CoreBrand<string, "GitTrailerRole">;
+export type GitTrailerActor = CoreBrand<string, "GitTrailerActor">;
+export type GitHunsuId = CoreBrand<string, "GitHunsuId">;
+
+export type CorePrimitiveError = {
+  type: "CorePrimitiveError";
+  field: string;
+  message: string;
+};
+
+export function makeCommitSha(value: unknown, field = "commitSha"): Result<CommitSha, CorePrimitiveError> {
+  return typeof value === "string" && /^[0-9a-f]{40}$/i.test(value)
+    ? ok(value as CommitSha)
+    : corePrimitiveError(field, "must be a 40-character Git commit SHA");
+}
+
+export function makeGitRef(value: unknown, field = "gitRef"): Result<GitRef, CorePrimitiveError> {
+  return makeGitToken(value, field, "must be a non-empty Git ref") as Result<GitRef, CorePrimitiveError>;
+}
+
+export function makeBranchName(value: unknown, field = "branchName"): Result<BranchName, CorePrimitiveError> {
+  return makeGitToken(value, field, "must be a non-empty branch name") as Result<BranchName, CorePrimitiveError>;
+}
+
+export function makeRuntimeChecksum(value: unknown, field = "runtimeChecksum"): Result<RuntimeChecksum, CorePrimitiveError> {
+  return typeof value === "string" && /^[0-9a-f]{64}$/i.test(value)
+    ? ok(value as RuntimeChecksum)
+    : corePrimitiveError(field, "must be a SHA-256 hex checksum");
+}
+
+export function makeRuntimeSchemaName(value: unknown, field = "runtimeSchemaName"): Result<RuntimeSchemaName, CorePrimitiveError> {
+  return makeNonEmptyCoreString(value, field, "must be a non-empty runtime schema name") as Result<RuntimeSchemaName, CorePrimitiveError>;
+}
+
+export function makeGitRunId(value: unknown, field = "runId"): Result<GitRunId, CorePrimitiveError> {
+  return makeNonEmptyCoreString(value, field, "must be a non-empty Hunsu run id") as Result<GitRunId, CorePrimitiveError>;
+}
+
+export function makeGitMoveNumber(value: unknown, field = "moveNumber"): Result<GitMoveNumber, CorePrimitiveError> {
+  const raw = String(value).trim();
+  const digits = /^M\d+$/i.test(raw) ? raw.slice(1) : raw;
+  return /^\d+$/.test(digits)
+    ? ok(digits.padStart(4, "0") as GitMoveNumber)
+    : corePrimitiveError(field, "must be numeric");
+}
+
+export function makeGitMoveId(value: unknown, field = "moveId"): Result<GitMoveId, CorePrimitiveError> {
+  const moveNumber = makeGitMoveNumber(value, field);
+  return moveNumber.ok ? ok(`M${moveNumber.value}` as GitMoveId) : moveNumber;
+}
+
+export function makeGitGoal(value: unknown, field = "goal"): Result<GitGoal, CorePrimitiveError> {
+  return makeGitToken(value, field, "must be a non-empty Hunsu goal") as Result<GitGoal, CorePrimitiveError>;
+}
+
+export function makeGitPriority(value: unknown, field = "priority"): Result<GitPriority, CorePrimitiveError> {
+  return makeGitToken(value, field, "must be a non-empty Hunsu priority") as Result<GitPriority, CorePrimitiveError>;
+}
+
+export function makeGitTrailerRole(value: unknown, field = "role"): Result<GitTrailerRole, CorePrimitiveError> {
+  return makeNonEmptyCoreString(value, field, "must be a non-empty Hunsu role") as Result<GitTrailerRole, CorePrimitiveError>;
+}
+
+export function makeGitTrailerActor(value: unknown, field = "actor"): Result<GitTrailerActor, CorePrimitiveError> {
+  return makeNonEmptyCoreString(value, field, "must be a non-empty Hunsu actor") as Result<GitTrailerActor, CorePrimitiveError>;
+}
+
+export function makeGitHunsuId(value: unknown, field = "hunsuId"): Result<GitHunsuId, CorePrimitiveError> {
+  return makeNonEmptyCoreString(value, field, "must be a non-empty HUNSU id") as Result<GitHunsuId, CorePrimitiveError>;
+}
+
+export function parseCommitSha(value: string, field = "commitSha"): CommitSha {
+  return unwrapCorePrimitive(makeCommitSha(value, field));
+}
+
+export function parseGitRef(value: string, field = "gitRef"): GitRef {
+  return unwrapCorePrimitive(makeGitRef(value, field));
+}
+
+export function parseBranchName(value: string, field = "branchName"): BranchName {
+  return unwrapCorePrimitive(makeBranchName(value, field));
+}
+
+export function parseRuntimeChecksum(value: string, field = "runtimeChecksum"): RuntimeChecksum {
+  return unwrapCorePrimitive(makeRuntimeChecksum(value, field));
+}
+
+export function parseRuntimeSchemaName(value: string, field = "runtimeSchemaName"): RuntimeSchemaName {
+  return unwrapCorePrimitive(makeRuntimeSchemaName(value, field));
+}
+
+export function parseGitRunId(value: string, field = "runId"): GitRunId {
+  return unwrapCorePrimitive(makeGitRunId(value, field));
+}
+
+export function parseGitMoveNumber(value: string | number, field = "moveNumber"): GitMoveNumber {
+  return unwrapCorePrimitive(makeGitMoveNumber(value, field));
+}
+
+export function parseGitMoveId(value: string | number, field = "moveId"): GitMoveId {
+  return unwrapCorePrimitive(makeGitMoveId(value, field));
+}
+
+export function parseGitGoal(value: string, field = "goal"): GitGoal {
+  return unwrapCorePrimitive(makeGitGoal(value, field));
+}
+
+export function parseGitPriority(value: string, field = "priority"): GitPriority {
+  return unwrapCorePrimitive(makeGitPriority(value, field));
+}
+
+export function parseGitTrailerRole(value: string, field = "role"): GitTrailerRole {
+  return unwrapCorePrimitive(makeGitTrailerRole(value, field));
+}
+
+export function parseGitTrailerActor(value: string, field = "actor"): GitTrailerActor {
+  return unwrapCorePrimitive(makeGitTrailerActor(value, field));
+}
+
+export function parseGitHunsuId(value: string, field = "hunsuId"): GitHunsuId {
+  return unwrapCorePrimitive(makeGitHunsuId(value, field));
+}
+
+function unwrapCorePrimitive<T>(result: Result<T, CorePrimitiveError>): T {
+  if (result.ok) {
+    return result.value;
+  }
+  throw new HunsuError(`${result.error.field} ${result.error.message}`);
+}
+
+function makeGitToken<T extends string>(value: unknown, field: string, message: string): Result<CoreBrand<T, string>, CorePrimitiveError> {
+  return typeof value === "string" && value.trim().length > 0 && !/[\0\r\n]/.test(value)
+    ? ok(value as CoreBrand<T, string>)
+    : corePrimitiveError(field, message);
+}
+
+function makeNonEmptyCoreString<T extends string>(value: unknown, field: string, message: string): Result<CoreBrand<T, string>, CorePrimitiveError> {
+  return typeof value === "string" && value.trim().length > 0
+    ? ok(value as CoreBrand<T, string>)
+    : corePrimitiveError(field, message);
+}
+
+function corePrimitiveError(field: string, message: string): Result<never, CorePrimitiveError> {
+  return err({ type: "CorePrimitiveError", field, message });
+}

package/src/trailer.ts

@@ -0,0 +1,79 @@
+import { InvalidTrailerError, MissingTrailerError } from "./errors.ts";
+import type { TrailerMap } from "./model.ts";
+
+const TRAILER_LINE = /^([A-Za-z][A-Za-z0-9-]*):[ \t]*(.*)$/;
+
+export function parseTrailers(message: string): TrailerMap {
+  const lines = message.replace(/\r\n/g, "\n").split("\n");
+  let end = lines.length - 1;
+
+  while (end >= 0 && lines[end].trim() === "") {
+    end -= 1;
+  }
+
+  const trailerLines: string[] = [];
+  for (let index = end; index >= 0; index -= 1) {
+    const line = lines[index];
+    if (line.trim() === "") {
+      break;
+    }
+    if (!TRAILER_LINE.test(line)) {
+      break;
+    }
+    trailerLines.unshift(line);
+  }
+
+  const trailers: TrailerMap = new Map();
+  for (const line of trailerLines) {
+    const match = line.match(TRAILER_LINE);
+    if (!match) {
+      throw new InvalidTrailerError(`Invalid trailer line: ${line}`);
+    }
+    const [, key, value] = match;
+    const values = trailers.get(key) ?? [];
+    values.push(value.trim());
+    trailers.set(key, values);
+  }
+
+  return trailers;
+}
+
+export function getTrailer(trailers: TrailerMap, key: string): string | undefined {
+  const values = trailers.get(key);
+  return values?.[values.length - 1];
+}
+
+export function requireTrailer(trailers: TrailerMap, key: string, commitSha: string): string {
+  const value = getTrailer(trailers, key);
+  if (!value) {
+    throw new MissingTrailerError(commitSha, key);
+  }
+  return value;
+}
+
+export function serializeTrailers(trailers: Record<string, string | number | boolean | undefined>): string {
+  const lines: string[] = [];
+  for (const [key, value] of Object.entries(trailers)) {
+    if (value === undefined) {
+      continue;
+    }
+    lines.push(`${key}: ${String(value)}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatMoveNumber(value: string | number): string {
+  const raw = String(value).trim();
+  if (/^M\d+$/i.test(raw)) {
+    return raw.slice(1).padStart(4, "0");
+  }
+  if (/^\d+$/.test(raw)) {
+    return raw.padStart(4, "0");
+  }
+  return raw;
+}
+
+export function formatMoveId(value: string | number): string {
+  const number = formatMoveNumber(value);
+  return /^M/i.test(number) ? number.toUpperCase() : `M${number}`;
+}