Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

Validate and publish tagged jg release artifacts with license notices

David Zhangb64ee690ac2b
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
new file mode 100644
index 0000000..4c0d59c
--- /dev/null
+++ b/.github/workflows/publish.yml
@@ -0,0 +1,89 @@
+name: Release
+
+on:
+ push:
+ tags: ["v*"]
+
+permissions:
+ contents: read
+
+concurrency:
+ group: npm-release-${{ github.ref }}
+ cancel-in-progress: false
+
+jobs:
+ release:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ id-token: write
+ outputs:
+ version: ${{ steps.package.outputs.version }}
+ integrity: ${{ steps.package.outputs.integrity }}
+ env:
+ NODE_AUTH_TOKEN: ""
+ steps:
+ - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+ with:
+ bun-version: 1.3.14
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+ with:
+ node-version: 22
+ registry-url: https://registry.npmjs.org
+ - name: Install locked development dependencies
+ run: bun install --frozen-lockfile
+ - name: Verify release prerequisites
+ run: bun run verify
+ - name: Test release validation
+ run: node --test test/release.test.mjs
+ - name: Build the release package
+ run: bun run --cwd apps/cli build
+ - name: Pack and validate the selected version
+ id: package
+ env:
+ RELEASE_TAG: ${{ github.ref_name }}
+ run: node scripts/prepare-release.mjs "$RELEASE_TAG" "$RUNNER_TEMP/jevgrep-release"
+ - name: Retain the verified release candidate
+ uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+ with:
+ name: jevgrep-${{ steps.package.outputs.version }}
+ path: ${{ runner.temp }}/jevgrep-release/
+ if-no-files-found: error
+ - name: Exercise the exact tarball in the Node-only runtime
+ env:
+ RELEASE_TARBALL: ${{ steps.package.outputs.tarball }}
+ run: bash scripts/test-installed.sh --prebuilt "$RELEASE_TARBALL"
+ - name: Dry-run publication of the verified tarball
+ env:
+ RELEASE_TARBALL: ${{ steps.package.outputs.tarball }}
+ RELEASE_DIST_TAG: ${{ steps.package.outputs.dist_tag }}
+ run: npm publish "$RELEASE_TARBALL" --access public --tag "$RELEASE_DIST_TAG" --ignore-scripts --dry-run
+ - name: Publish the verified tarball
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+ RELEASE_TARBALL: ${{ steps.package.outputs.tarball }}
+ RELEASE_DIST_TAG: ${{ steps.package.outputs.dist_tag }}
+ run: npm publish "$RELEASE_TARBALL" --access public --tag "$RELEASE_DIST_TAG" --ignore-scripts --provenance
+
+ verify-registry:
+ needs: release
+ runs-on: ubuntu-latest
+ env:
+ NODE_AUTH_TOKEN: ""
+ RELEASE_VERSION: ${{ needs.release.outputs.version }}
+ RELEASE_INTEGRITY: ${{ needs.release.outputs.integrity }}
+ steps:
+ - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+ with:
+ node-version: 22
+ registry-url: https://registry.npmjs.org
+ - name: Retrieve the exact public registry version
+ run: |
+ mkdir -p "$RUNNER_TEMP/jevgrep-registry"
+ npm pack "@dzhng/jevgrep@$RELEASE_VERSION" --ignore-scripts --pack-destination "$RUNNER_TEMP/jevgrep-registry"
+ - name: Match the registry archive to the verified candidate
+ run: node scripts/validate-release.mjs "$RUNNER_TEMP/jevgrep-registry/dzhng-jevgrep-$RELEASE_VERSION.tgz" "v$RELEASE_VERSION" "$RELEASE_INTEGRITY"
+ - name: Install registry bytes fresh and run installed journeys
+ run: bash scripts/test-installed.sh --prebuilt "$RUNNER_TEMP/jevgrep-registry/dzhng-jevgrep-$RELEASE_VERSION.tgz"
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..c92e086
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/apps/cli/package.json b/apps/cli/package.json
index 9660861..5c77e64 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -2,6 +2,7 @@
"name": "@dzhng/jevgrep",
"version": "0.0.0",
"description": "Content-aware source retrieval for coding agents",
+ "license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/dzhng/jevgrep.git",
diff --git a/scripts/RELEASING.md b/scripts/RELEASING.md
new file mode 100644
index 0000000..dfd0979
--- /dev/null
+++ b/scripts/RELEASING.md
@@ -0,0 +1,32 @@
+# Release identity and evidence
+
+A release is selected by the version in `apps/cli/package.json` and an exactly
+matching `vVERSION` tag. The development version `0.0.0` is not publishable through
+this workflow. Stable versions publish to `latest`; prereleases publish to `next`.
+The package is `@dzhng/jevgrep`, and its executable is `jg`.
+
+Complete the official quality confirmation and supported-runtime evidence before
+requesting a release. Ubuntu CI is not native macOS evidence and does not run paid
+model evaluations. The root `bun run verify` command is the common deterministic
+gate. Preparing a workflow or a candidate does not authorize creating a tag or
+publishing a development checkpoint.
+
+The [tag workflow](../.github/workflows/publish.yml) verifies, builds, packs, and
+checks canonical package content before exercising that exact archive through the
+installed Docker journeys. It retains the tarball and manifest as a workflow
+artifact and dry-runs npm publication before publishing those same bytes.
+Configure `NPM_TOKEN` as a repository Actions secret; only the publish step receives
+it as `NODE_AUTH_TOKEN`. Credentials never belong in a committed file.
+
+A separate job fetches the exact registry version, checks its integrity against
+the verified archive, and installs it into a fresh Node-only runtime for the same
+fixture-backed journeys. If registry availability or smoke verification fails
+after publication, rerun the failed registry-verification job; a published version
+is immutable and must not be replaced.
+
+[Package validation](validate-release.mjs) owns the allowed payload and canonical
+asset checks. [The build](build-cli.ts) copies the authored MIT license and
+[collects third-party notices](package-notices.mjs) from emitted bundle inputs.
+[Retained license sources](licenses/README.md) document upstream distribution gaps.
+The archive excludes test fixtures, evaluation evidence, node_modules directories, source maps,
+and repository source. Runtime parser dependencies install from exact npm pins.
diff --git a/scripts/build-cli.ts b/scripts/build-cli.ts
index da6cd9e..5ba2f72 100644
--- a/scripts/build-cli.ts
+++ b/scripts/build-cli.ts
@@ -1,7 +1,9 @@
-import { chmod, cp, mkdir, rm } from "node:fs/promises";
+import { chmod, cp, mkdir, rm, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
+import { bundledNotices } from "./package-notices.mjs";
+
const root = fileURLToPath(new URL("../", import.meta.url));
const out = join(root, "apps/cli/dist");
await rm(out, { recursive: true, force: true });
@@ -11,10 +13,16 @@ const build = await Bun.build({
outdir: join(out, "bin"),
target: "node",
format: "esm",
+ metafile: true,
external: ["web-tree-sitter", "typescript"],
});
if (!build.success) throw new AggregateError(build.logs, "CLI build failed");
await chmod(join(out, "bin/index.js"), 0o755);
+await writeFile(
+ join(out, "THIRD_PARTY_NOTICES.txt"),
+ await bundledNotices(build.metafile!, process.cwd()),
+);
+await cp(join(root, "LICENSE"), join(out, "LICENSE"));
await cp(join(root, "packages/core/assets"), join(out, "assets"), { recursive: true });
const skill = join(out, "skills/jevgrep/SKILL.md");
await mkdir(dirname(skill), { recursive: true });
diff --git a/scripts/licenses/Apache-2.0.txt b/scripts/licenses/Apache-2.0.txt
new file mode 100644
index 0000000..d645695
--- /dev/null
+++ b/scripts/licenses/Apache-2.0.txt
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/scripts/licenses/README.md b/scripts/licenses/README.md
new file mode 100644
index 0000000..26f0bad
--- /dev/null
+++ b/scripts/licenses/README.md
@@ -0,0 +1,11 @@
+# License sources omitted or abbreviated upstream
+
+`provider-utils-5.0.45.LICENSE` is the Vercel AI repository license at
+[the exact provider-utils 5.0.45 tag revision](https://github.com/vercel/ai/blob/08ae5ad05bc12496dd1ffcf64e34419e0831300d/LICENSE).
+That npm package declares Apache-2.0 but omits its license file. The override is
+version-specific so an upgrade cannot silently reuse an unchecked notice.
+
+`Apache-2.0.txt` contains the [Apache Software Foundation's full license terms](https://www.apache.org/licenses/LICENSE-2.0.txt).
+The notice generator retains package copyright notices and includes these terms
+when emitted dependencies use Apache-2.0. Builds read these retained sources;
+there is no build-time or runtime license download.
diff --git a/scripts/licenses/provider-utils-5.0.45.LICENSE b/scripts/licenses/provider-utils-5.0.45.LICENSE
new file mode 100644
index 0000000..6c16c29
--- /dev/null
+++ b/scripts/licenses/provider-utils-5.0.45.LICENSE
@@ -0,0 +1,13 @@
+Copyright 2023 Vercel, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
\ No newline at end of file
diff --git a/scripts/package-notices.mjs b/scripts/package-notices.mjs
new file mode 100644
index 0000000..fc4419a
--- /dev/null
+++ b/scripts/package-notices.mjs
@@ -0,0 +1,69 @@
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+/** Use emitted inputs, so the notice follows the actual bundled dependency graph. */
+export async function bundledNotices(metafile, root) {
+ const packages = new Map();
+ let needsApacheTerms = false;
+ for (const output of Object.values(metafile.outputs)) {
+ for (const [input, contribution] of Object.entries(output.inputs)) {
+ if (!contribution.bytesInOutput || !input.split("/").includes("node_modules")) continue;
+ let directory = dirname(resolve(root, input));
+ while (directory.split("/").includes("node_modules")) {
+ let metadata;
+ try {
+ metadata = JSON.parse(await readFile(resolve(directory, "package.json"), "utf8"));
+ } catch (error) {
+ if (error.code !== "ENOENT") throw error;
+ }
+ if (metadata?.name && metadata.version) {
+ const key = `${metadata.name}@${metadata.version}`;
+ if (!packages.has(key)) {
+ const files = (await readdir(directory, { withFileTypes: true }))
+ .filter(
+ (entry) =>
+ entry.isFile() && /^(?:licen[sc]e|copying|notice)(?:[.-]|$)/i.test(entry.name),
+ )
+ .map((entry) => entry.name)
+ .sort();
+ if (!files.length && key !== "@ai-sdk/[email protected]")
+ throw new Error(`Bundled dependency ${key} has no license file`);
+ if (metadata.license === "Apache-2.0") needsApacheTerms = true;
+ const texts = await Promise.all(
+ files.map(async (file) => {
+ const text = await readFile(resolve(directory, file), "utf8");
+ if (!text.trim()) throw new Error(`Empty license file in ${key}`);
+ return `--- ${file} ---\n${text.trimEnd()}\n`;
+ }),
+ );
+ if (!files.length)
+ texts.push(
+ await readFile(
+ new URL("./licenses/provider-utils-5.0.45.LICENSE", import.meta.url),
+ "utf8",
+ ),
+ );
+ packages.set(
+ key,
+ `=== ${key} (${metadata.license ?? "see license below"}) ===\n${texts.join("\n")}`,
+ );
+ }
+ break;
+ }
+ directory = dirname(directory);
+ }
+ if (!directory.split("/").includes("node_modules"))
+ throw new Error(`No package metadata for bundled input ${input}`);
+ }
+ }
+ if (!packages.size) throw new Error("Bundle metadata contains no dependency licenses");
+ if (needsApacheTerms)
+ packages.set(
+ "Apache License 2.0 terms",
+ `=== Apache License 2.0 terms ===\n${await readFile(new URL("./licenses/Apache-2.0.txt", import.meta.url), "utf8")}`,
+ );
+ return `Third-party notices for bundled JavaScript dependencies\n\n${[...packages]
+ .sort(([a], [b]) => a.localeCompare(b))
+ .map(([, text]) => text)
+ .join("\n")}`;
+}
diff --git a/scripts/prepare-release.mjs b/scripts/prepare-release.mjs
new file mode 100644
index 0000000..07f1e2a
--- /dev/null
+++ b/scripts/prepare-release.mjs
@@ -0,0 +1,39 @@
+import { execFile } from "node:child_process";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { promisify } from "node:util";
+import { releaseIdentity, repository, validateRelease } from "./validate-release.mjs";
+const execute = promisify(execFile);
+try {
+ const [tag, destination] = process.argv.slice(2);
+ if (!tag || !destination)
+ throw new Error("Usage: node scripts/prepare-release.mjs vVERSION output-directory");
+ releaseIdentity(
+ JSON.parse(await readFile(resolve(repository, "apps/cli/package.json"), "utf8")),
+ tag,
+ );
+ const directory = resolve(destination);
+ await mkdir(directory, { recursive: true });
+ const packed = await execute(
+ "npm",
+ ["pack", "./apps/cli", "--json", "--ignore-scripts", "--pack-destination", directory],
+ { cwd: repository, maxBuffer: 8_000_000 },
+ );
+ const entries = JSON.parse(packed.stdout);
+ if (entries.length !== 1 || basename(entries[0].filename) !== entries[0].filename)
+ throw new Error("Expected one package tarball");
+ const result = await validateRelease(resolve(directory, entries[0].filename), tag);
+ await writeFile(
+ resolve(directory, "release-manifest.json"),
+ `${JSON.stringify(result, null, 2)}\n`,
+ );
+ if (process.env.GITHUB_OUTPUT)
+ await appendFile(
+ process.env.GITHUB_OUTPUT,
+ `tarball=${result.tarball}\nversion=${result.version}\ndist_tag=${result.distTag}\nintegrity=${result.integrity}\n`,
+ );
+ console.log(JSON.stringify(result, null, 2));
+} catch (error) {
+ console.log(`Release preparation failed: ${error.message}`);
+ process.exitCode = 1;
+}
diff --git a/scripts/validate-release.mjs b/scripts/validate-release.mjs
new file mode 100644
index 0000000..db015ab
--- /dev/null
+++ b/scripts/validate-release.mjs
@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+const execute = promisify(execFile);
+export const repository = fileURLToPath(new URL("../", import.meta.url));
+
+export function releaseIdentity(metadata, tag) {
+ const version = metadata.version;
+ const match =
+ typeof version === "string" &&
+ /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*))?$/.exec(
+ version,
+ );
+ if (!match || match[4]?.split(".").some((part) => /^\d+$/.test(part) && /^0\d/.test(part)))
+ throw new Error("Release version must be valid SemVer without build metadata");
+ if (version === "0.0.0")
+ throw new Error("Set an intentional release version; 0.0.0 is a development checkpoint");
+ if (tag !== `v${version}`) throw new Error("Tag must equal v plus the CLI package version");
+ if (metadata.name !== "@dzhng/jevgrep") throw new Error("Release package must be @dzhng/jevgrep");
+ if (metadata.bin?.jg !== "./dist/bin/index.js" || Object.keys(metadata.bin).length !== 1)
+ throw new Error("Release must expose only the jg executable");
+ if (metadata.private || metadata.publishConfig?.access !== "public")
+ throw new Error("Release package must be public");
+ if (metadata.license !== "MIT" || metadata.engines?.node !== ">=22")
+ throw new Error("Release must retain MIT and Node >=22 contracts");
+ for (const [name, version] of Object.entries(metadata.dependencies ?? {}))
+ if (!/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(version))
+ throw new Error(`Runtime dependency ${name} must use an exact registry version`);
+ for (const name of ["typescript", "web-tree-sitter"])
+ if (!metadata.dependencies?.[name])
+ throw new Error(`Missing runtime parser dependency ${name}`);
+ return { name: metadata.name, version, distTag: match[4] ? "next" : "latest" };
+}
+
+export async function validateRelease(tarball, tag, root = repository) {
+ tarball = resolve(tarball);
+ if ((await stat(tarball)).size > 32_000_000)
+ throw new Error("Unexpectedly large release archive");
+ const { stdout } = await execute("tar", ["-tzf", tarball], { maxBuffer: 8_000_000 });
+ const files = stdout
+ .trim()
+ .split("\n")
+ .filter((name) => !name.endsWith("/"));
+ if (new Set(files).size !== files.length) throw new Error("Duplicate archive entries");
+ for (const path of files)
+ if (
+ !/^package\/(?:package\.json|README(?:\.md)?|LICENSE|dist\/(?:bin\/index\.js|assets\/(?:tree-sitter-python\.wasm|tree-sitter-python\.LICENSE|README\.md)|skills\/jevgrep\/SKILL\.md|LICENSE|THIRD_PARTY_NOTICES\.txt))$/.test(
+ path,
+ )
+ )
+ throw new Error(`Unexpected published file: ${path}`);
+ const listing = await execute("tar", ["-tvzf", tarball], { maxBuffer: 8_000_000 });
+ if (listing.stdout.split("\n").some((line) => line && !["-", "d"].includes(line[0])))
+ throw new Error("Release archive cannot contain links or special files");
+ const extract = async (path) => {
+ if (!files.includes(`package/${path}`)) throw new Error(`Missing packaged file: ${path}`);
+ return (
+ await execute("tar", ["-xOf", tarball, `package/${path}`], {
+ encoding: "buffer",
+ maxBuffer: 8_000_000,
+ })
+ ).stdout;
+ };
+ const metadata = JSON.parse((await extract("package.json")).toString());
+ const identity = releaseIdentity(metadata, tag);
+ const authored = JSON.parse(await readFile(resolve(root, "apps/cli/package.json"), "utf8"));
+ if (JSON.stringify(releaseIdentity(authored, tag)) !== JSON.stringify(identity))
+ throw new Error("Packed identity differs from authored CLI metadata");
+ const binary = (await extract("dist/bin/index.js")).toString();
+ if (!binary.startsWith("#!/usr/bin/env node\n"))
+ throw new Error("Packed executable must run in Node");
+ for (const [packed, original] of [
+ ["dist/LICENSE", "LICENSE"],
+ ["dist/skills/jevgrep/SKILL.md", "skills/jevgrep/SKILL.md"],
+ ["dist/assets/tree-sitter-python.wasm", "packages/core/assets/tree-sitter-python.wasm"],
+ ["dist/assets/tree-sitter-python.LICENSE", "packages/core/assets/tree-sitter-python.LICENSE"],
+ ])
+ if (!(await extract(packed)).equals(await readFile(resolve(root, original))))
+ throw new Error(`Packaged ${packed} differs from its canonical source`);
+ const notices = (await extract("dist/THIRD_PARTY_NOTICES.txt")).toString();
+ if (
+ !notices.startsWith("Third-party notices for bundled JavaScript dependencies\n") ||
+ !notices.includes("=== ")
+ )
+ throw new Error("Missing bundled dependency license notices");
+ const integrity = `sha512-${createHash("sha512")
+ .update(await readFile(tarball))
+ .digest("base64")}`;
+ return { ...identity, tarball, integrity, files };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ try {
+ const [tarball, tag, expectedIntegrity] = process.argv.slice(2);
+ if (!tarball || !tag)
+ throw new Error(
+ "Usage: node scripts/validate-release.mjs package.tgz vVERSION [expected-integrity]",
+ );
+ const result = await validateRelease(tarball, tag);
+ if (expectedIntegrity && result.integrity !== expectedIntegrity)
+ throw new Error("Registry tarball differs from the verified release artifact");
+ console.log(JSON.stringify(result, null, 2));
+ } catch (error) {
+ console.log(`Release validation failed: ${error.message}`);
+ process.exitCode = 1;
+ }
+}
diff --git a/test/Dockerfile b/test/Dockerfile
index 3a9cf17..446e0f2 100644
--- a/test/Dockerfile
+++ b/test/Dockerfile
@@ -13,6 +13,7 @@ COPY packages/core packages/core
COPY test test
COPY scripts scripts
COPY skills skills
+COPY LICENSE LICENSE
RUN bun scripts/build-cli.ts
RUN mkdir -p /opt/npm-cache && cd apps/cli && npm pack --ignore-scripts --pack-destination /opt && npm install --prefix /opt/npm-warm --cache /opt/npm-cache --ignore-scripts --no-audit --no-fund /opt/dzhng-jevgrep-*.tgz && chmod -R a+rX /opt/npm-cache
ENV npm_config_cache=/opt/npm-cache npm_config_offline=true
diff --git a/test/release.test.mjs b/test/release.test.mjs
new file mode 100644
index 0000000..199e5e9
--- /dev/null
+++ b/test/release.test.mjs
@@ -0,0 +1,134 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { releaseIdentity } from "../scripts/validate-release.mjs";
+const metadata = {
+ name: "@dzhng/jevgrep",
+ version: "1.2.3",
+ bin: { jg: "./dist/bin/index.js" },
+ publishConfig: { access: "public" },
+ license: "MIT",
+ engines: { node: ">=22" },
+ dependencies: { typescript: "5.9.3", "web-tree-sitter": "0.25.10" },
+};
+test("release tags select the authored version and keep prereleases off latest", () => {
+ assert.deepEqual(releaseIdentity(metadata, "v1.2.3"), {
+ name: "@dzhng/jevgrep",
+ version: "1.2.3",
+ distTag: "latest",
+ });
+ assert.equal(
+ releaseIdentity({ ...metadata, version: "1.3.0-rc.1" }, "v1.3.0-rc.1").distTag,
+ "next",
+ );
+ for (const [value, tag] of [
+ [metadata, "v1.2.4"],
+ [{ ...metadata, version: "0.0.0" }, "v0.0.0"],
+ [{ ...metadata, version: "1.2.3-01" }, "v1.2.3-01"],
+ [{ ...metadata, name: "jevgrep" }, "v1.2.3"],
+ [{ ...metadata, bin: { jevgrep: "./dist/bin/index.js" } }, "v1.2.3"],
+ ])
+ assert.throws(() => releaseIdentity(value, tag));
+});
+
+test("bundled notices retain emitted dependency licenses and exclude unbundled modules", async (t) => {
+ const { mkdtemp, mkdir, writeFile, rm } = await import("node:fs/promises");
+ const { tmpdir } = await import("node:os");
+ const { join } = await import("node:path");
+ const root = await mkdtemp(join(tmpdir(), "jg-notices-"));
+ t.after(() => rm(root, { recursive: true, force: true }));
+ const dependency = join(root, "node_modules/example");
+ await mkdir(dependency, { recursive: true });
+ await writeFile(
+ join(dependency, "package.json"),
+ JSON.stringify({ name: "example", version: "1.0.0", license: "MIT" }),
+ );
+ await writeFile(join(dependency, "LICENSE"), "MIT license fixture: preserve this copyright.\n");
+ const { bundledNotices } = await import("../scripts/package-notices.mjs");
+ const text = await bundledNotices(
+ {
+ outputs: {
+ "index.js": {
+ inputs: {
+ "node_modules/example/index.js": { bytesInOutput: 10 },
+ "node_modules/removed/index.js": { bytesInOutput: 0 },
+ "src/index.ts": { bytesInOutput: 50 },
+ },
+ },
+ },
+ },
+ root,
+ );
+ assert.ok(text.includes("[email protected]"));
+ assert.ok(text.includes("MIT license fixture: preserve this copyright.\n"));
+ assert.ok(!text.includes("removed"));
+ await rm(join(dependency, "LICENSE"));
+ await assert.rejects(
+ bundledNotices(
+ {
+ outputs: {
+ "index.js": { inputs: { "node_modules/example/index.js": { bytesInOutput: 10 } } },
+ },
+ },
+ root,
+ ),
+ /license/i,
+ );
+});
+
+test("archive validation rejects changed skill bytes and accidental source payloads", async (t) => {
+ const { mkdtemp, mkdir, writeFile, rm, cp, chmod } = await import("node:fs/promises");
+ const { tmpdir } = await import("node:os");
+ const { join } = await import("node:path");
+ const { execFile } = await import("node:child_process");
+ const { promisify } = await import("node:util");
+ const execute = promisify(execFile),
+ root = await mkdtemp(join(tmpdir(), "jg-release-"));
+ t.after(() => rm(root, { recursive: true, force: true }));
+ const files = {
+ "apps/cli/package.json": JSON.stringify(metadata),
+ LICENSE: "MIT canonical copyright\n",
+ "skills/jevgrep/SKILL.md": "Use jg for unfamiliar code.\n",
+ "packages/core/assets/tree-sitter-python.wasm": "fixture wasm",
+ "packages/core/assets/tree-sitter-python.LICENSE": "fixture grammar license",
+ };
+ for (const [path, text] of Object.entries(files)) {
+ await mkdir(join(root, path, ".."), { recursive: true });
+ await writeFile(join(root, path), text);
+ }
+ const archiveRoot = join(root, "archive"),
+ pkg = join(archiveRoot, "package");
+ await mkdir(join(pkg, "dist/bin"), { recursive: true });
+ await mkdir(join(pkg, "dist/skills/jevgrep"), { recursive: true });
+ await mkdir(join(pkg, "dist/assets"), { recursive: true });
+ for (const [from, to] of [
+ ["apps/cli/package.json", "package.json"],
+ ["LICENSE", "dist/LICENSE"],
+ ["skills/jevgrep/SKILL.md", "dist/skills/jevgrep/SKILL.md"],
+ ["packages/core/assets/tree-sitter-python.wasm", "dist/assets/tree-sitter-python.wasm"],
+ ["packages/core/assets/tree-sitter-python.LICENSE", "dist/assets/tree-sitter-python.LICENSE"],
+ ])
+ await cp(join(root, from), join(pkg, to));
+ await writeFile(join(pkg, "dist/bin/index.js"), '#!/usr/bin/env node\nconsole.log("jg");\n');
+ await chmod(join(pkg, "dist/bin/index.js"), 0o755);
+ await writeFile(
+ join(pkg, "dist/THIRD_PARTY_NOTICES.txt"),
+ "Third-party notices for bundled JavaScript dependencies\n\n=== [email protected] (MIT) ===\nFixture license\n",
+ );
+ const tarball = join(root, "package.tgz"),
+ pack = () => execute("tar", ["-czf", tarball, "-C", archiveRoot, "package"]);
+ const { validateRelease } = await import("../scripts/validate-release.mjs");
+ await pack();
+ assert.equal((await validateRelease(tarball, "v1.2.3", root)).version, "1.2.3");
+ await writeFile(join(pkg, "dist/skills/jevgrep/SKILL.md"), "Changed skill");
+ await pack();
+ await assert.rejects(validateRelease(tarball, "v1.2.3", root), /canonical source/);
+ await cp(join(root, "skills/jevgrep/SKILL.md"), join(pkg, "dist/skills/jevgrep/SKILL.md"));
+ await writeFile(join(pkg, "dist/assets/customer-data.json"), "Do not publish");
+ await pack();
+ await assert.rejects(validateRelease(tarball, "v1.2.3", root), /Unexpected published file/);
+ await rm(join(pkg, "dist/assets/customer-data.json"));
+ await mkdir(join(pkg, "evals"));
+ await writeFile(join(pkg, "evals/personal.txt"), "Do not publish");
+ await pack();
+ await assert.rejects(validateRelease(tarball, "v1.2.3", root), /Unexpected published file/);
+});
diff --git a/test/runtime.Dockerfile b/test/runtime.Dockerfile
index 2ca4e54..0c6fb60 100644
--- a/test/runtime.Dockerfile
+++ b/test/runtime.Dockerfile
@@ -11,7 +11,9 @@ COPY packages/typescript-config packages/typescript-config
RUN bun install --frozen-lockfile
COPY apps/cli apps/cli
COPY packages/core packages/core
-COPY scripts/build-cli.ts scripts/build-cli.ts
+COPY scripts/build-cli.ts scripts/package-notices.mjs scripts/
+COPY scripts/licenses scripts/licenses
+COPY LICENSE LICENSE
COPY skills skills
RUN bun run --cwd apps/cli build \
&& mkdir -p /artifacts \