@keelcode-ai/keelcode 0.1.3-win32-x64 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to Keelcode will be documented in this file.
+
+The format is based on Keep a Changelog, and this project follows Semantic
+Versioning.
+
+## [Unreleased]
+
+### Added
+
+- Add `kc`, `kcode`, and `keel` as packaged aliases for the `keelcode` command.
+- Add safe custom command aliases with `keelcode alias setup|add|list|remove`.
+- Show client-observed TTFT and provider-token TPS in interactive and headless
+  output without mixing tool time into model throughput; keep interactive
+  context and performance telemetry immediately above the input box.
+- Make the CLI hosted-only: `keelcode login` now owns the API origin and bearer
+  session, while customer provider keys, custom endpoints, and `ANTHROPIC_*`
+  transport configuration are ignored.
+- Add `/ship`, an objective-bound deliverable workflow whose runtime withholds
+  completion until a persisted passing `Verify` receipt, a read-only final
+  review, the cited receipt ID, and a stabilized Git fingerprint all agree.
+- Discover layered `AGENTS.md` and `KEELCODE.md` instructions from the Git root
+  to the active directory with source provenance and bounded, symlink-safe reads.
+- Add stable `json` and streaming `jsonl` headless output formats with explicit
+  terminal outcomes and automation-friendly exit codes.
+- Add lease-checked detached Git worktree primitives for repository-state
+  isolation without claiming operating-system sandboxing.
+- Add standalone `proof list/show` and `worktree create/status/cleanup` commands
+  so automation can inspect receipts and manage isolated runs without an API key.
+- Add an opt-in-aware World Cup match surface with a startup Match Centre,
+  compact in-session scores, scorer-specific goal takeovers, and `/football`
+  controls. Live provider traffic stays in the Keelcode backend.
+
+### Security
+
+- Treat checked-in `.keelcode/settings.json` and `.keelcode/settings.local.json`
+  as untrusted input: repositories can add restrictions and presentation
+  preferences, but cannot enable prompt-free modes, auto-allow tools, inject
+  environment variables, or launch MCP processes.
+- Store explicitly approved per-project MCP and allow settings in an owner-only
+  directory outside the checkout, and pass MCP processes a minimal environment
+  instead of every credential held by the CLI.
+- Require an explicit permission decision for filesystem access outside the
+  active workspace, including symbolic-link escapes, and make delegated agents
+  inherit the parent permission gate and deny rules.
+- Pin each WebFetch HTTPS connection to the public address that was validated,
+  revalidating every redirect to prevent DNS-rebinding SSRF.
+- Require approval for Git commands that write through `--output` or `-o`.
+- Redact and cap persisted verification output, store receipts and worktree
+  leases with owner-only POSIX permissions, and bound gate count and execution time.
+- Make Verify approvals fully scrollable and auditable, hard-limit observed
+  output, show exact executable command text, reject destructive checks and
+  common background syntax, detect residual children, and anchor local receipt
+  bytes per ship run.
+- Hash actual tracked/untracked worktree bytes and submodules independently of
+  Git stat-cache, filter, assume-unchanged, and skip-worktree behavior; isolate
+  Git subprocesses from ambient `GIT_*` injection.
+- Reject symlinked private receipt roots and revalidate directory/file identity
+  across receipt publication and reads.
+- Block WebFetch access to unsafe URL schemes, credentials, local/private
+  networks, and unsafe redirect targets.
+- Store user transcripts, mission artifacts, caches, and crash logs with
+  owner-only POSIX permissions.
+- Clarify that `bypassPermissions` is an explicit no-prompt mode while deny
+  rules and tool hard denials remain enforced.
+
+### Fixed
+
+- Reject Windows UNC paths before POSIX normalization can hide their form.
+- Run the npm launcher with Bun so globally installed commands work on Bun-only
+  machines without a `node` executable.
+- Avoid misclassifying an already-exiting Windows verification child as a
+  residual background process when no process tree was actually terminated.
+
+### Build
+
+- Standardize development, security auditing, packing, and CI on Bun.
+- Replace the unpublished JavaScript npm artifact with a small launcher and
+  exact platform-suffixed versions of the single `keelcode` package name for
+  macOS, Linux, and Windows on x64/arm64.
+- Fail release packing when source files, source maps, private metadata,
+  upstream endpoints, or secret-shaped credentials appear in an npm artifact.

