@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/helper-download.d.ts

@@ -1,106 +1,21 @@
-/**
- * Shared on-demand download + verification for the macOS native helper `.app`
- * bundles that ship as signed + notarized GitHub release assets on each helper's
- * OWN tag (`ComputerHelper.app`, `MenubarHelper.app`, `Agents CLI.app`) — see
- * `helper-versions.ts` for why they are no longer keyed to the CLI's tag.
- *
- * A `.app` is a directory, so each asset is a zip (`ditto -c -k --keepParent`);
- * a fresh `npm i -g` machine with no bundled copy fetches the asset for the
- * pinned helper version, verifies its sha256 against the published `.sha256`,
- * then verifies the code signature (Developer ID Team + notarization — and, for
- * the menu-bar helper, its designated requirement) before it is ever installed.
- *
- * `menubar/download-menubar.ts`
- * (MenubarHelper) are thin per-helper wrappers over the primitives here — one
- * download+verify machinery, two specs — so a fix to the verify/download logic
- * lands for both helpers at once.
- */
 import { type HelperName } from './helper-versions.js';
-/**
- * GitHub repo whose `<helper>/v<version>` releases carry the helper assets.
- *
- * This is the SLUG, which is not the npm package name: the package is still
- * `@phnx-labs/agents-cli`, but the repository was renamed to `agi-cli`. The old
- * slug kept working only because GitHub redirects a renamed repo, which is a
- * poor thing to hang signed-binary delivery on — a redirect is one re-created
- * repo away from resolving somewhere else. What actually protects the download
- * is the sha256 + codesign + designated-requirement + Team ID verification
- * below; this just stops relying on the redirect.
- */
 export declare const HELPER_RELEASE_REPO = "phnx-labs/agi-cli";
-/** Apple Developer ID Team every helper must be signed by ("Developer ID
- *  Application: Muqit Nawaz"). Defense in depth on top of `spctl` notarization. */
 export declare const EXPECTED_TEAM_ID = "2HTP252L87";
-/** One helper's identity + verification policy — everything that differs between
- *  the computer helper and the menu-bar helper. */
 export interface HelperSpec {
-    /**
-     * Which helper this is — the key into the independent release train
-     * (`helper-versions.ts`). This is what makes the download URL a function of
-     * the HELPER's version rather than the CLI's.
-     */
     helper: HelperName;
-    /** The zipped `.app` release asset name, e.g. `ComputerHelper.app.zip`. */
     assetName: string;
-    /** The bundle directory name once extracted, e.g. `ComputerHelper.app`. */
     appName: string;
-    /** Cache dir components under `getCacheDir()`, e.g. `['computer', 'mac-helper']`. */
     cacheSubdir: string[];
-    /** Developer ID Team the bundle must be signed by. */
     expectedTeamId: string;
-    /**
-     * When set, the bundle's designated requirement MUST pin this
-     * CFBundleIdentifier in addition to `expectedTeamId`. Used by the menu-bar
-     * helper: macOS keys the Accessibility (TCC) grant to this requirement, so a
-     * substituted bundle whose DR does not pin (id, team) would silently revoke
-     * the user's grant on the next paste. Left undefined for the computer helper,
-     * which has no such upgrade-stable grant to protect (matching its behavior
-     * before this shared primitive existed).
-     */
     expectedBundleId?: string;
-    /** Local-build command named in the "asset missing" error, for a repo checkout. */
     localBuildHint: string;
 }
-/** Cache dir for a downloaded helper, one subdir per release tag. */
 export declare function helperCacheDir(spec: HelperSpec, version: string): string;
-/**
- * Release-asset URLs for one helper build, at that HELPER's own tag.
- *
- * The tag is `<helper>/v<version>` (e.g. `menubar/v1.0.0`), never the CLI's
- * `v<cliVersion>`. Keying these to the CLI tag is what forced every CLI release
- * to re-stage every helper asset, and simultaneously made a helper fix
- * unreachable without a CLI release — see `helper-versions.ts` for the full why.
- *
- * `version` is a HELPER version. Passing a CLI version here yields a tag that
- * does not exist; callers default it from {@link helperFloor}.
- */
 export declare function helperAssetUrls(spec: HelperSpec, version: string): {
     zip: string;
     sha256: string;
 };
