@gjuoun/ast-outline

npm binary distribution of ast-outline — install the ast-outline CLI as an npm dependency. No system install, no postinstall script, no runtime download, and no Python, uv or pip on the target machine: each platform package ships a self-contained frozen executable.

Use it when your tool, CLI or agent needs ast-outline (tree-sitter based code outlines, symbol extraction and structural grep) on a machine where it is not installed — lean clients, containers, CI, remote hosts. npm install is the only setup step.

Install

npm install @gjuoun/ast-outline
# or
bun add @gjuoun/ast-outline

npm installs exactly one platform package matching your os/cpu (and, on Linux, libc) through optionalDependencies; nothing is downloaded at runtime.

Usage

Get the binary path

import { astOutlinePath } from "@gjuoun/ast-outline";

console.log(astOutlinePath);
// → /path/to/node_modules/@gjuoun/ast-outline-darwin-arm64/bin/ast-outline

Run ast-outline from your code

import { spawnSync } from "node:child_process";
import { astOutlinePath } from "@gjuoun/ast-outline";

const outline = spawnSync(astOutlinePath, ["outline", "src/index.ts"], {
  encoding: "utf8",
});
console.log(outline.stdout); // signature-level outline with line numbers

const symbol = spawnSync(astOutlinePath, ["show", "src/index.ts", "main"], {
  encoding: "utf8",
});

CommonJS works too

const { astOutlinePath } = require("@gjuoun/ast-outline");

API

export const astOutlinePath: string;

| Export | Type | Description | |---|---|---| | astOutlinePath | string | Absolute path to the ast-outline executable for the current platform, resolved with require.resolve against the matching platform package. |

Throws Error at import time when the current platform has no build, or when the matching platform package is missing. Both messages name the expected package and the npm install -O <pkg> fix; the Linux hint points at the -musl variant on glibc hosts, and vice versa.

Platform packages

| Package | os | cpu | libc | CI runner | |---|---|---|---|---| | @gjuoun/ast-outline-darwin-arm64 | darwin | arm64 | — | macos-14 | | @gjuoun/ast-outline-linux-x64 | linux | x64 | glibc | ubuntu-22.04 | | @gjuoun/ast-outline-linux-x64-musl | linux | x64 | musl | ubuntu-22.04 + python:3.12-alpine | | @gjuoun/ast-outline-linux-arm64 | linux | arm64 | glibc | ubuntu-24.04-arm | | @gjuoun/ast-outline-linux-arm64-musl | linux | arm64 | musl | ubuntu-24.04-arm + python:3.12-alpine |

Musl hosts (Alpine, node:alpine) are detected at import time and resolve to the -musl package; the libc hint in the error message covers npm versions that ignore the libc field.

Not built: win32-* and darwin-x64. Windows would need a bin/ast-outline.exe launcher and a win32 branch in the resolver; Intel macOS has no supported CI runner left. Both are additive changes to the resolver plus one matrix entry.

Development

Binaries are not committed. Each platform package is produced by packaging/build.sh, which installs the pinned upstream release into a throwaway virtualenv and freezes it with PyInstaller:

bun install         # workspace links for platform/* packages
bun run build       # freeze + stage the host platform into platform/<pkg>/bin
bun test            # resolver, executable and pipeline tests
bun run pack-check  # npm pack every package and assert the result

bun run build needs uv (preferred) or a python3 with venv. Build metadata lives in one place:

• versions.json — upstream tag/commit, Python and PyInstaller pins, CI runner per platform, and the staged launcher sha256.
• platform/*/package.json — os/cpu/libc constraints.
• .github/workflows/release.yml — matrix derived from versions.json by bun scripts/ci-matrix.ts.

Build shape

The bundle is PyInstaller onedir, not onefile. Measured on macOS arm64, a onefile build re-extracts its ~56 MB archive on every invocation (~5 s per run); onedir starts in ~60 ms and its first-run cost is a one-time macOS verification of the freshly written shared libraries. The bundle contents are copied into a platform package so the executable lands at the stable path bin/ast-outline, with bin/_internal/ holding CPython, the tree-sitter grammar bindings and the stdlib.

Publishing

Publishing is manual because npm requires a 2FA one-time code per publish.

0. One-time repo setup (CI needs a remote and a committed lockfile):

git init && git add -A && git commit -m "feat: @gjuoun/ast-outline packaging"
git remote add origin [email protected]:gjuoun/ast-outline.git
git push -u origin main

1. Run the release workflow (Actions → release → Run workflow) and wait for the pack + verify job to pass.
2. Fetch the verified tarballs (or reproduce them locally after downloading every platform artifact into dist/artifacts/):

gh run download <run-id> -n npm-tarballs -D dist/tarballs
# alternative, from per-platform artifacts:
gh run download <run-id> -D dist/artifacts
bun scripts/stage.ts --artifacts dist/artifacts --record
bun scripts/pack-check.ts

3. Publish the platform packages first, then the main package:

npm publish dist/gjuoun-ast-outline-darwin-arm64-1.9.0.tgz
npm publish dist/gjuoun-ast-outline-linux-x64-1.9.0.tgz
npm publish dist/gjuoun-ast-outline-linux-x64-musl-1.9.0.tgz
npm publish dist/gjuoun-ast-outline-linux-arm64-1.9.0.tgz
npm publish dist/gjuoun-ast-outline-linux-arm64-musl-1.9.0.tgz
npm publish dist/gjuoun-ast-outline-1.9.0.tgz

Provenance and attribution

The published packages redistribute a frozen build of ast-outline v1.9.0 (commit e17982960cdf0893236eeb9f7002f9098459d8bc), unmodified.

• ast-outline — Copyright 2026 Dmitrii Zaitsev (dim-s) and ast-outline contributors, licensed under the Apache License 2.0. See LICENSE and NOTICE; the MIT text of the 0.5.x tree is retained in LICENSE-MIT.
• Documentation and CLI prose — the upstream command help strings, guides and agent prompts embedded in the frozen executable are licensed CC BY 4.0; see LICENSE-DOCS. No upstream prose is reproduced in this repository's own documentation.
• Every platform package carries these license texts alongside the binary so attribution travels with the redistributed work.

This npm distribution (lib/, scripts/, packaging/, workflow and docs) is separate packaging work by Jun Guo and is not affiliated with the ast-outline project.

License

Apache-2.0 © Jun Guo; bundled binaries are © the ast-outline contributors under the same license.