package/README.md

@@ -0,0 +1,220 @@
+# keelcode
+
+Keelcode is a hosted coding agent for your terminal. It can inspect a project,
+edit files, run commands, search the web, use MCP servers, and verify its work.
+
+## Install
+
+Keelcode requires Bun 1.3.14 or newer. It does not require Node.js. Install it
+globally with Bun:
+
+```bash
+bun add --global @keelcode-ai/keelcode
+```
+
+The package provides four equivalent commands:
+
+```text
+keelcode
+kc
+kcode
+keel
+```
+
+To add your own command name after installation, run the guided setup or add
+one or more aliases directly:
+
+```bash
+keelcode alias setup
+keelcode alias add mycode kk
+keelcode alias list
+keelcode alias remove kk
+```
+
+Custom aliases are created beside the package-manager shims. Keelcode refuses
+to overwrite an existing command and never edits shell startup files. Package
+installation stays non-interactive so it remains reliable in terminals, CI,
+containers, and package managers that disable lifecycle scripts.
+
+The `@keelcode-ai/keelcode` npm package is a small launcher that installs the matching
+platform-suffixed version of that same package name for the current operating
+system, CPU, and Linux libc. Keelcode's
+application JavaScript, TypeScript, source maps, tests, and build configuration
+are not included in the public package.
+
+## Sign in and start
+
+```bash
+keelcode login
+keelcode
+```
+
+If the machine cannot open a browser:
+
+```bash
+keelcode login --no-browser
+```
+
+Keelcode will also start sign-in automatically when an interactive session has
+no usable account. Authentication uses a short-lived device approval; provider
+credentials are never stored in the CLI.
+
+Useful account commands:
+
+```bash
+keelcode whoami
+keelcode usage
+keelcode logout
+```
+
+## Everyday use
+
+Start in the current project:
+
+```bash
+keelcode
+```
+
+Run one prompt without opening the TUI:
+
+```bash
+keelcode -p "find and fix the failing test"
+git diff | keelcode -p "review this diff"
+```
+
+Resume work:
+
+```bash
+keelcode -c
+keelcode sessions
+keelcode --resume 2
+```
+
+Choose a model at launch:
+
+```bash
+keelcode --model <model-alias>
+```
+
+Inside the TUI, use `/models` to open the current model picker and `/usage` to
+see the remaining hosted allowance. Run `/help` for the complete command list.
+The footer reports client-observed `ttft` and `tps` for the latest model turn.
+TTFT includes network and gateway latency; TPS uses provider-reported output
+tokens and excludes tool execution. A dash is shown when the stream does not
+contain enough timing or usage information for an honest measurement.
+
+Measure local launcher startup:
+
+```bash
+keelcode bench
+keelcode bench --json
+```
+
+The benchmark runs the installed launcher repeatedly, reports median/p90/min/max
+latency, and is useful for comparing terminals, package managers, and releases.
+
+## Common options
+
+```text
+-m, --model <alias>        choose a Keelcode model
+    --permission-mode <m>  default | plan | acceptEdits | bypassPermissions
+    --yolo                 bypass permission prompts in trusted environments
+    --cwd <dir>            set the working directory
+    --icons <set>          unicode | nerd | ascii | auto
+    --no-alt-screen        keep output in the main terminal buffer
+-c, --continue             resume the newest session in this directory
+    --resume [id]          resume by id/index; no argument lists sessions
+-p, --print [prompt]       run one headless prompt
+    --output-format <f>    text | json | jsonl
+-h, --help                 show help
+-v, --version              show the installed version
+```
+
+`bypassPermissions` and `--yolo` remove confirmation prompts for operations
+inside the workspace. Crossing the workspace boundary still requires explicit
+approval and fails closed in headless mode.
+
+## Configuration
+
+Settings merge in this order, with later files winning:
+
+1. `~/.keelcode/settings.json`
+2. `<project>/.keelcode/settings.json` and `settings.local.json` (sanitized,
+   capability-reducing fields only)
+3. trusted per-project overrides under `~/.keelcode/projects/<workspace-hash>/`
+4. command-line flags
+
+Example project configuration:
+
+```json
+{
+  "model": "<model-alias>",
+  "permissionMode": "default",
+  "maxTurns": 100,
+  "timeoutMs": 600000,
+  "permissions": {
+    "ask": ["Bash", "Write", "Edit"],
+    "deny": ["Write(/etc/**)"]
+  }
+}
+```
+
+Committed or in-tree settings cannot enable MCP processes, inject environment
+variables, add allow rules, select `acceptEdits`/`bypassPermissions`, or define
+unknown future capabilities. Explicit per-project choices made through the CLI
+are stored outside the repository. Keelcode does not support bring-your-own-provider keys.
+
+## MCP and skills
+
+Inspect extension health:
+
+```bash
+keelcode doctor
+keelcode mcp list
+keelcode skills list
+keelcode import list
+```
+
+Use `keelcode mcp --help` and `keelcode skills --help` for management commands.
+MCP tools pass through the same permission checks as built-in tools.
+
+## Automation
+
+For scripts and CI, prefer structured headless output:
+
+```bash
+keelcode -p "run the tests and summarize failures" --output-format json
+keelcode -p "review this repository" --output-format jsonl
+```
+
+Human progress is written to stderr. Machine-readable results are written to
+stdout, so redirecting stdout does not mix logs into the protocol.
+Model performance is written to stderr in text mode and included as structured
+`performance` data in JSON/JSONL output.
+
+## Local data and privacy
+
+Keelcode stores account sessions, settings, conversations, caches, and local
+receipts under `~/.keelcode`. Sensitive state uses owner-only permissions on
+supported POSIX systems.
+
+Anonymous product analytics are opt-in and can be controlled at any time:
+
+```bash
+keelcode telemetry status
+keelcode telemetry enable
+keelcode telemetry disable
+```
+
+Do not paste production secrets into prompts or commit `.keelcode` personal
+state to a repository.
+
+## Security
+
+Report suspected vulnerabilities privately to `security@keelcode.ai`. Do not
+include real credentials or unrelated private data in a report.
+
+## License
+
+Keelcode is proprietary software. Installation and use are governed by the
+license included with this package and the applicable Keelcode service terms.

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest published version of Keelcode.
+
+## Reporting a vulnerability
+
+Please do not disclose an unpatched vulnerability publicly. Email
+`security@keelcode.ai` with the affected version, reproduction steps, impact,
+and any suggested mitigation.
+
+Avoid including real API keys, proprietary source code, or other sensitive data
+in a report. We will acknowledge a complete report as soon as practical and
+coordinate disclosure after a fix is available.
+
+## Local data
+
+Keelcode persists conversations, mission records, downloaded skills, model
+metadata, and crash diagnostics under `~/.keelcode` by default. On POSIX systems,
+Keelcode creates its private state directories with mode `0700` and sensitive
+files with mode `0600`. Users remain responsible for securing backups and any
+custom path supplied through `KEELCODE_CONFIG_DIR`.

