lua-cli 3.15.1 → 3.15.3

package/node_modules/@lua/shared-source-sync/dist/index.d.mts

@@ -0,0 +1,424 @@
+/**
+ * Wire types for the agent project backup feature.
+ *
+ * These mirror `packages/lua-cli/src/interfaces/backup.ts` byte-for-byte so the
+ * CLI and any server-side caller speak the same protocol against the existing
+ * `/developer/agents/:agentId/backup/*` endpoints on lua-api.
+ */
+/**
+ * A single file entry in the backup manifest. Carries no content — content is
+ * stored as a blob in S3 under `backups/blobs/<hash>` and dereferenced at
+ * restore time.
+ */
+interface BackupFileRef {
+    /**
+     * Path used both as identifier and as on-disk restore location.
+     * - In-project: relative to the agent's project root (e.g. `src/index.ts`).
+     * - External (monorepo cross-root): relative to the workspace root; restored
+     *   under `.lua/external/<relativePath>` (see BAC-69).
+     */
+    relativePath: string;
+    /** Truncated SHA-256 (16 hex chars) of the file's raw bytes. Used as the S3 key. */
+    hash: string;
+    /** Original (uncompressed) byte size. */
+    size: number;
+    /** Coarse classification for telemetry and UI grouping. */
+    type: 'source' | 'config' | 'other';
+    /** Defaults to in-project when absent. Cross-root files set this `true`. */
+    external?: boolean;
+}
+/** Body of `POST /developer/agents/:agentId/backup/check-blobs`. */
+interface CheckBlobsRequest {
+    hashes: string[];
+}
+/** Response shape from `check-blobs`. */
+interface CheckBlobsResponse {
+    missing: string[];
+    existing: string[];
+    results: Record<string, boolean>;
+}
+/** Body of `POST /developer/agents/:agentId/backup/blob-upload-urls` and `.../blob-urls`. */
+interface GetBlobUrlsRequest {
+    hashes: string[];
+}
+/** Response shape: `{ urls: { <hash>: <presignedUrl> }, expiresIn: <seconds> }`. */
+interface GetBlobUrlsResponse {
+    urls: Record<string, string>;
+    expiresIn: number;
+}
+/** Body of `POST /developer/agents/:agentId/backup/manifest`. */
+interface SaveManifestRequest {
+    projectHash: string;
+    files: BackupFileRef[];
+    version?: string;
+    createdBy?: string;
+    orgId?: string;
+    triggeredBy?: string;
+}
+/** Metadata returned by `GET /developer/agents/:agentId/backup`. */
+interface BackupMetadata {
+    agentId: string;
+    orgId: string;
+    projectHash: string;
+    fileCount: number;
+    totalSize: number;
+    version?: string;
+    createdBy: string;
+    createdAt: string;
+    /** Monotonic manifest version assigned by the V2 server path. */
+    activeVersion?: number;
+}
+/** Full response from `GET /developer/agents/:agentId/backup/manifest`. */
+interface BackupManifest extends BackupMetadata {
+    files: BackupFileRef[];
+}
+/** Response from `GET /developer/agents/:agentId/backup/check/:hash`. */
+interface BackupExistsResponse {
+    exists: boolean;
+    currentHash?: string;
+}
+
+/**
+ * Hashing primitives.
+ *
+ * Wire-format note: the rest of the Lua platform (compiler, CLI cache, server
+ * blob keys) uses the FIRST 16 HEX CHARS of SHA-256 as the file hash. This
+ * truncation is part of the protocol — full 64-char digests would be
+ * incompatible with the existing S3 layout and dedup. `hashContentTruncated`
+ * is the canonical helper; callers should not roll their own.
+ */
+/** Default truncation length used across the Lua platform. */
+declare const FILE_HASH_LENGTH = 16;
+/** Hash file content with the canonical 16-char truncated SHA-256. */
+declare function hashContentTruncated(content: string | Buffer): string;
+/** Full-length SHA-256 hex; used only for the combined project hash. */
+declare function sha256Hex(content: string | Buffer): string;
+/**
+ * Deterministic project hash: full-length SHA-256 over the sorted list of
+ * per-file hashes joined by `|`. Matches `calculateProjectHash` in
+ * `packages/lua-cli/src/utils/backup-helpers.ts` byte-for-byte so cross-tool
+ * pushes do not produce spurious drift.
+ */
+declare function combineFileHashes(files: {
+    relativePath: string;
+    hash: string;
+}[]): string;
+
+declare const DEFAULT_MAX_FILE_BYTES: number;
+declare function shouldSkipDirectory(name: string): boolean;
+declare function shouldSkipFile(filePathOrName: string): boolean;
+declare function classifyFile(relPath: string): 'source' | 'config' | 'other';
+
+/**
+ * Walk an agent workspace from disk and produce a fresh manifest. Used by
+ * both the CLI (via `buildManifestFromDisk`) and server-side callers
+ * (`SourceSyncService`).
+ */
+
+interface WalkOptions {
+    /** Per-file size cap. Files larger than this are skipped (default 256KB). */
+    maxFileBytes?: number;
+}
+interface WalkResult {
+    /** Sorted file references suitable for a backup manifest. */
+    files: BackupFileRef[];
+    /** Deterministic combined hash over the file set. */
+    projectHash: string;
+    /** Sum of original file sizes. */
+    totalSize: number;
+    /**
+     * Raw file content keyed by truncated hash. Caller uses this for the upload
+     * step instead of re-reading from disk. First-write-wins on collision so
+     * dedup is honored.
+     */
+    contentByHash: Map<string, Buffer>;
+}
+/**
+ * Walk `rootDir` and return a stable workspace snapshot. 16-char truncated
+ * SHA-256 hashes; path separators normalized to `/` for OS-independent
+ * manifest round-trip.
+ */
+declare function walkWorkspace(rootDir: string, opts?: WalkOptions): WalkResult;
+
+/**
+ * HTTP client for the `/developer/agents/:agentId/backup/*` endpoints on lua-api.
+ *
+ * Authentication is opaque to this module — the caller injects an
+ * `Authorization` header value. lua-cli uses a Bearer API key; server-side
+ * callers (`lua-claude-builder`) use a scoped service token.
+ *
+ * Errors surface as `BackupHttpError` instances with status code attached so
+ * the caller can distinguish auth (`401/403`) from transport vs CAS-conflict
+ * (`409`) failures.
+ */
+
+/** Minimal `fetch` contract — Node 18+, browser, or a test stub. */
+type FetchLike = typeof fetch;
+declare class BackupHttpError extends Error {
+    readonly status: number;
+    readonly endpoint: string;
+    readonly body?: string;
+    constructor(message: string, status: number, endpoint: string, body?: string);
+}
+interface BackupHttpClientOptions {
+    /** Base URL for lua-api (e.g. `https://api.heylua.ai`). No trailing slash. */
+    baseUrl: string;
+    /** Full `Authorization` header value, e.g. `Bearer <apiKey>`. */
+    authHeader: string;
+    /** Target agent id. Embedded into every path. */
+    agentId: string;
+    /** Override the global `fetch` (tests inject a mock). */
+    fetch?: FetchLike;
+}
+/**
+ * Thin wrapper around the backup endpoints. All methods return the parsed
+ * JSON body on `2xx` and throw `BackupHttpError` otherwise — by design this
+ * pushes branching (e.g. "no backup yet → 404") into the caller, where the
+ * intent is clearer than a discriminated success/error wrapper.
+ */
+declare class BackupHttpClient {
+    private readonly options;
+    private readonly fetchFn;
+    constructor(options: BackupHttpClientOptions);
+    private url;
+    private json;
+    /** `POST /backup/check-blobs` — returns existing vs missing partition. */
+    checkBlobsExist(hashes: string[]): Promise<CheckBlobsResponse>;
+    /** `POST /backup/blob-upload-urls` — presigned S3 PUT URLs. */
+    getBlobUploadUrls(hashes: string[]): Promise<GetBlobUrlsResponse>;
+    /** `POST /backup/blob-urls` — presigned S3 GET URLs (for restore). */
+    getBlobUrls(hashes: string[]): Promise<GetBlobUrlsResponse>;
+    /** `POST /backup/manifest` — final step in a push; returns server metadata. */
+    saveManifest(data: SaveManifestRequest): Promise<BackupMetadata>;
+    /** `GET /backup` — metadata only, no file list. */
+    getMetadata(): Promise<BackupMetadata>;
+    /** `GET /backup/manifest` — metadata + file list. */
+    getManifest(): Promise<BackupManifest>;
+    /** `GET /backup/check/:hash` — fast freshness probe. */
+    checkBackupExists(hash: string): Promise<BackupExistsResponse>;
+}
+
+/**
+ * S3 transfer primitives: gzip-compressed blob upload and download.
+ *
+ * Content is always gzipped before upload (matches the CLI convention) and
+ * decompressed transparently on download (magic-byte sniff with raw fallback
+ * for legacy/uncompressed blobs that may still exist).
+ */
+
+/**
+ * PUT each blob to its presigned URL. Caller supplies a map of `hash → URL`
+ * (from `BackupHttpClient.getBlobUploadUrls`) plus a map of `hash → content`.
+ * Returns the count of blobs that landed in S3.
+ */
+declare function uploadBlobs(opts: {
+    uploadUrls: Record<string, string>;
+    contentByHash: Map<string, Buffer>;
+    fetch?: FetchLike;
+    concurrency?: number;
+}): Promise<number>;
+/**
+ * GET each blob from its presigned URL and return `hash → buffer`. Detects
+ * gzip via magic bytes (1f 8b) and gracefully falls back to the raw response
+ * body for any legacy uncompressed blobs.
+ */
+declare function downloadBlobs(opts: {
+    urls: Record<string, string>;
+    fetch?: FetchLike;
+    concurrency?: number;
+}): Promise<Map<string, Buffer>>;
+
+/**
+ * Restore primitives: write a downloaded blob map back to disk.
+ *
+ * Mirrors `restoreProjectFromBackup` + `resolveBackupFileTarget` in
+ * `packages/lua-cli/src/utils/backup-helpers.ts`. The sandbox rule for
+ * `external: true` entries is preserved: they land under
+ * `<targetDir>/.lua/external/<workspaceRelativePath>` rather than being
+ * written back to their original workspace location.
+ */
+
+/**
+ * Compute the disk path where a manifest entry should land during restore.
+ *
+ * Throws if the result would escape `targetDir` — a malicious manifest with
+ * `../` segments must not be allowed to overwrite arbitrary files.
+ */
+declare function resolveBackupFileTarget(file: BackupFileRef, targetDir: string): string;
+interface RestoreOptions {
+    /** Overwrite existing files. Defaults to `false` — collision-safe. */
+    overwrite?: boolean;
+}
+interface RestoreResult {
+    filesWritten: number;
+    filesUnchanged: number;
+    filesSkipped: number;
+}
+/**
+ * Materialize a manifest's files into `targetDir`. Skips writes when the
+ * on-disk bytes already match the blob (so callers can distinguish "9 files
+ * restored" from "9 files matched, 0 written") and respects `overwrite=false`
+ * to avoid clobbering edits the user hasn't yet pushed.
+ */
+declare function restoreFromBlobs(manifest: BackupManifest, blobs: Map<string, Buffer>, targetDir: string, opts?: RestoreOptions): RestoreResult;
+
+/**
+ * High-level "push the contents of `workspaceDir` to the per-agent backup".
+ *
+ * This is the algorithm shared between `lua-cli`'s `lua push backup` and the
+ * `lua-claude-builder` `SourceSyncService`. Pure (no console output, no
+ * filesystem mutation outside of reading `workspaceDir`, no telemetry — the
+ * caller layers those concerns on top).
+ */
+
+interface PushAgentBackupOptions {
+    /** HTTP client config — the helper constructs the client internally. */
+    http: BackupHttpClientOptions;
+    /** Workspace root. Walked recursively with the standard skip rules. */
+    workspaceDir: string;
+    /** Org id (forwarded to the saveManifest body so the server can skip a lookup). */
+    orgId: string;
+    /** Semver of the deployed primitive when known. */
+    version?: string;
+    /** Audit label, e.g. `'admin-tool-builder'` or `'manual lua push backup'`. */
+    triggeredBy?: string;
+    /** Provenance label for the manifest record. Defaults to `'cli'` to match historical behavior. */
+    createdBy?: string;
+    /** Tuning knobs for the walk. */
+    walkOptions?: WalkOptions;
+    /** Tuning knob for the parallel S3 PUTs. */
+    concurrency?: number;
+}
+interface PushAgentBackupResult {
+    /** Combined project hash that was pushed. */
+    projectHash: string;
+    /** Number of files described by the manifest (post-dedupe by path). */
+    fileCount: number;
+    /** Number of blobs the helper actually PUT to S3 (deduped against existing). */
+    filesUploaded: number;
+    /** Server-assigned monotonic version, when the V2 manifest path returned one. */
+    activeVersion?: number;
+    /** Full server metadata response for the saveManifest call. */
+    metadata: BackupMetadata;
+    /** The manifest file refs in the order they were sent. */
+    files: BackupFileRef[];
+}
+/**
+ * Walk the workspace, upload missing blobs, save the manifest, return the
+ * server's response. Throws on any non-2xx — callers decide how to react.
+ *
+ * Idempotent by design: the algorithm is content-addressed, so re-running the
+ * push for the same workspace state is a no-op aside from the manifest write
+ * (which the server treats as either equal-to-current or a new version).
+ */
+declare function pushAgentBackup(opts: PushAgentBackupOptions): Promise<PushAgentBackupResult>;
+
+/**
+ * High-level "pull the per-agent backup into `targetDir`".
+ *
+ * Counterpart to `pushAgentBackup`. Today only the CLI calls this; the
+ * shared package exposes it so future server-side features (e.g. "rehydrate
+ * Builder workspace from the latest CLI push") can reuse the same logic.
+ */
+
+interface PullAgentBackupOptions {
+    http: BackupHttpClientOptions;
+    /** Destination on disk. Will be created if necessary. */
+    targetDir: string;
+    /** Restore options (overwrite policy). */
+    restore?: RestoreOptions;
+    /** Tuning knob for the parallel S3 GETs. */
+    concurrency?: number;
+}
+interface PullAgentBackupResult extends RestoreResult {
+    manifest: BackupManifest;
+}
+/**
+ * Fetch the manifest, download every referenced blob, write to disk. Returns
+ * the manifest plus a tally of write/no-op/skip outcomes.
+ *
+ * Errors propagate — a missing backup throws `BackupHttpError` (404). Callers
+ * decide whether that warrants a friendly "no source yet" message or a hard
+ * failure.
+ */
+declare function pullAgentBackup(opts: PullAgentBackupOptions): Promise<PullAgentBackupResult>;
+
+/**
+ * Workspace ↔ archive serialization. Wire format:
+ *   gzip(JSON.stringify({ [relPath]: contents })) → base64.
+ * Spec: docs/superpowers/specs/2026-05-02-canonical-tool-source-design.md.
+ *
+ * A JSON map is used (vs tar) so neither the CLI bundle nor the
+ * lua-claude-builder runtime needs a tar dependency. The format is symmetric
+ * across both, so encode/decode go through these helpers — never inline.
+ */
+declare const ARCHIVE_SCHEMA_VERSION = 1;
+/**
+ * Encode a workspace directory tree into a base64-gzip JSON map. Returns
+ * `null` if the workspace doesn't exist or is empty.
+ */
+declare function encodeWorkspaceArchive(workspaceDir: string): string | null;
+/**
+ * Decode a base64-gzip JSON map back to a `{ relPath: content }` object.
+ * Throws on malformed payloads — callers should treat that as a corrupt
+ * canonical record and surface clearly rather than silently writing nothing.
+ */
+declare function decodeWorkspaceArchive(archive: string, schemaVersion?: number): Record<string, string>;
+/**
+ * Write the contents of a decoded archive into `workspaceDir`. Existing files
+ * are overwritten — caller is responsible for save-pending-changes prompts.
+ * Defense-in-depth: any `relPath` containing `..` is rejected.
+ */
+declare function writeArchiveToWorkspace(workspaceDir: string, files: Record<string, string>): void;
+
+/**
+ * Wire types for the per-skill canonical source store.
+ * Spec: docs/superpowers/specs/2026-05-02-canonical-tool-source-design.md.
+ *
+ * Driven by both the admin-tool-builder's CanonicalSourceClient (internal
+ * lua-agents URI, no auth) and lua-cli's SkillApi (developer-facing lua-api
+ * endpoint, Bearer auth). Transport differs; the wire shapes are shared.
+ */
+declare const SKILL_SOURCE_EDITORS: readonly ["builder", "cli", "engineer", "system"];
+type SkillSourceEditor = (typeof SKILL_SOURCE_EDITORS)[number];
+/** Per-tool entry returned by `GET /skills/.../source`. */
+interface SkillSourceTool {
+    name: string;
+    entryFile: string | null;
+    source: string | null;
+    lastEditedBy: SkillSourceEditor | null;
+    lastEditedAt: string | Date | null;
+}
+/** Response from `GET /skills/.../source` (lua-agents internal) / `GET /developer/skills/.../source` (lua-api). */
+interface FetchedSkillSource {
+    skillId: string;
+    version: string;
+    sourceArchive: string | null;
+    archiveSchemaVersion: number | null;
+    tools: SkillSourceTool[];
+}
+/** Per-tool entry accepted by `PUT /skills/.../version/.../source`. */
+interface AttachSkillSourceTool {
+    name: string;
+    source?: string;
+    entryFile?: string;
+    lastEditedBy?: SkillSourceEditor;
+}
+/** Body of `PUT /skills/.../version/.../source`. */
+interface AttachSkillSourcePayload {
+    sourceArchive?: string;
+    archiveSchemaVersion?: number;
+    tools?: AttachSkillSourceTool[];
+    /**
+     * CAS gate: if supplied and not matching the skill's current
+     * `activeVersionId` on the server, the write is rejected with 409.
+     */
+    expectedActiveVersionId?: string;
+}
+/** Successful response shape from `PUT /skills/.../version/.../source`. */
+interface AttachSkillSourceResponse {
+    ok: true;
+    version: string;
+}
+
+export { ARCHIVE_SCHEMA_VERSION, type AttachSkillSourcePayload, type AttachSkillSourceResponse, type AttachSkillSourceTool, type BackupExistsResponse, type BackupFileRef, BackupHttpClient, type BackupHttpClientOptions, BackupHttpError, type BackupManifest, type BackupMetadata, type CheckBlobsRequest, type CheckBlobsResponse, DEFAULT_MAX_FILE_BYTES, FILE_HASH_LENGTH, type FetchLike, type FetchedSkillSource, type GetBlobUrlsRequest, type GetBlobUrlsResponse, type PullAgentBackupOptions, type PullAgentBackupResult, type PushAgentBackupOptions, type PushAgentBackupResult, type RestoreOptions, type RestoreResult, SKILL_SOURCE_EDITORS, type SaveManifestRequest, type SkillSourceEditor, type SkillSourceTool, type WalkOptions, type WalkResult, classifyFile, combineFileHashes, decodeWorkspaceArchive, downloadBlobs, encodeWorkspaceArchive, hashContentTruncated, pullAgentBackup, pushAgentBackup, resolveBackupFileTarget, restoreFromBlobs, sha256Hex, shouldSkipDirectory, shouldSkipFile, uploadBlobs, walkWorkspace, writeArchiveToWorkspace };