threadnote 0.1.0

package/docs/troubleshooting.md

@@ -0,0 +1,107 @@
+# Troubleshooting
+
+## `openviking-server` Missing
+
+Run:
+
+```bash
+threadnote install
+```
+
+The installer prefers `pipx`, then `uv`, then `python3 -m pip install --user`.
+
+## Local Embedding Extra Missing
+
+The default OpenViking config uses the local embedding backend. If the server log says `llama-cpp-python` is missing,
+rerun:
+
+```bash
+threadnote install
+```
+
+The installer repairs this by installing `openviking[local-embed]`.
+
+## Server Health Fails
+
+Check whether the server is running:
+
+```bash
+curl http://127.0.0.1:1933/health
+```
+
+For detached starts, logs are written to:
+
+```text
+~/.openviking/logs/server.log
+```
+
+## Port Already In Use
+
+The default bind address is `127.0.0.1:1933`. This does not conflict with projects serving `localhost:80`,
+`localhost:443`, or custom hostnames from `/etc/hosts`; those are different host and port bindings.
+
+If another process already uses port `1933`, pick a different port:
+
+```bash
+THREADNOTE_PORT=1934 threadnote start
+THREADNOTE_PORT=1934 threadnote mcp-install codex --apply
+```
+
+Keep the same port in the agent MCP configuration and in future `threadnote` invocations.
+
+## Seed Skips Files
+
+Skipped files usually matched a secret detector after redaction. Inspect the file manually and either remove the risky
+content or leave it out of the manifest.
+
+## `seed-skills --native` Fails With `[INTERNAL]`
+
+Native OpenViking skill ingestion generates skill overviews with the configured VLM provider. If the server log shows an
+OpenAI quota, rate-limit, or authentication error, run `seed-skills` without `--native`. The default mode stores
+`SKILL.md` files as searchable resources and does not require native skill overview generation.
+
+After changing `~/.openviking/ov.conf`, restart the server:
+
+```bash
+threadnote stop
+threadnote start
+```
+
+## Claude MCP Fails While Health Is OK
+
+OpenViking `0.3.12` can be healthy at `/health` while returning `404` at `/mcp`. That means the stable server does not
+expose the native HTTP MCP endpoint.
+
+Use the default stdio adapter:
+
+```bash
+threadnote mcp-install claude --apply
+claude mcp list
+```
+
+`mcp-install claude` writes user-scoped Claude config by default. This is intentional: local-scoped config only applies
+to one repo/project, and the `threadnote` shim runs the implementation from the checkout that installed it.
+
+Only use `--native-http` with an OpenViking build that actually exposes `/mcp`.
+
+## Worktree Was Deleted
+
+Memories live in `~/.openviking/data`, so deleting a branch or worktree does not delete stored memories. The launcher
+configuration can still point at scripts inside the deleted worktree, though.
+
+From any fresh checkout, run:
+
+```bash
+threadnote repair
+```
+
+`repair` reinstalls the `threadnote` shim, repairs generated config files, starts OpenViking if needed, and rewrites
+Codex/Claude MCP configs to point at the current checkout.
+
+## MCP Install Is Only Printing Commands
+
+This is expected. Run with `--apply` after reviewing the command:
+
+```bash
+threadnote mcp-install codex --apply
+```

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "threadnote",
+  "version": "0.1.0",
+  "type": "commonjs",
+  "main": "dist/threadnote.cjs",
+  "description": "Shared local context and handoffs for development agents",
+  "license": "GPL-3.0-or-later",
+  "homepage": "https://github.com/Kashkovsky/threadnote#readme",
+  "bugs": {
+    "url": "https://github.com/Kashkovsky/threadnote/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kashkovsky/threadnote.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "agent",
+    "context",
+    "handoff",
+    "mcp",
+    "openviking"
+  ],
+  "bin": {
+    "threadnote": "bin/threadnote.cjs",
+    "threadnote-mcp-server": "bin/threadnote-mcp-server.cjs"
+  },
+  "files": [
+    ".threadnoteignore",
+    "bin/",
+    "config/",
+    "dist/",
+    "docs/",
+    "LICENSE",
+    "README.md",
+    "scripts/"
+  ],
+  "scripts": {
+    "build": "npm run clean --silent && esbuild threadnote.ts --bundle --platform=node --format=cjs --target=node20 --outfile=dist/threadnote.cjs && esbuild mcp_server.ts --bundle --platform=node --format=cjs --target=node20 --outfile=dist/mcp_server.cjs",
+    "clean": "rm -rf dist",
+    "dev": "tsx threadnote.ts",
+    "dev:mcp-server": "tsx mcp_server.ts",
+    "prepack": "npm run build",
+    "threadnote": "npm run build --silent && node ./bin/threadnote.cjs",
+    "doctor": "npm run build --silent && node ./bin/threadnote.cjs doctor",
+    "mcp-server": "npm run build --silent && node ./bin/threadnote-mcp-server.cjs",
+    "pack:dry-run": "npm pack --dry-run",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.6.0",
+    "commander": "^14.0.3",
+    "esbuild": "^0.27.7",
+    "js-yaml": "^4.1.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3",
+    "zod": "^4.4.3"
+  }
+}

