@pify/cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,195 @@
+/** CLI version, read from the packaged package.json (always in the tarball). */
+declare const VERSION: string;
+
+interface CatalogPackage {
+    /** Short name used on the pify command line, e.g. "goal". */
+    name: string;
+    /** Full npm name, e.g. "@pify/goal". */
+    npm: string;
+    repo: string;
+    description: string;
+    /** "published" once it exists on the npm registry; "planned" before that. */
+    status: "published" | "planned";
+}
+interface Catalog {
+    version: number;
+    org: string;
+    scope: string;
+    /** URL of the always-current catalog on the org's main branch. */
+    remote: string;
+    packages: CatalogPackage[];
+}
+declare function loadBundledCatalog(): Catalog;
+/**
+ * SECURITY-CRITICAL. A fetched catalog is either fully valid or fully
+ * discarded: every npm name must stay inside the @pify scope so a tampered
+ * catalog cannot redirect installs outside the org (npm publish rights are a
+ * separate credential from GitHub). Combined with the install rule that only
+ * `npm:@pify/...` specs are ever delegated to pi, this bounds the blast
+ * radius of a compromised remote to "packages the org itself published".
+ */
+declare function validateCatalog(data: unknown): data is Catalog;
+/**
+ * Load the catalog. Resolution chain, newest `version` wins:
+ * bundled snapshot (offline floor) -> ~/.pify cache -> remote fetch.
+ * Opportunistic refresh (3s timeout) when the cache is stale; forced refresh
+ * (10s) via `refreshCatalog`. Every failure path falls back silently — the
+ * catalog can never break a command.
+ */
+declare function loadCatalog(opts?: {
+    refresh?: boolean;
+}): Promise<Catalog>;
+/** Forced refresh for `pify update --catalog`. Reports success. */
+declare function refreshCatalog(): Promise<{
+    ok: boolean;
+    catalog: Catalog;
+}>;
+interface InstallSpec {
+    base: string;
+    pin: string | null;
+}
+/** Split `goal@0.3.0` / `@pify/goal@next` into base and validated pin. */
+declare function parseInstallSpec(input: string): InstallSpec;
+interface InstallTarget {
+    shortName: string;
+    npm: string;
+    pin: string | null;
+    /** True when the user typed the full @pify/<name> form (catalog bypass). */
+    explicit: boolean;
+    inCatalog: boolean;
+    status: CatalogPackage["status"] | null;
+    repo: string | null;
+}
+/**
+ * Resolve a user-supplied install argument. Short names must exist in the
+ * catalog and be published; the explicit `@pify/<name>` form always proceeds
+ * (the escape hatch for catalog staleness — a truly unpublished package
+ * degrades to pi/npm's own E404, never a wrong install). Anything outside the
+ * @pify scope is refused: that is pi's job.
+ */
+declare function resolveInstallTarget(catalog: Catalog, input: string): InstallTarget;
+/**
+ * Resolve a name for remove/update targeting: same input forms, but catalog
+ * membership is not required (users must be able to remove packages later
+ * dropped from the catalog). Pins are parsed and ignored.
+ */
+declare function resolvePifyName(input: string): string;
+
+/** The npm package that provides the `pi` binary. */
+declare const PI_PACKAGE = "@earendil-works/pi-coding-agent";
+/** Minimum Node version required by the pi coding agent. */
+declare const NODE_FLOOR = "22.19.0";
+/** The pi version this CLI release was developed and tested against. */
+declare const TESTED_PI_VERSION = "0.84.4";
+interface PiStatus {
+    installed: boolean;
+    /** Absolute path to the `pi` launcher, when installed. */
+    binPath: string | null;
+    /** Version reported by `pi --version`, when installed. */
+    version: string | null;
+}
+declare function piStatus(): PiStatus;
+/** Latest pi version from pi's own release endpoint. Null offline/on error. */
+declare function fetchLatestPiVersion(): Promise<string | null>;
+declare function compareSemver(a: string, b: string): number;
+/**
+ * Install pi globally via npm. This is the one operation pi cannot do for
+ * itself — `pi update --self` requires a working pi. `--ignore-scripts`
+ * matches pi's own self-update invocation (supply-chain-safe default).
+ */
+declare function installPi(version?: string): Promise<void>;
+/**
+ * Update pi. Delegates to bare `pi update` (its default target is self):
+ * pi's updater owns install-method detection, the pi.dev rename protocol,
+ * managed-install staging, and the Windows native-module quarantine.
+ * Reimplementing any of it would rot. When pi is absent, fall through to a
+ * fresh install so `npx @pify/cli update` works on a bare machine.
+ */
+declare function updatePi(): Promise<void>;
+interface PiSettings {
+    packages?: Array<string | {
+        source: string;
+        [k: string]: unknown;
+    }>;
+    [k: string]: unknown;
+}
+/** pi's agent directory: tilde-expanded PI_CODING_AGENT_DIR or ~/.pi/agent. */
+declare function agentDir(): string;
+/**
+ * Read-only view of pi settings. All writes go through the pi CLI — pi owns
+ * that state (dedup rules, npm workspace, trust model), and two writers would
+ * eventually disagree. Parse failures are treated as absent (doctor warns).
+ */
+declare function readSettings(scope: "user" | "project"): PiSettings | null;
+interface InstalledPifyPackage {
+    name: string;
+    scope: "user" | "project";
+    source: string;
+    pin: string | null;
+}
+/**
+ * @pify packages configured in pi's settings, both scopes, deduped by name
+ * (project wins, matching pi's own scope precedence).
+ */
+declare function installedPifyPackages(): Map<string, InstalledPifyPackage>;
+interface OnDiskState {
+    present: boolean;
+    version: string | null;
+}
+/** Version of an installed @pify package as materialized in pi's npm root. */
+declare function installedVersionOnDisk(name: string, scope: "user" | "project"): OnDiskState;
+
+/** True when the user asked for offline behavior (pi's env var is honored too). */
+declare function isOffline(): boolean;
+declare function assertSafeArg(arg: string, what?: string): void;
+/**
+ * Absolute path of a command on PATH, or null. In-process scan (no child
+ * process): PATHEXT-aware on Windows, executable-bit check on POSIX.
+ */
+declare function which(command: string): string | null;
+
+/**
+ * The five `pify init` file templates, embedded as string literals so the
+ * tarball ships nothing extra. Every line of the package.json template
+ * encodes a verified ecosystem rule — see the comments in initCommand.
+ */
+interface TemplateVars {
+    name: string;
+    description: string;
+    shortName: string;
+    snakeName: string;
+    piVersion: string;
+    dir: string;
+}
+declare function interpolate(template: string, vars: TemplateVars): string;
+declare function packageJsonTemplate(scoped: boolean): string;
+declare const INDEX_TS = "import { Type } from \"@earendil-works/pi-ai\";\nimport { defineTool, type ExtensionAPI } from \"@earendil-works/pi-coding-agent\";\n\n// Rules this template already follows:\n// - Signal tool errors by THROWING from execute(); returned values never set isError.\n// - Truncate large output with truncateHead/truncateTail from\n//   @earendil-works/pi-coding-agent (built-in limits: 50 KB / 2000 lines).\n// - Use StringEnum from @earendil-works/pi-ai for enum parameters;\n//   Type.Union/Type.Literal breaks on Google's API.\n// - Use the CONFIG_DIR_NAME export instead of hardcoding \".pi\" for\n//   project-local config paths.\nconst exampleTool = defineTool({\n  name: \"{{snakeName}}_hello\",\n  label: \"{{shortName}} hello\",\n  description: \"Example tool for {{name}}. Replace with your own.\",\n  parameters: Type.Object({\n    name: Type.String({ description: \"Name to greet\" }),\n  }),\n  async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {\n    return {\n      content: [{ type: \"text\", text: `Hello, ${params.name}!` }],\n      details: { greeted: params.name },\n    };\n  },\n});\n\nexport default function (pi: ExtensionAPI) {\n  pi.registerTool(exampleTool);\n\n  pi.registerCommand(\"{{shortName}}-hello\", {\n    description: \"Example command for {{name}}. Replace with your own.\",\n    handler: async (args, _ctx) => {\n      // `args` is the single raw string typed after the command name.\n      // There is no argv parsing - split it yourself if you need arguments.\n    },\n  });\n\n  // Never start watchers, sockets, timers, or child processes here in the\n  // factory: it can run in invocations that never start a session.\n  pi.on(\"session_start\", async (_event, _ctx) => {\n    // Start background resources here.\n  });\n\n  pi.on(\"session_shutdown\", async (_event, _ctx) => {\n    // Tear them down here. This must be idempotent: it fires on quit,\n    // /reload, /new, /resume, and /fork.\n  });\n}\n";
+declare const README_MD = "# {{name}}\n\n{{description}}\n\nA Pi Package for the pi coding agent (https://pi.dev).\n\n## Develop\n\n    npm install              # dev dependencies for typechecking\n    pi install ./{{dir}}     # register locally; hot-reloads with /reload\n    pi -e ./index.ts         # or load ad hoc for a single run\n    npm run typecheck\n\n## Publish\n\n    npm publish --access public\n\nThen install anywhere with: pi install npm:{{name}}\n\nTested with pi {{piVersion}}.\n";
+
+/**
+ * Exit codes. Distinct codes let CI distinguish "your environment is wrong"
+ * from "the thing you asked for does not exist".
+ */
+declare const ExitCode: {
+    readonly OK: 0;
+    /** Generic / unexpected failure. */
+    readonly FAILURE: 1;
+    /** Bad arguments, unknown command, malformed package name. */
+    readonly USAGE: 2;
+    /** A required external program (pi, npm, node) is missing or too old. */
+    readonly ENVIRONMENT: 3;
+    /** The requested package is not in the catalog or not yet published. */
+    readonly NOT_FOUND: 4;
+    /** A delegated `pi` or `npm` subprocess exited non-zero. */
+    readonly SUBPROCESS: 5;
+};
+type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+/** An error we produced deliberately: message is user-facing, no stack trace. */
+declare class PifyError extends Error {
+    readonly code: ExitCodeValue;
+    /** Optional follow-up shown after the message, e.g. a command to run. */
+    readonly hint?: string;
+    constructor(message: string, code?: ExitCodeValue, hint?: string);
+}
+
+export { type Catalog, type CatalogPackage, ExitCode, INDEX_TS, type InstallSpec, type InstallTarget, type InstalledPifyPackage, NODE_FLOOR, PI_PACKAGE, type PiSettings, type PiStatus, PifyError, README_MD, TESTED_PI_VERSION, type TemplateVars, VERSION, agentDir, assertSafeArg, compareSemver, fetchLatestPiVersion, installPi, installedPifyPackages, installedVersionOnDisk, interpolate, isOffline, loadBundledCatalog, loadCatalog, packageJsonTemplate, parseInstallSpec, piStatus, readSettings, refreshCatalog, resolveInstallTarget, resolvePifyName, updatePi, validateCatalog, which };