@cairn-tool/cairn 2.0.0

package/dist/agent/types.d.ts

@@ -0,0 +1,204 @@
+import type { BundleMarketplace } from "./manifest.js";
+import type { UpgradeReport } from "./upgrade.js";
+import type { ImportReport } from "./import/normalize.js";
+import type { PackageReport } from "./package/index.js";
+import type { AuditReport } from "./audit/index.js";
+import type { TestReport } from "./test/index.js";
+import type { InstallReport } from "./install/index.js";
+import type { MarketplaceReport } from "./marketplace/index.js";
+export declare const TARGETS: readonly ["claude-code", "codex", "cursor", "antigravity", "opencode"];
+export type AgentTarget = (typeof TARGETS)[number];
+export type AgentProfile = "plugin" | "project";
+export type MappingQuality = "exact" | "approximate" | "unsupported";
+export interface AgentDiagnostic {
+    code: string;
+    severity: "notice" | "warning" | "error";
+    message: string;
+    component?: string;
+    path?: string;
+    target?: AgentTarget;
+    profile?: AgentProfile;
+    quality: MappingQuality;
+    remediation?: string;
+}
+export interface SourceFile {
+    path: string;
+    content: Buffer;
+    mode: number;
+}
+export interface MarkdownComponent {
+    name: string;
+    description: string;
+    path: string;
+    metadata: Record<string, unknown>;
+    body: string;
+    files: SourceFile[];
+}
+export interface BundleRule extends MarkdownComponent {
+    activation: "always" | "files" | "model" | "manual";
+    globs: string[];
+}
+/**
+ * A target-native overlay: files copied verbatim into one target's output,
+ * keyed by the output profile they belong to. This is how a platform-only
+ * feature reaches the generated tree without being given a false portable
+ * abstraction.
+ */
+export interface NativeOverlay {
+    target: AgentTarget;
+    /** Absolute path to the overlay root. */
+    root: string;
+    /** Overlay files, POSIX-relative to `root/<profile>`, per output profile. */
+    files: Record<AgentProfile, SourceFile[]>;
+    /** `native/<target>/manifest.json`, merged over the generated plugin manifest. */
+    manifest?: Record<string, unknown>;
+    /**
+     * What happens when an overlay file claims a path a portable artifact already
+     * produced. Defaults to `overlay-wins`: an overlay is a deliberate,
+     * target-specific statement, so honoring it and reporting AB181 beats
+     * discarding it silently. `error` refuses the whole conversion instead.
+     */
+    onCollision: "overlay-wins" | "error";
+}
+export interface AgentBundle {
+    schemaVersion: string;
+    name: string;
+    version: string;
+    description: string;
+    root: string;
+    legacy: boolean;
+    manifest: Record<string, unknown>;
+    /** Declared listing metadata. Read by `agent package`; ignored by `agent convert`. */
+    marketplace?: BundleMarketplace;
+    /** Loaded native overlays. Always empty on a v1 or legacy bundle. */
+    overlays: NativeOverlay[];
+    skills: MarkdownComponent[];
+    agents: MarkdownComponent[];
+    rules: BundleRule[];
+    hooks?: {
+        path: string;
+        value: Record<string, unknown>;
+    };
+    hookFiles: SourceFile[];
+    policies: Array<{
+        path: string;
+        value: Record<string, unknown>;
+    }>;
+    mcp?: {
+        path: string;
+        value: Record<string, unknown>;
+    };
+    assets: SourceFile[];
+    diagnostics: AgentDiagnostic[];
+    graph: Record<string, string[]>;
+}
+export type ArtifactOrigin = "portable" | "native";
+export interface Artifact {
+    path: string;
+    content: Buffer;
+    mode: number;
+    /**
+     * Absent means "portable". Only overlay-sourced artifacts set it, which is
+     * what keeps `conversion-report.json` byte-identical for every bundle that
+     * has no overlay.
+     */
+    origin?: ArtifactOrigin;
+}
+export type HostStatus = "unknown" | "unverified" | "below-minimum" | "verified" | "newer";
+export interface HostReport {
+    target: AgentTarget;
+    /** The version supplied via `--host-version`, or `null` when none was given. */
+    requested: string | null;
+    minimumVersion: string | null;
+    verifiedThrough: string | null;
+    documentationRevision: string;
+    status: HostStatus;
+}
+export interface DoctorReport {
+    /** One row per selected target, present even when no host version is known. */
+    hosts: HostReport[];
+    /** Populated only when `--output` was given. */
+    output?: {
+        root: string;
+        missing: string[];
+        changed: string[];
+        unmanaged: string[];
+    };
+    /** Rendered paths no target profile describes. */
+    undeclared: Array<{
+        target: AgentTarget;
+        profile: AgentProfile;
+        path: string;
+    }>;
+    /**
+     * Paths contributed by a native overlay. These are exempt from the declared
+     * path check by design — being outside the profile is what an overlay is for —
+     * so they are reported positively here rather than as `undeclared` findings.
+     */
+    overlays: Array<{
+        target: AgentTarget;
+        profile: AgentProfile;
+        path: string;
+    }>;
+    /**
+     * Reserved for evidence from a host's own validator. Always empty in this
+     * release: `agent doctor` never spawns a process, so its result does not
+     * depend on what happens to be installed.
+     */
+    native: never[];
+}
+export type PlanAction = "create" | "update" | "skip";
+export interface PlanOperation {
+    action: PlanAction;
+    /** POSIX path relative to the plan root. */
+    path: string;
+    kind: string;
+    bytes: number;
+    /** Octal file mode, spelled as in `artifacts[].mode`. */
+    mode: string;
+    /** Why a `skip`, or what an `update` changes. */
+    reason?: string;
+}
+export interface AgentPlan {
+    root: string;
+    operations: PlanOperation[];
+}
+export interface AgentResult {
+    command: "convert" | "validate" | "inspect" | "compat" | "doctor" | "specs" | "init" | "add" | "upgrade" | "import" | "package" | "audit" | "test" | "install" | "uninstall" | "installed" | "marketplace";
+    ok: boolean;
+    source?: string;
+    targets: AgentTarget[];
+    profiles?: AgentProfile[];
+    artifacts: Array<{
+        path: string;
+        bytes: number;
+        mode: string;
+    }>;
+    diagnostics: AgentDiagnostic[];
+    bundle?: unknown;
+    compatibility?: unknown;
+    /** The full target conformance profiles, emitted by `agent specs`. */
+    specs?: unknown;
+    /** Conformance findings, emitted by `agent doctor`. */
+    doctor?: DoctorReport;
+    /** What a writing command did or would do, emitted by `agent init` and `agent add`. */
+    plan?: AgentPlan;
+    /** Migration result, emitted by `agent upgrade`. */
+    upgrade?: UpgradeReport;
+    /** Provenance report, emitted by `agent import`. */
+    import?: ImportReport;
+    /** Packaging result, emitted by `agent package`. */
+    package?: PackageReport;
+    /** Review surface and findings summary, emitted by `agent audit`. */
+    audit?: AuditReport;
+    /** Contract test results, emitted by `agent test`. */
+    test?: TestReport;
+    /** Install, uninstall, or listing result, emitted by the install commands. */
+    install?: InstallReport;
+    /** Collection build result, emitted by `agent marketplace`. */
+    marketplace?: MarketplaceReport;
+    dryRun?: boolean;
+    check?: boolean;
+    stale?: boolean;
+}
+export declare function diagnostic(code: string, message: string, quality: MappingQuality, extra?: Partial<AgentDiagnostic>): AgentDiagnostic;

