lua-cli 3.15.3 → 3.16.0

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

@@ -1,424 +0,0 @@
-/**
- * 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 };