-/** Extract `TeamIdentifier=XXXX` from `codesign -dv --verbose=4` output (which is
- *  emitted on stderr). Returns null when absent (ad-hoc / unsigned). */
 export declare function parseTeamId(codesignInfo: string): string | null;
-/**
- * Pure predicate (no I/O) behind the DR pin: does the requirement string pin
- * BOTH the expected CFBundleIdentifier and the Developer ID Team? Returns null
- * when it does, else an actionable error message naming the missing pin. Kept
- * pure so the truth table is unit-testable without a signed bundle or codesign.
- * Mirrors the release-time gate in `scripts/verify-menubar-helper.sh` (identifier
- * + team substring check against the same requirement string).
- */
 export declare function checkDesignatedRequirement(req: string, bundleId: string, teamId: string): string | null;
-/**
- * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
- * Team, (for the menu-bar helper) pinned by its designated requirement, and
- * notarized (Gatekeeper-accepted). Throws with an actionable message on any
- * failure — a downloaded bundle is never trusted without this.
- */
 export declare function verifyHelperApp(appPath: string, spec: HelperSpec): void;
-/**
- * Download a helper release asset for `version`, verify sha256, extract the
- * `.app`, and verify its signature (+ DR pin when the spec requires one).
- * Returns the path to the extracted bundle. A missing asset is a hard error
- * naming the exact tag — never a silent fallback to another release.
- */
 export declare function downloadHelperApp(spec: HelperSpec, version: string): Promise<string>;

package/dist/lib/helper-download.js