package/dist/agent/types.js

@@ -0,0 +1,11 @@
+export const TARGETS = ["claude-code", "codex", "cursor", "antigravity", "opencode"];
+export function diagnostic(code, message, quality, extra = {}) {
+    return {
+        code,
+        severity: quality === "unsupported" ? "warning" : quality === "approximate" ? "warning" : "notice",
+        message,
+        quality,
+        ...extra,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/agent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,aAAa,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAU,CAAC;AA0M9F,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,OAAe,EACf,OAAuB,EACvB,QAAkC,EAAE;IAEpC,OAAO;QACL,IAAI;QACJ,QAAQ,EACN,OAAO,KAAK,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;QAC1F,OAAO;QACP,OAAO;QACP,GAAG,KAAK;KACT,CAAC;AACJ,CAAC"}

package/dist/agent/upgrade.d.ts

@@ -0,0 +1,29 @@
+import type { AgentBundle, AgentDiagnostic } from "./types.js";
+export interface MigrationChange {
+    field: string;
+    from: unknown;
+    to: unknown;
+}
+export interface UpgradeReport {
+    /** Source schema layer, spelled as the manifest spells it. */
+    from: string;
+    to: string;
+    changes: MigrationChange[];
+    /** Items a human should decide, mirrored as AB221 notices. */
+    notes: string[];
+}
+export interface UpgradePlan {
+    report: UpgradeReport;
+    /** The migrated manifest, or `null` when nothing needs to change. */
+    content: Buffer | null;
+    diagnostics: AgentDiagnostic[];
+}
+/**
+ * Plans a 1 -> 2 migration of `agent-bundle.yaml`.
+ *
+ * Only the manifest is rewritten; no component file is touched. Schema 2 is a
+ * strict superset of schema 1, so the migration is additive by construction —
+ * which is what makes the byte-identity guarantee checkable rather than hoped
+ * for. The caller verifies it by rendering before and after.
+ */
+export declare function planUpgrade(bundle: AgentBundle, source: string, to: string): UpgradePlan;

package/dist/agent/upgrade.js

@@ -0,0 +1,72 @@
+import { parseDocument } from "yaml";
+import { diagnostic } from "./types.js";
+import { COMPONENT_KEYS, CURRENT_BUNDLE_SCHEMA } from "./manifest.js";
+import { YAML_OPTIONS } from "./scaffold.js";
+function notice(code, message, path, remediation) {
+    return diagnostic(code, message, "exact", {
+        path,
+        ...(remediation ? { remediation } : {}),
+    });
+}
+function error(code, message, path, remediation) {
+    return {
+        ...diagnostic(code, message, "unsupported", { path, ...(remediation ? { remediation } : {}) }),
+        severity: "error",
+    };
+}
+/**
+ * Plans a 1 -> 2 migration of `agent-bundle.yaml`.
+ *
+ * Only the manifest is rewritten; no component file is touched. Schema 2 is a
+ * strict superset of schema 1, so the migration is additive by construction —
+ * which is what makes the byte-identity guarantee checkable rather than hoped
+ * for. The caller verifies it by rendering before and after.
+ */
+export function planUpgrade(bundle, source, to) {
+    const manifestPath = `${bundle.root}/agent-bundle.yaml`;
+    const diagnostics = [];
+    const report = {
+        from: bundle.schemaVersion,
+        to,
+        changes: [],
+        notes: [],
+    };
+    if (to !== CURRENT_BUNDLE_SCHEMA) {
+        diagnostics.push(error("AB222", `Unsupported target schema '${to}'`, manifestPath, `Use --to-schema ${CURRENT_BUNDLE_SCHEMA}.`));
+        return { report, content: null, diagnostics };
+    }
+    if (bundle.legacy) {
+        diagnostics.push(error("AB223", "A legacy Claude plugin has no neutral manifest to upgrade", manifestPath, "Run agent import to produce a portable bundle first."));
+        return { report, content: null, diagnostics };
+    }
+    if (bundle.schemaVersion === CURRENT_BUNDLE_SCHEMA) {
+        diagnostics.push(notice("AB220", `Bundle is already at schemaVersion ${to}`, manifestPath));
+        return { report, content: null, diagnostics };
+    }
+    const document = parseDocument(source);
+    document.setIn(["schemaVersion"], to);
+    report.changes.push({ field: "schemaVersion", from: bundle.schemaVersion, to });
+    // v1 allowed component paths both at the top level and under `components`.
+    // v2 prefers the nested form, so hoist them; the parser still honors either.
+    for (const key of COMPONENT_KEYS) {
+        const value = document.getIn([key]);
+        if (value === undefined)
+            continue;
+        if (document.getIn(["components", key]) === undefined) {
+            document.setIn(["components", key], value);
+            report.changes.push({ field: `components.${key}`, from: undefined, to: value });
+        }
+        document.deleteIn([key]);
+        report.changes.push({ field: key, from: value, to: undefined });
+    }
+    // Marketplace metadata is deliberately not synthesized. A half-filled block
+    // would look like a decision nobody made, and `agent package` would then
+    // report findings against values this migration invented.
+    if (!bundle.marketplace) {
+        report.notes.push("Add a marketplace: block before packaging; displayName, categories, publisher, and license cannot be derived.");
+        diagnostics.push(notice("AB221", "Marketplace metadata cannot be derived from a v1 bundle", manifestPath, "Add a marketplace: block before running agent package."));
+    }
+    report.notes.push("Native overlays are now available under native/<target>/; nothing was created because none existed.");
+    return { report, content: Buffer.from(document.toString(YAML_OPTIONS)), diagnostics };
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/agent/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../src/agent/upgrade.ts"],"names":[],"mappings":"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"}

package/dist/agent/writer.d.ts

@@ -0,0 +1,30 @@
+import type { Artifact } from "./types.js";
+export interface WriteOptions {
+    /**
+     * Directories, relative to the output root, that this write owns entirely.
+     * Each is replaced wholesale, so a component removed from the source stops
+     * existing in the output instead of lingering as an orphan.
+     */
+    managedRoots: string[];
+    /** Artifacts at the output root that are replaced individually, not by directory. */
+    looseFiles?: string[];
+    /** Replace a nonempty managed root instead of refusing. */
+    force: boolean;
+}
+/**
+ * Writes every artifact under `root` through a staging directory.
+ *
+ * The staging directory is a sibling of the output root rather than a temp
+ * directory, so it is on the same filesystem and the final `rename` is atomic.
+ * Nothing is visible at the destination until every artifact has been written
+ * successfully.
+ */
+export declare function writeArtifactsAtomically(root: string, artifacts: Artifact[], options: WriteOptions): void;
+/**
+ * Places `linkPath` as a symlink to `target`.
+ *
+ * Replaces whatever is already at `linkPath`. Occupancy checks belong to the
+ * caller; this is the write. The target is stored as an absolute path so the
+ * link keeps working after the process changes directory.
+ */
+export declare function placeSymlink(linkPath: string, target: string): void;

package/dist/agent/writer.js

@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import path from "node:path";
+function nonempty(directory) {
+    if (!fs.existsSync(directory))
+        return false;
+    return !fs.statSync(directory).isDirectory() || fs.readdirSync(directory).length > 0;
+}
+/**
+ * Writes every artifact under `root` through a staging directory.
+ *
+ * The staging directory is a sibling of the output root rather than a temp
+ * directory, so it is on the same filesystem and the final `rename` is atomic.
+ * Nothing is visible at the destination until every artifact has been written
+ * successfully.
+ */
+export function writeArtifactsAtomically(root, artifacts, options) {
+    for (const managed of options.managedRoots) {
+        const destination = path.join(root, managed);
+        if (nonempty(destination) && !options.force)
+            throw new Error(`Destination is nonempty: ${destination} (use --force)`);
+    }
+    const parent = path.dirname(root);
+    fs.mkdirSync(parent, { recursive: true });
+    const staging = fs.mkdtempSync(path.join(parent, `.${path.basename(root)}.staging-`));
+    try {
+        for (const artifact of artifacts) {
+            const destination = path.join(staging, artifact.path);
+            fs.mkdirSync(path.dirname(destination), { recursive: true });
+            fs.writeFileSync(destination, artifact.content, { mode: artifact.mode });
+            fs.chmodSync(destination, artifact.mode);
+        }
+        fs.mkdirSync(root, { recursive: true });
+        for (const managed of options.managedRoots) {
+            const destination = path.join(root, managed);
+            const staged = path.join(staging, managed);
+            if (fs.existsSync(destination))
+                fs.rmSync(destination, { recursive: true, force: true });
+            fs.mkdirSync(path.dirname(destination), { recursive: true });
+            if (fs.existsSync(staged))
+                fs.renameSync(staged, destination);
+            else
+                fs.mkdirSync(destination, { recursive: true });
+        }
+        for (const loose of options.looseFiles ?? []) {
+            const destination = path.join(root, loose);
+            const staged = path.join(staging, loose);
+            if (!fs.existsSync(staged))
+                continue;
+            if (fs.existsSync(destination))
+                fs.rmSync(destination, { recursive: true, force: true });
+            fs.mkdirSync(path.dirname(destination), { recursive: true });
+            fs.renameSync(staged, destination);
+        }
+    }
+    finally {
+        fs.rmSync(staging, { recursive: true, force: true });
+    }
+}
+/**
+ * Places `linkPath` as a symlink to `target`.
+ *
+ * Replaces whatever is already at `linkPath`. Occupancy checks belong to the
+ * caller; this is the write. The target is stored as an absolute path so the
+ * link keeps working after the process changes directory.
+ */
+export function placeSymlink(linkPath, target) {
+    const resolved = path.resolve(target);
+    fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+    if (fs.lstatSync(linkPath, { throwIfNoEntry: false }))
+        fs.rmSync(linkPath, { recursive: true, force: true });
+    fs.symlinkSync(resolved, linkPath);
+}
+//# sourceMappingURL=writer.js.map

package/dist/agent/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/agent/writer.ts"],"names":[],"mappings":"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"}

package/dist/archive/db.d.ts

@@ -0,0 +1,20 @@
+import type { Migration, StoreHandle } from "../sqlite-store.js";
+export declare const MIGRATIONS: readonly Migration[];
+export declare const LATEST_VERSION: number;
+/**
+ * Where the archive lives.
+ *
+ * Under `XDG_DATA_HOME` like the usage store, and for a stronger version of the
+ * same reason: this one holds the only copy of files whose originals may since
+ * have been deleted. `--archive` points it somewhere else — external or network
+ * storage — which is the expected shape once transcripts are included.
+ */
+export declare function getArchiveRoot(env?: NodeJS.ProcessEnv, homedir?: string): string;
+export declare function indexPath(root: string): string;
+export declare function segmentsDirectory(root: string): string;
+export interface OpenArchiveOptions {
+    root: string;
+    readOnly?: boolean;
+    migrate?: boolean;
+}
+export declare function openArchive(options: OpenArchiveOptions): StoreHandle;

package/dist/archive/db.js

@@ -0,0 +1,98 @@
+import os from "node:os";
+import path from "node:path";
+import { latestVersion, openStore } from "../sqlite-store.js";
+/**
+ * The archive index.
+ *
+ * Content-addressed, which is what makes the archive incremental in both
+ * directions at once. A file whose bytes have not changed is already a `blob`
+ * and is not stored again; a file whose bytes *have* changed gets a second
+ * `artifact` row against a new blob, so the archive keeps every version it ever
+ * saw without anyone asking it to.
+ *
+ * The index is a convenience, not the archive. Every segment is a plain
+ * `.tar.gz` whose members are named by their own hash, so `tar tzf` recovers the
+ * contents with no database and no `cairn` — which is the whole point of
+ * choosing a standard container for something meant to outlive the tool.
+ */
+const SCHEMA_V1 = `
+CREATE TABLE meta(
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE segment(
+  id        INTEGER PRIMARY KEY,
+  name      TEXT    NOT NULL UNIQUE,
+  bytes     INTEGER NOT NULL,
+  blobs     INTEGER NOT NULL,
+  sha256    TEXT    NOT NULL,
+  sealed_at TEXT    NOT NULL
+);
+
+CREATE TABLE blob(
+  sha256     TEXT    PRIMARY KEY,
+  size       INTEGER NOT NULL,
+  segment_id INTEGER NOT NULL REFERENCES segment(id),
+  offset     INTEGER NOT NULL,
+  stored_at  TEXT    NOT NULL
+);
+
+CREATE TABLE artifact(
+  id         INTEGER PRIMARY KEY,
+  provider   TEXT    NOT NULL,
+  set_id     TEXT    NOT NULL,
+  class      TEXT    NOT NULL,
+  path       TEXT    NOT NULL,
+  sha256     TEXT    NOT NULL REFERENCES blob(sha256),
+  size       INTEGER NOT NULL,
+  mtime_ms   REAL    NOT NULL,
+  mode       INTEGER NOT NULL,
+  first_seen TEXT    NOT NULL,
+  last_seen  TEXT    NOT NULL,
+  UNIQUE(provider, path, sha256)
+);
+
+CREATE INDEX artifact_path  ON artifact(provider, path);
+CREATE INDEX artifact_class ON artifact(class, last_seen);
+CREATE INDEX blob_segment   ON blob(segment_id);
+`;
+export const MIGRATIONS = [
+    {
+        version: 1,
+        description: "Initial schema: segments, blobs, and artifact path history",
+        up(db) {
+            db.exec(SCHEMA_V1);
+        },
+    },
+];
+export const LATEST_VERSION = latestVersion(MIGRATIONS);
+/**
+ * Where the archive lives.
+ *
+ * Under `XDG_DATA_HOME` like the usage store, and for a stronger version of the
+ * same reason: this one holds the only copy of files whose originals may since
+ * have been deleted. `--archive` points it somewhere else — external or network
+ * storage — which is the expected shape once transcripts are included.
+ */
+export function getArchiveRoot(env = process.env, homedir = os.homedir()) {
+    const configured = env.XDG_DATA_HOME?.trim();
+    const base = configured ? configured : path.join(homedir, ".local", "share");
+    return path.join(base, "cairn", "archive");
+}
+export function indexPath(root) {
+    return path.join(root, "archive.db");
+}
+export function segmentsDirectory(root) {
+    return path.join(root, "segments");
+}
+export function openArchive(options) {
+    return openStore({
+        path: indexPath(options.root),
+        migrations: MIGRATIONS,
+        label: "archive index",
+        ...(options.readOnly === true ? { readOnly: true } : {}),
+        ...(options.migrate === false ? { migrate: false } : {}),
+    });
+}
+//# sourceMappingURL=db.js.map

package/dist/archive/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/archive/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;;;;;;;;GAaG;AACH,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCjB,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAyB;IAC9C;QACE,OAAO,EAAE,CAAC;QACV,WAAW,EAAE,4DAA4D;QACzE,EAAE,CAAC,EAAE;YACH,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAW,aAAa,CAAC,UAAU,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAyB,OAAO,CAAC,GAAG,EACpC,UAAkB,EAAE,CAAC,OAAO,EAAE;IAE9B,MAAM,UAAU,GAAG,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC;IAC7C,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC7E,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACrC,CAAC;AAQD,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,OAAO,SAAS,CAAC;QACf,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;QAC7B,UAAU,EAAE,UAAU;QACtB,KAAK,EAAE,eAAe;QACtB,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzD,CAAC,CAAC;AACL,CAAC"}

package/dist/archive/progress.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Progress reporting for a long archive run.
+ *
+ * A full run is tens of thousands of files and several gigabytes, and without
+ * this it printed nothing at all until it finished. Two levels, because they
+ * answer different questions:
+ *
+ * - the **transient line** answers "is it still going, and how far in" — it
+ *   rewrites itself in place, so it belongs only on a terminal
+ * - **verbose** answers "what exactly did it do to which file" — one durable
+ *   line per artifact, so it is worth redirecting to a file and grepping later
+ *
+ * The transient line is gated the same way the update notifier is: stderr must
+ * be a TTY, the format must not be machine-readable, and `CI` must be unset.
+ * Those gates exist because a `\r`-rewritten line is corruption in a log file
+ * and noise in a CI transcript. Verbose has no such gate — being redirectable is
+ * the whole point of it.
+ */
+export type Disposition = "stored" | "duplicate" | "unchanged" | "skipped";
+export interface FileEvent {
+    path: string;
+    class: string;
+    size: number;
+    disposition: Disposition;
+    /** Absent for `unchanged`, which is decided without opening the file. */
+    sha256?: string;
+}
+export interface SegmentEvent {
+    name: string;
+    bytes: number;
+    blobs: number;
+}
+/** What `runArchive` reports as it goes. Every hook is optional. */
+export interface RunReporter {
+    start?(total: {
+        files: number;
+        bytes: number;
+    }): void;
+    file?(event: FileEvent): void;
+    segment?(event: SegmentEvent): void;
+    failure?(event: {
+        file: string;
+        reason: string;
+    }): void;
+    finish?(): void;
+}
+export interface ReporterOptions {
+    /** Draw the transient status line. */
+    progress: boolean;
+    /** Emit one durable line per artifact. */
+    verbose: boolean;
+    stream?: NodeJS.WriteStream;
+    now?: () => number;
+}
+/**
+ * Decides whether the transient line may be drawn.
+ *
+ * Kept separate from the reporter so the command can report the decision, and
+ * so the rule is testable without a terminal.
+ */
+export declare function progressAllowed(format: string, stream?: NodeJS.WriteStream, env?: NodeJS.ProcessEnv): boolean;
+export declare function createReporter(options: ReporterOptions): RunReporter;