package/bin/kc.cjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env bun
+'use strict'
+
+const { spawnSync } = require('node:child_process')
+const {
+  lstatSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} = require('node:fs')
+const { createInterface } = require('node:readline')
+const path = require('node:path')
+
+const VERSION = "0.1.3"
+const TARGETS = {
+  "darwin-arm64": {
+    "packageName": "@keelcode-ai/keelcode-darwin-arm64",
+    "packageVersion": "0.1.3-darwin-arm64",
+    "executableName": "keelcode",
+    "ripgrepExecutableName": "rg"
+  },
+  "darwin-x64": {
+    "packageName": "@keelcode-ai/keelcode-darwin-x64",
+    "packageVersion": "0.1.3-darwin-x64",
+    "executableName": "keelcode",
+    "ripgrepExecutableName": "rg"
+  },
+  "linux-arm64": {
+    "packageName": "@keelcode-ai/keelcode-linux-arm64",
+    "packageVersion": "0.1.3-linux-arm64",
+    "executableName": "keelcode",
+    "ripgrepExecutableName": "rg"
+  },
+  "linux-arm64-musl": {
+    "packageName": "@keelcode-ai/keelcode-linux-arm64-musl",
+    "packageVersion": "0.1.3-linux-arm64-musl",
+    "executableName": "keelcode",
+    "ripgrepExecutableName": "rg"
+  },
+  "linux-x64": {
+    "packageName": "@keelcode-ai/keelcode-linux-x64",
+    "packageVersion": "0.1.3-linux-x64",
+    "executableName": "keelcode",
+    "ripgrepExecutableName": "rg"
+  },
+  "linux-x64-musl": {
+    "packageName": "@keelcode-ai/keelcode-linux-x64-musl",
+    "packageVersion": "0.1.3-linux-x64-musl",
+    "executableName": "keelcode",
+    "ripgrepExecutableName": "rg"
+  },
+  "win32-arm64": {
+    "packageName": "@keelcode-ai/keelcode-win32-arm64",
+    "packageVersion": "0.1.3-win32-arm64",
+    "executableName": "keelcode.exe",
+    "ripgrepExecutableName": "rg.exe"
+  },
+  "win32-x64": {
+    "packageName": "@keelcode-ai/keelcode-win32-x64",
+    "packageVersion": "0.1.3-win32-x64",
+    "executableName": "keelcode.exe",
+    "ripgrepExecutableName": "rg.exe"
+  }
+}
+const DEFAULT_ALIASES = ['keelcode', 'kc', 'kcode', 'keel']
+const ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,31}$/u
+const WINDOWS_ALIAS_MARKER = 'REM keelcode-managed-alias'
+
+function detectTargetId() {
+  const platform = process.platform
+  const arch = process.arch
+  if (platform === 'linux') {
+    let glibc = false
+    try {
+      glibc = Boolean(process.report && process.report.getReport().header.glibcVersionRuntime)
+    } catch {}
+    return 'linux-' + arch + (glibc ? '' : '-musl')
+  }
+  return platform + '-' + arch
+}
+
+function fail(message) {
+  process.stderr.write('keelcode: ' + message + '\n')
+  process.exit(1)
+}
+
+function pathEntryExists(filename) {
+  try {
+    lstatSync(filename)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function commandCandidates(directory, name) {
+  if (process.platform !== 'win32') return [path.join(directory, name)]
+  return ['.exe', '.cmd', '.ps1', ''].map((extension) => path.join(directory, name + extension))
+}
+
+function findLauncherBinDirectory() {
+  const launcher = realpathSync(__filename)
+  let windowsFallback
+  for (const directory of (process.env.PATH || '').split(path.delimiter).filter(Boolean)) {
+    for (const name of DEFAULT_ALIASES) {
+      for (const candidate of commandCandidates(directory, name)) {
+        if (!pathEntryExists(candidate)) continue
+        if (process.platform !== 'win32') {
+          try {
+            if (realpathSync(candidate) === launcher) return { directory, command: path.basename(candidate) }
+          } catch {}
+          continue
+        }
+
+        windowsFallback ||= { directory, command: path.basename(candidate) }
+        if (!/\.(?:cmd|ps1)$/iu.test(candidate)) continue
+        try {
+          const shim = readFileSync(candidate, 'utf8').replaceAll('\\', '/')
+          const expected = __filename.replaceAll('\\', '/')
+          if (shim.includes(expected) || shim.includes('node_modules/keelcode/bin/keelcode.cjs')) {
+            return { directory, command: path.basename(candidate) }
+          }
+        } catch {}
+      }
+    }
+  }
+  if (windowsFallback) return windowsFallback
+  fail('could not find the active package-manager bin directory on PATH')
+}
+
+function validateAliasName(name) {
+  if (DEFAULT_ALIASES.includes(name)) fail('"' + name + '" is a built-in alias and cannot be changed')
+  if (!ALIAS_PATTERN.test(name)) {
+    fail('alias "' + name + '" must start with a lowercase letter and contain only lowercase letters, digits, - or _ (32 characters max)')
+  }
+}
+
+function aliasConflicts(directory, name) {
+  return commandCandidates(directory, name).some(pathEntryExists)
+}
+
+function addAliases(names) {
+  const aliases = [...new Set(names)]
+  if (aliases.length === 0) fail('usage: keelcode alias add <name> [name...]')
+  for (const name of aliases) validateAliasName(name)
+
+  const location = findLauncherBinDirectory()
+  for (const name of aliases) {
+    if (aliasConflicts(location.directory, name)) {
+      fail('refusing to overwrite existing command "' + name + '" in ' + location.directory)
+    }
+  }
+
+  const created = []
+  try {
+    for (const name of aliases) {
+      if (process.platform === 'win32') {
+        const target = path.join(location.directory, location.command)
+        if (!/\.(?:exe|cmd)$/iu.test(target)) {
+          fail('the active Windows package-manager shim is not compatible with custom aliases')
+        }
+        const destination = path.join(location.directory, name + '.cmd')
+        const body = '@echo off\r\n' + WINDOWS_ALIAS_MARKER + '\r\n"%~dp0' + path.basename(target) + '" %*\r\n'
+        writeFileSync(destination, body, { flag: 'wx', mode: 0o755 })
+        created.push(destination)
+      } else {
+        const destination = path.join(location.directory, name)
+        symlinkSync(location.command, destination)
+        created.push(destination)
+      }
+    }
+  } catch (error) {
+    for (const filename of created.reverse()) {
+      try { unlinkSync(filename) } catch {}
+    }
+    fail(error instanceof Error ? error.message : String(error))
+  }
+
+  process.stdout.write('Added custom alias' + (aliases.length === 1 ? '' : 'es') + ': ' + aliases.join(', ') + '\n')
+}
+
+function managedAliases(location) {
+  const aliases = new Set()
+  for (const entry of readdirSync(location.directory)) {
+    if (process.platform === 'win32') {
+      if (!entry.toLowerCase().endsWith('.cmd')) continue
+      const name = entry.slice(0, -4)
+      if (DEFAULT_ALIASES.includes(name) || !ALIAS_PATTERN.test(name)) continue
+      try {
+        if (readFileSync(path.join(location.directory, entry), 'utf8').includes(WINDOWS_ALIAS_MARKER)) aliases.add(name)
+      } catch {}
+      continue
+    }
+
+    if (DEFAULT_ALIASES.includes(entry) || !ALIAS_PATTERN.test(entry)) continue
+    const filename = path.join(location.directory, entry)
+    try {
+      if (lstatSync(filename).isSymbolicLink() && realpathSync(filename) === realpathSync(__filename)) aliases.add(entry)
+    } catch {}
+  }
+  return [...aliases].sort()
+}
+
+function listAliases() {
+  const aliases = managedAliases(findLauncherBinDirectory())
+  process.stdout.write('Built-in aliases: ' + DEFAULT_ALIASES.join(', ') + '\n')
+  process.stdout.write('Custom aliases: ' + (aliases.length > 0 ? aliases.join(', ') : 'none') + '\n')
+}
+
+function removeAliases(names) {
+  const aliases = [...new Set(names)]
+  if (aliases.length === 0) fail('usage: keelcode alias remove <name> [name...]')
+  for (const name of aliases) validateAliasName(name)
+
+  const location = findLauncherBinDirectory()
+  const managed = new Set(managedAliases(location))
+  for (const name of aliases) {
+    if (!managed.has(name)) fail('"' + name + '" is not a Keelcode-managed custom alias')
+  }
+  for (const name of aliases) {
+    unlinkSync(path.join(location.directory, name + (process.platform === 'win32' ? '.cmd' : '')))
+  }
+  process.stdout.write('Removed custom alias' + (aliases.length === 1 ? '' : 'es') + ': ' + aliases.join(', ') + '\n')
+}
+
+function printAliasHelp() {
+  process.stdout.write([
+    'Manage Keelcode command aliases',
+    '',
+    '  keelcode alias setup',
+    '  keelcode alias list',
+    '  keelcode alias add <name> [name...]',
+    '  keelcode alias remove <name> [name...]',
+    '',
+    'Built in: ' + DEFAULT_ALIASES.join(', '),
+    'Names must start with a lowercase letter and use only a-z, 0-9, - or _.',
+    '',
+  ].join('\n'))
+}
+
+async function setupAliases() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    fail('alias setup needs an interactive terminal; use keelcode alias add <name> instead')
+  }
+  process.stdout.write('Built-in aliases are already active: ' + DEFAULT_ALIASES.join(', ') + '\n')
+  const readline = createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await new Promise((resolve) => {
+    readline.question('Custom aliases (comma or space separated; blank to skip): ', resolve)
+  })
+  readline.close()
+  const aliases = String(answer).trim().split(/[\s,]+/u).filter(Boolean)
+  if (aliases.length === 0) {
+    process.stdout.write('No custom aliases added.\n')
+    return
+  }
+  addAliases(aliases)
+}
+
+async function handleAliasCommand(args) {
+  const action = args[0] || 'help'
+  if (action === 'help' || action === '--help' || action === '-h') return printAliasHelp()
+  if (action === 'setup') return setupAliases()
+  if (action === 'list') return listAliases()
+  if (action === 'add') return addAliases(args.slice(1))
+  if (action === 'remove') return removeAliases(args.slice(1))
+  fail('unknown alias action "' + action + '"; use keelcode alias --help')
+}
+
+function launchNative(args) {
+  const targetId = detectTargetId()
+  const target = TARGETS[targetId]
+  if (!target) fail('unsupported platform ' + targetId)
+
+  let manifestPath
+  try {
+    manifestPath = require.resolve(target.packageName + '/package.json')
+  } catch {
+    fail('native package ' + target.packageName + ' is missing; reinstall keelcode@' + VERSION + ' with optional dependencies enabled')
+  }
+
+  let nativeManifest
+  try {
+    nativeManifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch {
+    fail('could not read native package metadata for ' + target.packageName)
+  }
+  if (nativeManifest.name !== '@keelcode-ai/keelcode' || nativeManifest.version !== target.packageVersion) {
+    fail('native package version mismatch: expected @keelcode-ai/keelcode@' + target.packageVersion + ', found ' + (nativeManifest.name || 'unknown') + '@' + (nativeManifest.version || 'unknown'))
+  }
+
+  const packageRoot = path.dirname(manifestPath)
+  const executable = path.join(packageRoot, 'bin', target.executableName)
+  const ripgrep = path.join(packageRoot, 'bin', target.ripgrepExecutableName)
+  for (const [label, filename] of [['native executable', executable], ['ripgrep sidecar', ripgrep]]) {
+    try {
+      if (!statSync(filename).isFile()) throw new Error('not a file')
+    } catch {
+      fail(label + ' is missing from ' + target.packageName + '; reinstall keelcode')
+    }
+  }
+
+  const result = spawnSync(executable, args, {
+    stdio: 'inherit',
+    env: { ...process.env, KEELCODE_RG_PATH: ripgrep },
+    windowsHide: false,
+  })
+  if (result.error) fail(result.error.message)
+  if (result.signal && process.platform !== 'win32') process.kill(process.pid, result.signal)
+  process.exit(result.status === null ? 1 : result.status)
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  if (args[0] === 'alias') {
+    await handleAliasCommand(args.slice(1))
+    return
+  }
+  launchNative(args)
+}
+
+main().catch((error) => fail(error instanceof Error ? error.message : String(error)))