@skylence-ai/skyline 1.0.31

package/README.md

@@ -0,0 +1,238 @@
+# skyline
+
+[![CI](https://github.com/skylence-be/binary-skyline/actions/workflows/ci.yml/badge.svg)](https://github.com/skylence-be/binary-skyline/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://github.com/skylence-be/binary-skyline/blob/main/LICENSE)
+
+A search-and-edit toolkit that lets AI coding assistants change your code safely. Every edit
+is bound to a content fingerprint and refused if the file changed since it was read, so an
+assistant never silently overwrites your work. Search and refactoring understand code
+structure, not just text.
+
+## Install
+
+The recommended setup is a small always-on background service (a daemon) that your AI client
+talks to. Start it once and every tool call is fast.
+
+<details>
+<summary>Why a daemon instead of a per-call binary?</summary>
+
+- No cold starts: the warm daemon answers a full `tools/list` round-trip in
+  **10 to 40 ms**. A per-session stdio server pays its full startup cost
+  before the first call, every session.
+- Language servers stay warm: the one-time cold index on a ~224k-line workspace
+  took **95 s**; warm calls are **sub-second**. With a daemon that price is paid
+  once per workspace, not once per session.
+- One process for every client: Claude Code, other MCP clients, and scripts all
+  share the same warm state, one audit stream, and one bench stream.
+- The per-session stdio mode works too; it just re-pays startup and indexing in
+  every new session. Numbers: [docs/benchmarks.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/benchmarks.md). Setup for
+  both modes: [docs/install.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/install.md).
+
+</details>
+
+### 1. Install (npm — prebuilt binary, every platform)
+
+```bash
+npm install -g @skylence-ai/skyline
+```
+
+Puts the `skyline` binary on your PATH (macOS arm64/x64, Linux arm64/x64,
+Windows x64/arm64) via the matching `@skylence-ai/skyline-<platform>` optional
+dependency — no native installer or compile step. Alternatives:
+`cargo binstall skyline`, or a prebuilt archive from
+[GitHub Releases](https://github.com/skylence-be/binary-skyline/releases).
+
+### 2. Start the shared background service (pick any free port)
+```bash
+skyline daemon start --port 7333
+```
+
+To survive reboots, register it as an OS service instead: `skyline daemon install --port 7333` (see [docs/install.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/install.md) for details).
+
+### 3. Tell your AI client (here, Claude Code) about it
+```bash
+claude mcp add --scope user --transport http skyline http://127.0.0.1:7333/mcp
+```
+
+Check it is up with `skyline daemon status` (the port should read `running`). That is it.
+
+Other install methods are in [docs/install.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/install.md).
+
+### 4. Prompts for your agent
+
+Paste this into your agent's instructions so it picks the right tool:
+
+```text
+Prefer skyline's MCP tools over your built-in file read, edit, and search tools for all code work, and especially when a skyline HTTP MCP server is registered (a shared, always-warm daemon, so calls stay cheap). If skyline becomes unavailable mid-session (tools dropped from your tool list, connection refused or closed), do NOT silently fall back to your built-in tools: retry once, then pause code work, report the outage to your orchestrator or user, and wait for skyline to be restored before continuing. Use `skyline_tree` to get project shape and orient in an unfamiliar repo (every output line is a plain path you pass straight to `skyline_read`), `skyline_read` to read a file (it returns a `¶path#TAG` anchor; never reconstruct that header by hand, copy it back verbatim), `skyline_grep` for regex/text search, `skyline_sgrep` for structural/AST search, `skyline_edit` to apply hash-guarded line edits using that anchor, `skyline_srewrite` for one-pass structural find-and-replace across a file or directory, and `skyline_format` to run the language formatter (rustfmt, gofmt, prettier) through the audited pipeline; use `skyline_git` for repo status and compressed unstaged diffs (context stripped, each file section headed by a real `¶path#TAG` anchor so you can edit straight from the diff output), and `skyline_test` to run the test suite (failures come back with `¶path#TAG` anchors for direct editing; `exit_code` is authoritative — a nonzero exit with no parsed failures means a build error, consult the raw output path); use `skyline_run` with an argv ARRAY (never a shell string; there is no shell) for any simple command such as git, cargo, docker, gh, or npm (output comes back compressed with the full raw output teed to a temp file and the invocation audited; to run several commands in one round-trip pass `argv_list`, an array of argv arrays, optionally with `parallel: true`, and supply exactly one of `argv` or `argv_list`), falling back to your built-in Bash tool only for compound shell features (pipes, &&, redirection, command substitution); use `skyline_json` to query or reshape JSON without paying tokens for or leaking the values, instead of piping a file through Bash and jq; when the task is about a SYMBOL rather than text, use the semantic tools: `skyline_definition` (where is it defined, starting from a call site), `skyline_references` (every true caller; comments and strings never match), `skyline_rename` (whole-workspace rename, preview with dry_run), `skyline_symbols` (find by name fragment), and `skyline_diagnostics` (does the file still typecheck after an edit; per-file, so use the build tool for whole-project checks); always read (or grep/sgrep) to get a fresh anchor before editing, pass it back unchanged, and if an edit is rejected as stale, re-read to refresh the tag and retry. For observability (off by default): `skyline_observability_status` to see what is enabled, `skyline_observability_set` to toggle the audit/devlog/bench streams, `skyline_audit_tail` and `skyline_log_tail` to read the mutation-audit and diagnostic logs, `skyline_bench_report` for timing aggregates, and `skyline_audit_prune` / `skyline_devlog_prune` / `skyline_bench_prune` to trim them.
+```
+
+Or skip the manual setup entirely and hand your agent this:
+
+```text
+Set up skyline for me: install it with `npm install -g @skylence-ai/skyline` (prebuilt binaries for every platform, incl Windows arm64), install the shared HTTP MCP daemon as a supervised autostart service with `skyline daemon install --port 7333` (so it survives sleep cycles and restarts itself if it dies; plain `skyline daemon start` runs unsupervised and dies with its parent), register it for all my projects with `claude mcp add --scope user --transport http skyline http://127.0.0.1:7333/mcp`, then verify: `skyline daemon status` must show the port as `running`, and `claude mcp list` must show skyline as connected. Do NOT probe the endpoint with raw curl: it is a stateful streamable-HTTP MCP server that requires an initialize handshake, an Accept header for both application/json and text/event-stream, and a session id, so ad-hoc curl calls fail by design; `claude mcp list` is the correct connectivity check, and the tools (e.g. `skyline_version`) become callable in your next session. If the port is taken, pick a free one and redo both the install and add commands with it.
+```
+
+## The numbers
+
+The search result IS the edit handle, so edit cost stays flat (~60 tokens whether the
+file is 300 lines or 10,000). Four blind evaluation rounds, measured with skyline's
+own bench stream:
+
+- Every mid-edit race became a one-line rejection, never a silent overwrite. Two
+  agents editing the same file simultaneously, blind to each other: zero lost
+  updates ([docs/concurrency.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/concurrency.md)).
+- Repo-scale questions answered in one line instead of a match dump.
+- A 404-file rewrite converged in one extra call; the residual report said exactly
+  what remained and why.
+- Under drift, conflicts, and out-of-band edits, a blind agent re-grounded before
+  editing and reconstructed the change history from the audit stream.
+
+| | Built-in read→edit | skyline |
+|---|---|---|
+| One edit in a 10,000-line file | ~83,500 tokens | **~62 tokens** (1,336× less) |
+| Repo-wide structural count (896 Go files) | full match dump, no exact total | **1 line**: `282 matches in 105 files.` |
+| 213-file structural rewrite | no built-in equivalent | **3 calls, ~8.3k tokens**, previewed + hash-guarded |
+
+Measured, not modeled: methodology and full tables in [docs/benchmarks.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/benchmarks.md).
+
+## What problem does this solve?
+
+- **Silent overwrites.** If a file changed after the assistant read it (you saved, a
+  formatter ran), text-matching edits quietly destroy work. skyline fingerprints every
+  read and refuses stale edits.
+- **Text-blind search.** Find-and-replace renames hit comments and strings. skyline
+  rewrites by structure: real calls change, comments stay.
+- **Token bloat.** Read-then-edit costs grow with file size; search returns dumps.
+  skyline replies stay small: ~60-token edits, one-line counts, per-file rewrite
+  summaries. Up to 48% less traffic on combined tasks; one blind run took 14
+  round-trips where built-ins needed ~450.
+- **Cold starts.** The daemon keeps one warm process (and warm language servers) for
+  every client.
+
+## Why it is better
+
+These come from running skyline against real repositories and measuring with its own tools.
+Full detail and the methodology are in [docs/benchmarks.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/benchmarks.md).
+
+- **Safe edits, proven.** When a file changed between read and write, skyline refused the edit
+  rather than overwriting it. A plain string-matching editor has no such guard.
+- **Refactors that respect code.** Rewriting a Go call changed 18 of 18 real call sites and
+  left an identical word inside a comment untouched. A `sed` find-and-replace would have
+  corrupted that comment.
+- **No search penalty.** A controlled query returned the same 66 matches as ripgrep, because
+  skyline uses the same engine and gitignore-aware walk.
+- **No startup tax.** The warm daemon answers in 10 to 40 ms with no per-session startup, while
+  spawning the tool per session costs about a second each time.
+
+## Tools
+
+skyline is one Rust binary with two faces: a command-line tool and an MCP server for AI clients.
+
+| Capability | CLI | MCP tool |
+|------------|-----|----------|
+| Read a file with a content fingerprint | `skyline read` | `skyline_read` |
+| Apply a fingerprint-guarded edit | `skyline edit` | `skyline_edit` |
+| Patch format reference | `skyline preview` | `skyline_format` |
+| Regex search (ripgrep engine) | `skyline grep` | `skyline_grep` |
+| Structural search (ast-grep) | `skyline sgrep` | `skyline_sgrep` |
+| Structural rewrite (ast-grep) | `skyline srewrite` | `skyline_srewrite` |
+| Where a symbol is defined | | `skyline_definition` |
+| Every real caller of a symbol | | `skyline_references` |
+| Rename a symbol everywhere, safely | | `skyline_rename` |
+| Find a symbol by name fragment | | `skyline_symbols` |
+| Does the file still compile after an edit | | `skyline_diagnostics` |
+| Project shape / orientation (tree) | | `skyline_tree` |
+| Git status and compressed diff with anchors | | `skyline_git` |
+| Run tests, failures-only with anchors | | `skyline_test` |
+| Version and tool-manifest digest | `skyline version` | `skyline_version` |
+| Observability streams (audit, devlog, bench) | `skyline audit/devlog/bench` | `skyline_observability_*`, tail and prune tools |
+| Manage the background daemon | `skyline daemon …` | (CLI) |
+| Start the daemon on every boot | `skyline daemon install` | (CLI) |
+| Health check | `skyline doctor` | (CLI) |
+### Understanding code, not just matching text
+
+The five symbol tools (`definition`, `references`, `rename`, `symbols`,
+`diagnostics`) answer questions text search cannot: where a function is really
+defined, who actually calls it (the same word in a comment does not count), and
+how to rename it everywhere in one safe step. skyline does this by talking to
+the same "language brain" your editor uses (a language server). Two things to
+know: that brain is a separate program installed once per language, and skyline
+prints the exact install command if it is missing; and the first question in a
+project takes a few seconds while the brain reads your code, after which answers
+are instant. Setup and details: [docs/lsp.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/lsp.md).
+### Language support
+| Language | Extensions | sgrep/srewrite | LSP (definition, rename...) | Block ops | Test runners |
+|----------|------------|:--------------:|:---------------------------:|:---------:|--------------|
+| Rust | `.rs` | yes | rust-analyzer | yes | cargo-test |
+| Go | `.go` | yes | gopls | yes | go-test |
+| TypeScript | `.ts .tsx .mts .cts` | yes | typescript-language-server | yes | vitest, jest |
+| JavaScript | `.js .jsx .mjs .cjs` | yes | typescript-language-server | yes | vitest, jest |
+| Python | `.py .pyi` | yes | pyright-langserver | yes | pytest |
+| PHP | `.php` | yes | intelephense / phpactor | yes | pest, phpunit |
+| C | `.c .h` | yes | clangd | yes | |
+| C++ | `.cc .cpp .cxx .hh .hpp .hxx` | yes | clangd | yes | |
+| Ruby | `.rb` | yes | ruby-lsp | yes | rspec, rake-test |
+| Java | `.java` | yes | jdtls | yes | |
+| Swift | `.swift` | yes | sourcekit-lsp | yes | swift-test |
+| Kotlin | `.kt .kts` | yes | kotlin-language-server | yes | |
+| HTML | `.html .htm` | yes | | | |
+| JSON | `.json` | yes | | | |
+| YAML | `.yaml .yml` | yes | yaml-language-server | | |
+| CSS | `.css` | yes | | | |
+| Markdown | `.md .mdx .markdown` | | marksman | | |
+Adding a language: [docs/add-a-language.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/add-a-language.md).
+## How it works
+
+`read` prints a file with a `¶path#TAG` header and numbered lines. That header is the edit
+anchor: pass it back verbatim to `edit`. The tag is a 4-hex CRC32 of the normalized content,
+so a changed file produces a different tag and a stale edit is rejected (and recovered via
+3-way merge when possible). `grep` and `sgrep` return the same `¶path#TAG` headers, so search
+output feeds straight into an edit. `srewrite` rewrites by structure in one pass and can
+preview with `--dry-run`.
+
+Details: [edit and patch format](https://github.com/skylence-be/binary-skyline/blob/main/docs/patch-format.md), [grep](https://github.com/skylence-be/binary-skyline/blob/main/docs/grep.md),
+[structural search and rewrite](https://github.com/skylence-be/binary-skyline/blob/main/docs/sgrep.md), [the content tag](https://github.com/skylence-be/binary-skyline/blob/main/docs/content-hash.md),
+[stale-edit recovery](https://github.com/skylence-be/binary-skyline/blob/main/docs/recovery.md).
+
+## Documentation
+
+- [docs/install.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/install.md): all install methods
+- [docs/benchmarks.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/benchmarks.md): benchmarks, findings, and methodology
+- [docs/cli.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/cli.md): full CLI reference, including `daemon`, `doctor`, `version`
+- [docs/mcp.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/mcp.md): MCP server, transports, client config, and tool descriptions
+- [docs/grep.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/grep.md): grep reference (flags, output format, parallelism)
+- [docs/sgrep.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/sgrep.md): structural search and rewrite reference
+- [docs/lsp.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/lsp.md): the semantic tools (definition, references, rename, symbols, diagnostics)
+- [docs/patch-format.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/patch-format.md): patch sections and operations
+- [docs/content-hash.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/content-hash.md): the CRC32 content tag
+- [docs/block-operations.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/block-operations.md): tree-sitter `replace block` / `delete block`
+- [docs/add-a-language.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/add-a-language.md): how to wire a new language into the registry
+- [docs/recovery.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/recovery.md): stale-tag recovery and snapshot storage
+- [docs/observability.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/observability.md): audit, devlog, and bench streams
+- [docs/npm-distribution.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/npm-distribution.md): how skyline ships to npm
+- [AGENTS.md](AGENTS.md): agent-facing conventions
+
+## More benchmarks
+
+From a blind production run (1.0.10, fresh agent, hugo's 896 Go files; all numbers
+from skyline's own `bench` stream):
+
+- All six tasks (a 7-file semantic rename, workspace symbol search, two repo-wide
+  structural counts, a YAML rule diagnosis, and the 213-file rewrite) cost
+  **~16.8k output tokens total**. An earlier release spent 86k on a single rewrite
+  preview alone; the summary preview cut that by ~99.7%.
+- Per-edit cost is **flat against file size**: ~49 tokens on a 292-line file, ~62 on a
+  10,496-line file. The naive read-then-edit flow grows linearly (~2.1k → ~83.5k); even
+  a skilled grep→windowed-read→edit flow runs 12-17× skyline's cost.
+- Batched diagnostics covered 7 renamed files in **one call (~248 tokens)**. The
+  one-time language-server cold index on a ~224k-line workspace took 95 s; warm calls
+  are sub-second.
+- Edit input has held at **~57 tokens p50 across releases**: anchors keep file content
+  out of the edit round-trip entirely.
+
+Full tables, the 1.0.5 safety/parity/transport baselines, and honest caveats:
+[docs/benchmarks.md](https://github.com/skylence-be/binary-skyline/blob/main/docs/benchmarks.md).
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/skylence-be/binary-skyline/blob/main/LICENSE).

package/bin.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+const PLATFORM_PKGS = {
+  "darwin-arm64": "@skylence-ai/skyline-darwin-arm64",
+  "darwin-x64":   "@skylence-ai/skyline-darwin-x64",
+  "linux-arm64":  "@skylence-ai/skyline-linux-arm64",
+  "linux-x64":    "@skylence-ai/skyline-linux-x64",
+  "win32-x64":    "@skylence-ai/skyline-win32-x64",
+  "win32-arm64":  "@skylence-ai/skyline-win32-arm64",
+};
+
+function getBinaryPath() {
+  const arch = process.arch === "arm64" ? "arm64" : "x64";
+  const key = `${process.platform}-${arch}`;
+  const pkg = PLATFORM_PKGS[key];
+  if (!pkg) {
+    throw new Error(
+      `skyline: unsupported platform: ${process.platform} ${process.arch}\n` +
+      `Supported: ${Object.keys(PLATFORM_PKGS).join(", ")}`
+    );
+  }
+  let pkgDir;
+  try {
+    pkgDir = path.dirname(require.resolve(`${pkg}/package.json`));
+  } catch {
+    throw new Error(
+      `skyline: platform package ${pkg} is not installed.\n` +
+      `Run: npm install ${pkg}`
+    );
+  }
+  const ext = process.platform === "win32" ? ".exe" : "";
+  return path.join(pkgDir, `skyline${ext}`);
+}
+
+let binaryPath;
+try {
+  binaryPath = getBinaryPath();
+} catch (err) {
+  process.stderr.write(err.message + "\n");
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@skylence-ai/skyline",
+  "version": "1.0.31",
+  "description": "Content-hash line editor — CLI and MCP server",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skylence-be/binary-skyline"
+  },
+  "bugs": "https://github.com/skylence-be/binary-skyline/issues",
+  "homepage": "https://github.com/skylence-be/binary-skyline#readme",
+  "keywords": [
+    "mcp",
+    "editor",
+    "hash",
+    "search",
+    "ast-grep",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "preferUnplugged": true,
+  "bin": {
+    "skyline": "bin.js"
+  },
+  "optionalDependencies": {
+    "@skylence-ai/skyline-darwin-arm64": "1.0.31",
+    "@skylence-ai/skyline-darwin-x64": "1.0.31",
+    "@skylence-ai/skyline-linux-arm64": "1.0.31",
+    "@skylence-ai/skyline-linux-x64": "1.0.31",
+    "@skylence-ai/skyline-win32-x64": "1.0.31"
+  }
+}