package/scripts/install.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env sh
+set -eu
+
+PACKAGE="${THREADNOTE_PACKAGE:-threadnote@latest}"
+REGISTRY="${THREADNOTE_NPM_REGISTRY:-https://registry.npmjs.org/}"
+RUNTIME="${THREADNOTE_RUNTIME:-auto}"
+
+say() {
+  printf '%s\n' "$*"
+}
+
+die() {
+  say "ERROR: $*" >&2
+  exit 1
+}
+
+have() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+select_runtime() {
+  case "$RUNTIME" in
+    npm | bun | deno)
+      have "$RUNTIME" || die "$RUNTIME was requested but was not found on PATH."
+      say "$RUNTIME"
+      ;;
+    auto | "")
+      if have npm; then
+        say npm
+      elif have bun; then
+        say bun
+      elif have deno; then
+        say deno
+      else
+        die "Install Node/npm, Bun, or Deno, then rerun this installer."
+      fi
+      ;;
+    *)
+      die "THREADNOTE_RUNTIME must be npm, bun, deno, or auto."
+      ;;
+  esac
+}
+
+npm_global_bin() {
+  prefix="$(npm prefix --global 2>/dev/null || true)"
+  if [ -n "$prefix" ]; then
+    say "$prefix/bin"
+  fi
+}
+
+bun_global_bin() {
+  bun pm bin -g 2>/dev/null || true
+}
+
+runtime_threadnote_bin() {
+  runtime="$1"
+  dir=""
+  case "$runtime" in
+    npm) dir="$(npm_global_bin)" ;;
+    bun) dir="$(bun_global_bin)" ;;
+    deno) dir="${DENO_INSTALL:-$HOME/.deno}/bin" ;;
+  esac
+  if [ -n "$dir" ]; then
+    say "$dir/threadnote"
+  fi
+}
+
+find_threadnote() {
+  runtime="$1"
+  preferred="$(runtime_threadnote_bin "$runtime")"
+  if [ -n "$preferred" ] && [ -x "$preferred" ]; then
+    say "$preferred"
+    return 0
+  fi
+
+  for dir in "$(npm_global_bin)" "$(bun_global_bin)" "${DENO_INSTALL:-$HOME/.deno}/bin" "$HOME/.local/bin"; do
+    if [ -n "$dir" ] && [ -x "$dir/threadnote" ]; then
+      say "$dir/threadnote"
+      return 0
+    fi
+  done
+
+  if have threadnote; then
+    command -v threadnote
+    return 0
+  fi
+
+  return 1
+}
+
+install_package() {
+  runtime="$1"
+  case "$runtime" in
+    npm)
+      npm install --global "$PACKAGE" --registry="$REGISTRY"
+      ;;
+    bun)
+      bun install --global "$PACKAGE" --registry="$REGISTRY"
+      ;;
+    deno)
+      case "$PACKAGE" in
+        npm:*) deno_package="$PACKAGE" ;;
+        *) deno_package="npm:$PACKAGE" ;;
+      esac
+      NPM_CONFIG_REGISTRY="$REGISTRY" deno install --global --name threadnote \
+        --allow-read --allow-write --allow-run --allow-env --allow-net \
+        "$deno_package"
+      ;;
+  esac
+}
+
+runtime="$(select_runtime)"
+say "Installing $PACKAGE with $runtime from $REGISTRY"
+install_package "$runtime"
+
+threadnote_bin="$(find_threadnote "$runtime")" || die "Installed $PACKAGE, but could not find the threadnote command."
+
+say "Running threadnote install"
+"$threadnote_bin" install "$@"
+
+if ! have threadnote; then
+  say ""
+  say "threadnote is installed, but it is not on PATH in this shell."
+  say "Add ~/.local/bin or your package-manager global bin directory to PATH."
+fi
+
+say ""
+say "Threadnote is installed. Run: threadnote doctor --dry-run"