@dannylee1020/kkt 0.5.0

package/internal/workflow/workspace_test.go

@@ -0,0 +1,285 @@
+package workflow
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestStartWorkflowCreatesPlanState(t *testing.T) {
+	root := t.TempDir()
+	workspace, err := StartWorkflow(root, "implement KKT workflow CLI", "plan")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if workspace.Path != filepath.Join(root, ".kkt") {
+		t.Fatalf("Path = %q, want %q", workspace.Path, filepath.Join(root, ".kkt"))
+	}
+	required := []string{"kkt.yaml"}
+	for _, name := range required {
+		if _, err := os.Stat(filepath.Join(workspace.Path, name)); err != nil {
+			t.Fatalf("missing %s: %v", name, err)
+		}
+	}
+	current, err := os.ReadFile(filepath.Join(root, ".kkt", "current"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(current) == 0 {
+		t.Fatal("current pointer is empty")
+	}
+	state, err := os.ReadFile(filepath.Join(workspace.Path, "kkt.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if text := string(state); !strings.Contains(text, "workspace_type: plan") || !strings.Contains(text, "profile: plan") {
+		t.Fatalf("plan state did not use plan profile:\n%s", text)
+	}
+	for _, want := range []string{
+		"planning_contract:",
+		"objective_function:",
+		"files_to_modify:",
+		"constraint_functions:",
+		"decision_variables:",
+		"validation_proof:",
+	} {
+		if !strings.Contains(string(state), want) {
+			t.Fatalf("plan state missing %q:\n%s", want, state)
+		}
+	}
+}
+
+func TestStartWorkflowCreatesModelWorkspace(t *testing.T) {
+	root := t.TempDir()
+	workspace, err := StartWorkflow(root, "choose API shape", "model")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := filepath.Dir(workspace.Path), filepath.Join(root, ".kkt", "model"); got != want {
+		t.Fatalf("workspace parent = %q, want %q", got, want)
+	}
+	required := []string{"kkt.yaml", "intent.md", "discovery.md", "model.md", "guardrails.json"}
+	for _, name := range required {
+		if _, err := os.Stat(filepath.Join(workspace.Path, name)); err != nil {
+			t.Fatalf("missing %s: %v", name, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(workspace.Path, "plan.md")); !os.IsNotExist(err) {
+		t.Fatalf("plan.md should not exist for model workspace: %v", err)
+	}
+	state, err := os.ReadFile(filepath.Join(workspace.Path, "kkt.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if text := string(state); !strings.Contains(text, "active_layer: intent") || !strings.Contains(text, "method: pending") {
+		t.Fatalf("model workspace should start with pending intent:\n%s", text)
+	}
+}
+
+func TestStartWorkflowCreatesLoopWorkspace(t *testing.T) {
+	root := t.TempDir()
+	workspace, err := StartWorkflow(root, "run multi-step migration", "loop")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := filepath.Dir(workspace.Path), filepath.Join(root, ".kkt", "loop"); got != want {
+		t.Fatalf("workspace parent = %q, want %q", got, want)
+	}
+	required := []string{"kkt.yaml", "intent.md", "discovery.md", "model.md", "guardrails.json", "plan.md", "progress.md", "evidence.md", "notes.md", "events.jsonl"}
+	for _, name := range required {
+		if _, err := os.Stat(filepath.Join(workspace.Path, name)); err != nil {
+			t.Fatalf("missing %s: %v", name, err)
+		}
+	}
+	state, err := os.ReadFile(filepath.Join(workspace.Path, "kkt.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if text := string(state); !strings.Contains(text, "loop_state:") || !strings.Contains(text, "acceptance_criteria:") {
+		t.Fatalf("loop state block missing from kkt.yaml:\n%s", text)
+	}
+	if text := string(state); !strings.Contains(text, "active_layer: intent") || !strings.Contains(text, "method_invocations: []") {
+		t.Fatalf("loop workspace should start with pending method selection:\n%s", text)
+	}
+}
+
+func TestStartWorkflowCreatesRunWorkspace(t *testing.T) {
+	root := t.TempDir()
+	workspace, err := StartWorkflow(root, "execute selected model", "run")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := filepath.Dir(workspace.Path), filepath.Join(root, ".kkt", "run"); got != want {
+		t.Fatalf("workspace parent = %q, want %q", got, want)
+	}
+	required := []string{"kkt.yaml", "intent.md", "discovery.md", "model.md", "guardrails.json", "plan.md", "progress.md", "evidence.md", "notes.md"}
+	for _, name := range required {
+		if _, err := os.Stat(filepath.Join(workspace.Path, name)); err != nil {
+			t.Fatalf("missing %s: %v", name, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(workspace.Path, "events.jsonl")); !os.IsNotExist(err) {
+		t.Fatalf("events.jsonl should not exist for run workspace: %v", err)
+	}
+	state, err := os.ReadFile(filepath.Join(workspace.Path, "kkt.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if text := string(state); !strings.Contains(text, "workspace_type: run") || !strings.Contains(text, "guardrails: guardrails.json") {
+		t.Fatalf("run state missing expected contract:\n%s", text)
+	}
+}
+
+func TestResolveWorkspaceUsesCurrentPointer(t *testing.T) {
+	root := t.TempDir()
+	created, err := StartWorkflow(root, "choose API shape", "model")
+	if err != nil {
+		t.Fatal(err)
+	}
+	resolved, err := ResolveWorkspace(root, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resolved != created.Path {
+		t.Fatalf("resolved = %q, want %q", resolved, created.Path)
+	}
+}
+
+func TestStartWorkflowUsesNearestGitRoot(t *testing.T) {
+	root := t.TempDir()
+	if err := os.Mkdir(filepath.Join(root, ".git"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	nested := filepath.Join(root, "packages", "app")
+	if err := os.MkdirAll(nested, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	workspace, err := StartWorkflow(nested, "anchor workspace at project root", "plan")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := workspace.Path, filepath.Join(root, ".kkt"); got != want {
+		t.Fatalf("workspace = %q, want %q", got, want)
+	}
+	if _, err := os.Stat(filepath.Join(nested, ".kkt")); !os.IsNotExist(err) {
+		t.Fatalf("nested .kkt should not exist: %v", err)
+	}
+}
+
+func TestResolveWorkspaceUsesProjectRootFromNestedDirectory(t *testing.T) {
+	root := t.TempDir()
+	if err := os.Mkdir(filepath.Join(root, ".git"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	firstNested := filepath.Join(root, "packages", "app")
+	secondNested := filepath.Join(root, "cmd", "tool")
+	if err := os.MkdirAll(firstNested, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(secondNested, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	created, err := StartWorkflow(firstNested, "choose API shape", "model")
+	if err != nil {
+		t.Fatal(err)
+	}
+	resolved, err := ResolveWorkspace(secondNested, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resolved != created.Path {
+		t.Fatalf("resolved = %q, want %q", resolved, created.Path)
+	}
+}
+
+func TestProjectRootAcceptsGitFile(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, ".git"), []byte("gitdir: ../.git/worktrees/app\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	nested := filepath.Join(root, "src")
+	if err := os.MkdirAll(nested, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	workspace, err := StartWorkflow(nested, "support worktree roots", "plan")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := workspace.Path, filepath.Join(root, ".kkt"); got != want {
+		t.Fatalf("workspace = %q, want %q", got, want)
+	}
+}
+
+func TestProjectRootFallsBackToStartOutsideGit(t *testing.T) {
+	root := t.TempDir()
+	nested := filepath.Join(root, "src")
+	if err := os.MkdirAll(nested, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	resolved, err := projectRoot(nested)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resolved != nested {
+		t.Fatalf("projectRoot = %q, want %q", resolved, nested)
+	}
+}
+
+func TestResolveWorkspaceUsesExplicitPathOutsideProjectRoot(t *testing.T) {
+	root := t.TempDir()
+	if err := os.Mkdir(filepath.Join(root, ".git"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	nested := filepath.Join(root, "src")
+	if err := os.MkdirAll(nested, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	external := t.TempDir()
+	created, err := StartWorkflow(external, "external explicit workspace", "model")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	resolved, err := ResolveWorkspace(nested, created.Path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resolved != created.Path {
+		t.Fatalf("resolved = %q, want %q", resolved, created.Path)
+	}
+}
+
+func TestValidateWorkspaceFailsPendingEvidence(t *testing.T) {
+	root := t.TempDir()
+	workspace, err := StartWorkflow(root, "implement KKT workflow CLI", "loop")
+	if err != nil {
+		t.Fatal(err)
+	}
+	result, err := ValidateWorkspace(workspace.Path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.OK {
+		t.Fatal("ValidateWorkspace should fail while evidence is pending")
+	}
+}
+
+func TestValidateModelWorkspaceDoesNotRequireExecutionFiles(t *testing.T) {
+	root := t.TempDir()
+	workspace, err := StartWorkflow(root, "choose API shape", "model")
+	if err != nil {
+		t.Fatal(err)
+	}
+	result, err := ValidateWorkspace(workspace.Path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !result.OK {
+		t.Fatalf("ValidateWorkspace should accept model workspace, got issues: %v", result.Issues)
+	}
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dannylee1020/kkt",
+  "version": "0.5.0",
+  "description": "KKT constrained-optimization workflow skills and CLI installer for coding agents.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dannylee1020/kkt.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dannylee1020/kkt/issues"
+  },
+  "homepage": "https://github.com/dannylee1020/kkt#readme",
+  "keywords": [
+    "pi-package",
+    "agent-skills",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "opencode",
+    "pi",
+    "kkt"
+  ],
+  "bin": {
+    "kkt-install": "bin/kkt-install.mjs"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://raw.githubusercontent.com/dannylee1020/kkt/main/assets/kkt-readme-modern.png"
+  },
+  "files": [
+    "assets/",
+    "bin/",
+    "cmd/",
+    "internal/",
+    "scripts/",
+    "skills/",
+    "go.mod",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/scripts/install-cli.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+kkt CLI installer
+
+Usage:
+  scripts/install-cli.sh [options]
+  curl -fsSL https://raw.githubusercontent.com/dannylee1020/kkt/main/scripts/install-cli.sh | bash
+  curl -fsSL https://raw.githubusercontent.com/dannylee1020/kkt/main/scripts/install-cli.sh | bash -s -- [options]
+  curl -fsSL <install-cli.sh-url> | KKT_INSTALL_URL=<archive-url> bash -s -- [options]
+
+Installs the Go kkt CLI. KKT skills can use this binary for deterministic
+.kkt state scaffolding, status, next-step hints, and validation.
+
+Options:
+  --bin-dir <path>          Install the kkt CLI here. Defaults to ~/.local/bin.
+  --help                    Show this help.
+
+Environment:
+  KKT_INSTALL_URL           Source archive URL. Defaults to main branch archive.
+  KKT_BINARY_URL            Explicit prebuilt kkt binary URL.
+  KKT_BUILD_FROM_SOURCE     Build the CLI from source without downloading a release binary.
+  KKT_VERSION               GitHub Release tag to install. Defaults to latest.
+EOF
+}
+
+log() {
+  printf '%s\n' "$*" >&2
+}
+
+fail() {
+  printf 'Error: %s\n' "$*" >&2
+  exit 1
+}
+
+need_command() {
+  command -v "$1" >/dev/null 2>&1 || fail "Required command not found: $1"
+}
+
+script_dir() {
+  cd -- "$(dirname -- "$0")" && pwd -P
+}
+
+try_download_file() {
+  local url="$1"
+  local dest="$2"
+
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL "$url" -o "$dest"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -qO "$dest" "$url"
+  else
+    fail "curl or wget is required to download KKT."
+  fi
+}
+
+download_file() {
+  local url="$1"
+  local dest="$2"
+
+  try_download_file "$url" "$dest" || fail "Failed to download $url."
+}
+
+github_release_base_url() {
+  printf '%s\n' "https://github.com/dannylee1020/kkt/releases"
+}
+
+detect_platform() {
+  local os arch
+  os="$(uname -s)"
+  arch="$(uname -m)"
+
+  case "$os" in
+    Darwin) os="darwin" ;;
+    Linux) os="linux" ;;
+    *) return 1 ;;
+  esac
+
+  case "$arch" in
+    x86_64|amd64) arch="amd64" ;;
+    arm64|aarch64) arch="arm64" ;;
+    *) return 1 ;;
+  esac
+
+  printf '%s-%s\n' "$os" "$arch"
+}
+
+default_binary_url() {
+  local platform asset base
+  platform="$(detect_platform)" || return 1
+  asset="kkt-$platform"
+  base="$(github_release_base_url)"
+
+  if [ -n "${KKT_VERSION:-}" ]; then
+    printf '%s/download/%s/%s\n' "$base" "$KKT_VERSION" "$asset"
+  else
+    printf '%s/latest/download/%s\n' "$base" "$asset"
+  fi
+}
+
+default_archive_url() {
+  if [ -n "${KKT_VERSION:-}" ]; then
+    printf '%s\n' "https://github.com/dannylee1020/kkt/archive/refs/tags/${KKT_VERSION}.tar.gz"
+    return
+  fi
+  printf '%s\n' "https://github.com/dannylee1020/kkt/archive/refs/heads/main.tar.gz"
+}
+
+extract_archive() {
+  local archive="$1"
+  local dest="$2"
+
+  need_command tar
+  mkdir -p "$dest"
+  tar -xzf "$archive" -C "$dest" --strip-components 1
+}
+
+resolve_root() {
+  if [ -f "$0" ] && [ "$0" != "bash" ] && [ "$0" != "sh" ]; then
+    local dir
+    dir="$(script_dir)"
+    for root in "$dir" "$dir/.."; do
+      if [ -f "$root/cmd/kkt/main.go" ] && [ -d "$root/internal/workflow" ]; then
+        cd -- "$root"
+        pwd -P
+        return
+      fi
+    done
+  fi
+
+  local install_url tmp_dir archive
+  install_url="${KKT_INSTALL_URL:-$(default_archive_url)}"
+  tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/kkt-cli-install.XXXXXX")"
+  archive="$tmp_dir/kkt.tar.gz"
+  download_file "$install_url" "$archive"
+  log "source: downloaded $install_url"
+  extract_archive "$archive" "$tmp_dir/src"
+  printf '%s\n' "$tmp_dir/src"
+}
+
+expand_home() {
+  case "$1" in
+    \~) printf '%s\n' "$HOME" ;;
+    \~/*) printf '%s/%s\n' "$HOME" "${1#~/}" ;;
+    *) printf '%s\n' "$1" ;;
+  esac
+}
+
+parse_args() {
+  bin_dir="${KKT_BIN_DIR:-$HOME/.local/bin}"
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --bin-dir)
+        [ "$#" -ge 2 ] || fail "--bin-dir requires a value."
+        bin_dir="$(expand_home "$2")"
+        shift 2
+        ;;
+      --help)
+        usage
+        exit 0
+        ;;
+      *)
+        fail "Unknown argument: $1"
+        ;;
+    esac
+  done
+}
+
+install_cli() {
+  local kkt_command binary_url build_from_source root
+  kkt_command="$(expand_home "$bin_dir")/kkt"
+  build_from_source="${KKT_BUILD_FROM_SOURCE:-}"
+  binary_url="${KKT_BINARY_URL:-}"
+  if [ -z "$binary_url" ] && [ "$build_from_source" != "1" ] && [ "$build_from_source" != "true" ]; then
+    binary_url="$(default_binary_url || true)"
+  fi
+
+  mkdir -p "$(dirname "$kkt_command")"
+
+  if [ -n "$binary_url" ]; then
+    log "cli: downloading $binary_url"
+    if try_download_file "$binary_url" "$kkt_command"; then
+      chmod +x "$kkt_command"
+      log "cli: downloaded $kkt_command"
+      return
+    fi
+    rm -f "$kkt_command"
+    log "cli: prebuilt unavailable $binary_url"
+  fi
+
+  if command -v go >/dev/null 2>&1; then
+    root="$(resolve_root)"
+    log "cli: building $kkt_command"
+    (cd "$root" && go build -ldflags="-X github.com/dannylee1020/kkt/internal/workflow.Version=${KKT_VERSION:-dev}" -o "$kkt_command" ./cmd/kkt)
+  else
+    fail "Could not install kkt CLI: prebuilt binary unavailable and Go is not installed."
+  fi
+
+  log "cli: built $kkt_command"
+}
+
+main() {
+  parse_args "$@"
+  install_cli
+}
+
+main "$@"