@@ -1,20 +1,3 @@
-/**
- * Shared on-demand download + verification for the macOS native helper `.app`
- * bundles that ship as signed + notarized GitHub release assets on each helper's
- * OWN tag (`ComputerHelper.app`, `MenubarHelper.app`, `Agents CLI.app`) — see
- * `helper-versions.ts` for why they are no longer keyed to the CLI's tag.
- *
- * A `.app` is a directory, so each asset is a zip (`ditto -c -k --keepParent`);
- * a fresh `npm i -g` machine with no bundled copy fetches the asset for the
- * pinned helper version, verifies its sha256 against the published `.sha256`,
- * then verifies the code signature (Developer ID Team + notarization — and, for
- * the menu-bar helper, its designated requirement) before it is ever installed.
- *
- * `menubar/download-menubar.ts`
- * (MenubarHelper) are thin per-helper wrappers over the primitives here — one
- * download+verify machinery, two specs — so a fix to the verify/download logic
- * lands for both helpers at once.
- */
 import { execFileSync, spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -23,68 +6,26 @@ import { pipeline } from 'node:stream/promises';
 import { getCacheDir } from './state.js';
 import { parseSha256Asset, sha256File } from './sha256-asset.js';
 import { helperTag } from './helper-versions.js';
-/**
- * GitHub repo whose `<helper>/v<version>` releases carry the helper assets.
- *
- * This is the SLUG, which is not the npm package name: the package is still
- * `@phnx-labs/agents-cli`, but the repository was renamed to `agi-cli`. The old
- * slug kept working only because GitHub redirects a renamed repo, which is a
- * poor thing to hang signed-binary delivery on — a redirect is one re-created
- * repo away from resolving somewhere else. What actually protects the download
- * is the sha256 + codesign + designated-requirement + Team ID verification
- * below; this just stops relying on the redirect.
- */
 export const HELPER_RELEASE_REPO = 'phnx-labs/agi-cli';
-/** Apple Developer ID Team every helper must be signed by ("Developer ID
- *  Application: Muqit Nawaz"). Defense in depth on top of `spctl` notarization. */
 export const EXPECTED_TEAM_ID = '2HTP252L87';
-/** Cache dir for a downloaded helper, one subdir per release tag. */
 export function helperCacheDir(spec, version) {
     return path.join(getCacheDir(), ...spec.cacheSubdir, `v${version}`);
 }
-/**
- * Release-asset URLs for one helper build, at that HELPER's own tag.
- *
- * The tag is `<helper>/v<version>` (e.g. `menubar/v1.0.0`), never the CLI's
- * `v<cliVersion>`. Keying these to the CLI tag is what forced every CLI release
- * to re-stage every helper asset, and simultaneously made a helper fix
- * unreachable without a CLI release — see `helper-versions.ts` for the full why.
- *
- * `version` is a HELPER version. Passing a CLI version here yields a tag that
- * does not exist; callers default it from {@link helperFloor}.
- */
 export function helperAssetUrls(spec, version) {
     const base = `https://github.com/${HELPER_RELEASE_REPO}/releases/download/${helperTag(spec.helper, version)}`;
-    // Asset names must not contain spaces: GitHub rewrites a space to a dot on
-    // upload, so a spaced name is requested at a URL that 404s forever. Caught on
-    // `Agents CLI.app.zip`, which GitHub served as `Agents.CLI.app.zip`. Use an
-    // underscore -- GitHub preserves it verbatim.
     if (spec.assetName.includes(' ')) {
         throw new Error(`helper asset name ${JSON.stringify(spec.assetName)} contains a space; GitHub rewrites it to a dot on `
             + 'upload, so this URL would always 404. Use an underscore instead.');
     }
     return { zip: `${base}/${spec.assetName}`, sha256: `${base}/${spec.assetName}.sha256` };
 }
-/** Extract `TeamIdentifier=XXXX` from `codesign -dv --verbose=4` output (which is
- *  emitted on stderr). Returns null when absent (ad-hoc / unsigned). */
 export function parseTeamId(codesignInfo) {
     return codesignInfo.match(/TeamIdentifier=([A-Z0-9]+)/)?.[1] ?? null;
 }
-/** Read the bundle's designated requirement string (`codesign -d --requirements -`).
- *  codesign writes it to stdout, but capture both streams so a diagnostic on
- *  stderr can never make the pin-check read empty and falsely pass. */
 function readDesignatedRequirement(appPath) {
     const r = spawnSync('/usr/bin/codesign', ['-d', '--requirements', '-', appPath], { encoding: 'utf8' });
     return `${r.stdout ?? ''}${r.stderr ?? ''}`;
 }
-/**
- * Pure predicate (no I/O) behind the DR pin: does the requirement string pin
- * BOTH the expected CFBundleIdentifier and the Developer ID Team? Returns null
- * when it does, else an actionable error message naming the missing pin. Kept
- * pure so the truth table is unit-testable without a signed bundle or codesign.
- * Mirrors the release-time gate in `scripts/verify-menubar-helper.sh` (identifier
- * + team substring check against the same requirement string).
- */
 export function checkDesignatedRequirement(req, bundleId, teamId) {
     const trimmed = req.trim();
     const shown = trimmed ? JSON.stringify(trimmed.slice(0, 200)) : '<none>';
@@ -98,50 +39,27 @@ export function checkDesignatedRequirement(req, bundleId, teamId) {
     }
     return null;
 }
-/**
- * Verify the bundle's designated requirement pins the expected CFBundleIdentifier
- * AND Developer ID Team. macOS re-validates each new version against this stored
- * requirement to keep an Accessibility grant alive across upgrades; a downloaded
- * bundle whose DR drops either pin would silently revoke that grant on the next
- * paste, so refuse it.
- */
 function verifyDesignatedRequirement(appPath, bundleId, teamId) {
     const err = checkDesignatedRequirement(readDesignatedRequirement(appPath), bundleId, teamId);
     if (err)
         throw new Error(err);
 }
-/**
- * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
- * Team, (for the menu-bar helper) pinned by its designated requirement, and
- * notarized (Gatekeeper-accepted). Throws with an actionable message on any
- * failure — a downloaded bundle is never trusted without this.
- */
 export function verifyHelperApp(appPath, spec) {
-    // 1. Structural + signature integrity.
     try {
         execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', appPath], { stdio: 'pipe' });
     }
     catch (e) {
         throw new Error(`code signature invalid for ${appPath}: ${e.message}`);
     }
-    // 2. Team identity — must be our Developer ID, not some other valid signer.
-    // `codesign -dv` writes its details to STDERR even on success (exit 0), so we
-    // must read stderr, not stdout. spawnSync captures both streams regardless of
-    // exit code; execFileSync would return only (empty) stdout and the Team check
-    // would falsely reject every validly-signed helper.
     const dv = spawnSync('/usr/bin/codesign', ['-dv', '--verbose=4', appPath], { encoding: 'utf8' });
     const info = `${dv.stdout ?? ''}${dv.stderr ?? ''}`;
     const team = parseTeamId(info);
     if (team !== spec.expectedTeamId) {
         throw new Error(`helper signed by unexpected Team (${team ?? 'none'}), expected ${spec.expectedTeamId}. Refusing to install.`);
     }
-    // 3. Designated-requirement pin (menu-bar helper only) — before the Gatekeeper
-    //    assessment so a DR mismatch fails with its specific, actionable message
-    //    rather than a generic Gatekeeper rejection.
     if (spec.expectedBundleId) {
         verifyDesignatedRequirement(appPath, spec.expectedBundleId, spec.expectedTeamId);
     }
-    // 4. Notarization / Gatekeeper — confirms Apple stapled a notarization ticket.
     try {
         execFileSync('/usr/sbin/spctl', ['--assess', '--type', 'execute', '--verbose', appPath], { stdio: 'pipe' });
     }
@@ -149,29 +67,18 @@ export function verifyHelperApp(appPath, spec) {
         throw new Error(`helper is not notarized / rejected by Gatekeeper: ${e.message}. Refusing to install.`);
     }
 }
-/**
- * Download a helper release asset for `version`, verify sha256, extract the
- * `.app`, and verify its signature (+ DR pin when the spec requires one).
- * Returns the path to the extracted bundle. A missing asset is a hard error
- * naming the exact tag — never a silent fallback to another release.
- */
 export async function downloadHelperApp(spec, version) {
     const dir = helperCacheDir(spec, version);
     const cachedApp = path.join(dir, spec.appName);
     if (fs.existsSync(cachedApp)) {
-        // Re-verify a cached bundle cheaply; a tampered cache must not be trusted.
         verifyHelperApp(cachedApp, spec);
         return cachedApp;
     }
-    // Name the HELPER's tag, not `v${version}`: after the per-helper split that
-    // string was a tag that does not exist, so a 404 pointed the reader at the
-    // wrong place to look.
     const tag = helperTag(spec.helper, version);
     const { zip: zipUrl, sha256: shaUrl } = helperAssetUrls(spec, version);
     const missing = (status, url) => new Error(`no ${spec.assetName} release asset for tag ${tag} (HTTP ${status} on ${url}). ` +
         `The macOS helper ships as a GitHub release asset on its own helper tag; ` +
         `from a repo checkout you can stage it locally instead: ${spec.localBuildHint}`);
-    // Checksum first: it is tiny and 404s fast when the tag has no assets.
     const shaRes = await fetch(shaUrl, { signal: AbortSignal.timeout(30_000) });
     if (!shaRes.ok)
         throw missing(shaRes.status, shaUrl);
@@ -188,8 +95,6 @@ export async function downloadHelperApp(spec, version) {
         if (actual !== expected) {
             throw new Error(`sha256 mismatch for ${zipUrl}: expected ${expected}, got ${actual}`);
         }
-        // Extract the zip (created with `ditto -c -k --keepParent`, so it contains
-        // <appName>/ at top level) into the version cache dir.
         fs.rmSync(cachedApp, { recursive: true, force: true });
         execFileSync('/usr/bin/ditto', ['-x', '-k', partial, dir], { stdio: 'pipe' });
         if (!fs.existsSync(cachedApp)) {

package/dist/lib/helper-versions.d.ts

@@ -1,60 +1,9 @@
-/**
- * Which build of each native helper this CLI expects, and where its release
- * lives — the module that decouples helper distribution from CLI releases.
- *
- * WHY THIS EXISTS. `helperAssetUrls` used to build
- * `releases/download/v${cliVersion}/<asset>`, keying every helper to the CLI's
- * own tag. That is coupled in BOTH directions and each one hurts:
- *
- *   - A CLI release had to re-stage every helper asset onto its new tag, or the
- *     download 404'd. That is what chained an ordinary release to a Mac.
- *   - A helper fix could not reach anyone without cutting a CLI release, because
- *     no URL existed that a shipped CLI would look at.
- *
- * Helpers now publish to their OWN tags (`<helper>/v<x.y.z>`) and this table
- * records the FLOOR — the build this CLI was tested against. A floor, not an
- * exact pin: a pin would fix the first problem and leave the second, since an
- * improved helper would still need a CLI release to be reachable. The floor is
- * what a channel manifest can later resolve *upward* from (newest >= floor),
- * without another rewrite of the download path.
- *
- * The floor is also the offline answer: it names an IMMUTABLE tag that always
- * exists, so a machine that cannot reach a manifest still has exactly one
- * correct URL rather than a guess.
- *
- * Bumping an entry here is a deliberate act — it says "this CLI has been tested
- * against that helper build". It is not a mirror of the CLI version and must
- * never be derived from `getCliVersion()`.
- */
-/** The helpers that have their own release train. */
 export type HelperName = 'menubar';
-/** One helper's release identity. */
 interface HelperRelease {
-    /** Tag prefix — the release is `<tagPrefix>/v<version>`. */
     tagPrefix: string;
-    /**
-     * Lowest helper build this CLI is known to work with. Resolution may pick a
-     * NEWER build; it must never pick an older one.
-     */
     floor: string;
 }
-/**
- * Floors, by helper.
- *
- * `menubar` starts at 1.0.0 — the first build published under its own tag
- * rather than the CLI's. It is not "version 1 of the helper"; it is version 1
- * of its independent release train.
- *
- * Two helper families have since left this table entirely, both for the same
- * reason: their engine became a standalone CLI that resolves and verifies its
- * OWN helper release. The keychain helper went with `secrets` (PHNX-3989); the
- * macOS and Windows computer helpers went with `computer` (PHNX-4075). A floor
- * recorded here for a helper this CLI never downloads would be a lying table —
- * it would claim a distribution responsibility agents-cli no longer has.
- */
 export declare const HELPER_RELEASES: Readonly<Record<HelperName, HelperRelease>>;
-/** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */
 export declare function helperTag(helper: HelperName, version: string): string;
-/** The floor build for one helper — the version used when nothing resolves higher. */
 export declare function helperFloor(helper: HelperName): string;
 export {};

package/dist/lib/helper-versions.js

@@ -1,56 +1,12 @@
-/**
- * Which build of each native helper this CLI expects, and where its release
- * lives — the module that decouples helper distribution from CLI releases.
- *
- * WHY THIS EXISTS. `helperAssetUrls` used to build
- * `releases/download/v${cliVersion}/<asset>`, keying every helper to the CLI's
- * own tag. That is coupled in BOTH directions and each one hurts:
- *
- *   - A CLI release had to re-stage every helper asset onto its new tag, or the
- *     download 404'd. That is what chained an ordinary release to a Mac.
- *   - A helper fix could not reach anyone without cutting a CLI release, because
- *     no URL existed that a shipped CLI would look at.
- *
- * Helpers now publish to their OWN tags (`<helper>/v<x.y.z>`) and this table
- * records the FLOOR — the build this CLI was tested against. A floor, not an
- * exact pin: a pin would fix the first problem and leave the second, since an
- * improved helper would still need a CLI release to be reachable. The floor is
- * what a channel manifest can later resolve *upward* from (newest >= floor),
- * without another rewrite of the download path.
- *
- * The floor is also the offline answer: it names an IMMUTABLE tag that always
- * exists, so a machine that cannot reach a manifest still has exactly one
- * correct URL rather than a guess.
- *
- * Bumping an entry here is a deliberate act — it says "this CLI has been tested
- * against that helper build". It is not a mirror of the CLI version and must
- * never be derived from `getCliVersion()`.
- */
-/**
- * Floors, by helper.
- *
- * `menubar` starts at 1.0.0 — the first build published under its own tag
- * rather than the CLI's. It is not "version 1 of the helper"; it is version 1
- * of its independent release train.
- *
- * Two helper families have since left this table entirely, both for the same
- * reason: their engine became a standalone CLI that resolves and verifies its
- * OWN helper release. The keychain helper went with `secrets` (PHNX-3989); the
- * macOS and Windows computer helpers went with `computer` (PHNX-4075). A floor
- * recorded here for a helper this CLI never downloads would be a lying table —
- * it would claim a distribution responsibility agents-cli no longer has.
- */
 export const HELPER_RELEASES = {
-    menubar: { tagPrefix: 'menubar', floor: '1.6.2' },
+    menubar: { tagPrefix: 'menubar', floor: '1.7.0' },
 };
-/** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */
 export function helperTag(helper, version) {
     const release = HELPER_RELEASES[helper];
     if (!release)
         throw new Error(`unknown helper '${helper}' (want: ${Object.keys(HELPER_RELEASES).join(', ')})`);
     return `${release.tagPrefix}/v${version}`;
 }
-/** The floor build for one helper — the version used when nothing resolves higher. */
 export function helperFloor(helper) {
     const release = HELPER_RELEASES[helper];
     if (!release)

package/dist/lib/hooks/cache.d.ts

@@ -1,60 +1,20 @@
 import type { HookCache, HookCacheConfig, HookMatches } from '../types.js';
-/**
- * Parse a `cache:` value from hooks.yaml into the canonical config form.
- * Accepts the shorthand string ("5m", "30s-bg") or the full object form.
- * Returns null if the value is missing or unparseable.
- */
 export declare function parseCacheConfig(raw: HookCache | undefined): HookCacheConfig | null;
-/** Parse "30s" | "5m" | "1h" | "7d" | plain seconds. Returns seconds, or null on failure. */
 export declare function parseDuration(d: number | string | undefined): number | null;
-/**
- * Reject hook names that could escape the shims directory when interpolated
- * into a filename. Mirrors the containment gate on hook script resolution in
- * hooks.ts (`resolveContainedHookPath`).
- */
 export declare function isValidHookShimName(name: string): boolean;
-/** Absolute path of the generated shim for a hook name. */
 export declare function getHookShimPath(name: string): string;
-/**
- * Optional path overrides for tests that need to redirect cache + logs to a
- * temp dir. Production callers omit `paths`; the shim uses real state.ts dirs.
- * (state.ts captures HOME at module load, so mutating process.env.HOME in a
- * test's beforeEach doesn't reach getHookCacheDir() — this is the explicit
- * seam.)
- */
 export interface HookShimPaths {
     shimsDir?: string;
     cacheDir?: string;
     logsDir?: string;
-    /** Directory for the disposable perf warehouse + spool (default ~/.agents/.cache/perf). */
     perfDir?: string;
 }
-/**
- * Generate (or refresh) the shim script for a hook. Idempotent — only writes
- * when the content differs from what's on disk. Returns the absolute shim path.
- *
- * A shim is generated when the hook opts into caching (`cache`) and/or declares
- * `matches:` predicates. When `matches` is present the shim gates execution on
- * those predicates before running the underlying script (see `renderShim`);
- * when `cache` is absent the shim is a thin pass-through wrapper that only
- * applies the gate and forwards stdin/stdout unchanged.
- */
 export declare function generateHookShim(args: {
     name: string;
     scriptPath: string;
     cache?: HookCacheConfig | null;
     matches?: HookMatches;
     paths?: HookShimPaths;
-    /**
-     * Deny the tool call (exit 2) when the source script is missing instead of
-     * failing with 127, which every harness reads as "allow". Set for
-     * PreToolUse hooks: a guard whose script vanished (version pruned, sync
-     * rewriting the hooks dir) must not silently wave tool calls through.
-     */
     failClosed?: boolean;
 }): string;
-/**
- * Remove a hook's shim. Called by the registrar's garbage collection when a
- * hook is renamed/deleted or has its `cache:` field removed.
- */
 export declare function removeHookShim(name: string, shimsDir?: string): void;