ghcr-manager 0.0.4

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.4] - 2026-04-30
+
+### Changed
+
+- Publish to npmjs
+
+## [0.0.3] - 2026-04-30
+
+### Changed
+
+- Released on GitHub marketplace as public action
+
+## [0.0.1] - 2026-04-30
+
+### Added
+
+- Initial public release of `ghcr-manager` as a GitHub Action plus companion CLI.
+- GHCR scan flow that loads package versions, tags, manifests, descriptors, and manifest graph edges into SQLite.
+- Manifest reachability precomputation (`manifest_reachability`) for fast graph-based analysis queries.
+- Raw payload storage for GitHub package-version items and GHCR manifests (`package_version_payloads`,
+  `manifest_payloads`).
+- Scan lifecycle tracking with scan history (`package_scans`) and status transitions (`running|completed|failed`).
+- Immutable per-scan UUID (`package_scans.scan_uuid`) for robust duplicate detection across merged databases.
+- Optional action artifact upload for scan DB export (`upload-db-artifact`, optional retention override).
+- Manual workflow for interactive scan runs (`.github/workflows/manual-run.yml`).
+- Missing-manifest investigation SQL recipes (`docs/missing-manifests-queries.md`) and schema/terminology docs.
+
+### Changed
+
+- Enforced stricter repository conventions:
+  - source/test tree mirroring
+  - cross-folder imports via folder `index.ts`
+  - internal source naming (`_*.ts`)
+- Hardened CI/workflows with explicit token permissions and immutable action reference checks.
+- Refined action/runtime flow to focus on scan + DB export behavior for this release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gh-workflow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# ghcr-manager
+
+[![Release](https://img.shields.io/github/v/release/gh-workflow/ghcr-manager?style=flat-square)](https://github.com/gh-workflow/ghcr-manager/releases)
+[![Immutable Releases](https://img.shields.io/badge/releases-immutable-blue?labelColor=333)](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases)
+[![GitHub Marketplace](https://img.shields.io/badge/marketplace-ghcr--manager-blue?logo=github&labelColor=333&style=flat-square)](https://github.com/marketplace/actions/ghcr-manager)
+[![Tests](https://img.shields.io/github/actions/workflow/status/gh-workflow/ghcr-manager/change-validation.yml?branch=main&label=test&style=flat-square)](https://github.com/gh-workflow/ghcr-manager/actions/workflows/change-validation.yml)
+[![Usage](https://img.shields.io/badge/image-GHCR-2496ED?logo=docker&logoColor=white&style=flat-square)](#usage)
+
+Inspect, analyze, and manage GitHub Container Registry packages.
+
+`ghcr-manager` is a public GitHub Action and companion CLI for safe GHCR cleanup and inspection, with a focus on large
+packages and correct handling of multi-arch images, referrers, and attestations.
+
+## Scope
+
+- :white_check_mark: Full package and manifest scan per run for correctness
+- :white_check_mark: Export database of Container Registry from runs for local analysis
+- :construction: Safe cleanup of GHCR image artifacts in GitHub packages
+
+## How
+
+### :white_check_mark: Data Loading
+
+1. Writes Container Registry metadata to a database
+2. Pre-processes data for optimized lookups
+3. Optional: Export of database from runs for local analysis
+
+> :construction: Planned: Support for merging several such databases into one for local analysis
+
+### :construction: Consistency Check
+
+1. Run consistency check against the database
+2. Optional: Export report of missing manifests from runs
+
+### :construction: Safe cleanup of GHCR image artifacts
+
+1. Use filter input to query database for related artifacts (images and manifests)
+2. Optional `dry-run`: Export which image artifacts would be deleted
+3. Delete image artifacts (without `dry-run`)
+
+## Usage
+
+```yaml
+concurrency:
+  group: ghcr-manager__${{ inputs.owner }}__${{ inputs.package }}
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+      actions: write # only required when upload-db-artifact is true
+    concurrency:
+      group: ghcr-manager
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Run ghcr-manager action
+        uses: gh-workflow/ghcr-manager@0.0.4
+        with:
+          github-token: ${{ github.token }}
+          owner: OWNER
+          package: PACKAGE
+          upload-db-artifact: true
+```
+
+> Copy the [Manual Run Workflow](.github/workflows/manual-run.yml) as a ready-to-run manual scan workflow.
+
+## Inputs
+
+<!-- markdownlint-disable MD013 -->
+
+| Input                        | Description                                                     | Required | Default                        |
+| ---------------------------- | --------------------------------------------------------------- | -------- | ------------------------------ |
+| `github-token`               | GitHub token used for GitHub/GHCR API calls                     | Yes      | `${{ github.token }}`          |
+| `owner`                      | GitHub owner of the container package (user or org)             | Yes      |                                |
+| `package`                    | Container package name                                          | Yes      |                                |
+| `upload-db-artifact`         | Whether to upload the scan database as a workflow run artifact  | No       | `false`                        |
+| `db-artifact-retention-days` | Optional retention days override for uploaded database artifact | No       | `${{ github.retention_days }}` |
+
+<!-- markdownlint-enable MD013 -->
+
+## Outputs
+
+| Output    | Description                                             |
+| --------- | ------------------------------------------------------- |
+| `db-path` | Path to the SQLite database in the GitHub action runner |
+
+## Artifacts
+
+<!-- markdownlint-disable MD013 -->
+
+| Name                          | Filename                          | Description                                                          |
+| ----------------------------- | --------------------------------- | -------------------------------------------------------------------- |
+| `${OWNER}__${PACKAGE}.sqlite` | `${OWNER}__${PACKAGE}.sqlite.zip` | Zipped SQLite database containing GitHub Container Registry metadata |
+
+<!-- markdownlint-enable MD013 -->

package/dist/cli/_args.d.ts

@@ -0,0 +1,6 @@
+import { type LogLevel } from "./_logger.js";
+export declare function requireOption(args: string[], name: string): string;
+export declare function findOption(args: string[], name: string): string | undefined;
+export declare function collectRepeatedOption(args: string[], name: string): string[];
+export declare function resolveGitHubToken(args: string[]): string;
+export declare function resolveLogLevel(args: string[]): LogLevel;

package/dist/cli/_args.js

@@ -0,0 +1,38 @@
+import { isLogLevel } from "./_logger.js";
+export function requireOption(args, name) {
+    const value = findOption(args, name);
+    if (!value) {
+        throw new Error(`missing required option: ${name}`);
+    }
+    return value;
+}
+export function findOption(args, name) {
+    const index = args.indexOf(name);
+    if (index < 0) {
+        return undefined;
+    }
+    return args[index + 1];
+}
+export function collectRepeatedOption(args, name) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === name && args[index + 1]) {
+            values.push(args[index + 1]);
+        }
+    }
+    return values;
+}
+export function resolveGitHubToken(args) {
+    const cliToken = findOption(args, "--token");
+    if (cliToken) {
+        return cliToken;
+    }
+    throw new Error("missing required option: --token");
+}
+export function resolveLogLevel(args) {
+    const rawLevel = findOption(args, "--log-level") ?? "info";
+    if (!isLogLevel(rawLevel)) {
+        throw new Error(`invalid log level: ${rawLevel}`);
+    }
+    return rawLevel;
+}

package/dist/cli/_logger.d.ts

@@ -0,0 +1,9 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+export interface Logger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export declare function isLogLevel(value: string): value is LogLevel;
+export declare function createLogger(level: LogLevel, sink?: NodeJS.WritableStream): Logger;

package/dist/cli/_logger.js

@@ -0,0 +1,24 @@
+const _logLevelPriority = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: 50
+};
+export function isLogLevel(value) {
+    return value in _logLevelPriority;
+}
+export function createLogger(level, sink = process.stderr) {
+    return {
+        debug: _write.bind(null, "debug", level, sink),
+        info: _write.bind(null, "info", level, sink),
+        warn: _write.bind(null, "warn", level, sink),
+        error: _write.bind(null, "error", level, sink)
+    };
+}
+function _write(level, threshold, sink, message) {
+    if (_logLevelPriority[level] < _logLevelPriority[threshold]) {
+        return;
+    }
+    sink.write(`${new Date().toISOString()} ${level.toUpperCase()} ${message}\n`);
+}

package/dist/cli/_scan-command.d.ts

@@ -0,0 +1 @@
+export declare function handleScan(args: string[]): Promise<number>;

package/dist/cli/_scan-command.js

@@ -0,0 +1,32 @@
+import { ScanWriter, SnapshotRepository, openDatabase } from "../db/index.js";
+import { importGitHubScan } from "../ingest/github/index.js";
+import { requireOption, resolveGitHubToken, resolveLogLevel } from "./_args.js";
+import { createLogger } from "./_logger.js";
+export async function handleScan(args) {
+    const databasePath = requireOption(args, "--db");
+    const owner = requireOption(args, "--owner");
+    const packageName = requireOption(args, "--package");
+    const logger = createLogger(resolveLogLevel(args));
+    const database = openDatabase(databasePath);
+    const repository = new SnapshotRepository(database);
+    const writer = new ScanWriter(database);
+    await importGitHubScan({
+        owner,
+        packageName,
+        token: resolveGitHubToken(args),
+        logger
+    }, writer, repository);
+    const scanId = writer.getActiveScanId();
+    const metadata = repository.getPackageMetadata(scanId);
+    console.log(JSON.stringify({
+        owner: metadata.owner,
+        packageName: metadata.packageName,
+        scanCompletedAt: metadata.scanCompletedAt,
+        packageVersions: repository.countPackageVersions(scanId),
+        tags: repository.countTags(scanId),
+        manifests: repository.countManifests(scanId),
+        manifestEdges: repository.countManifestEdges(scanId)
+    }, null, 2));
+    database.close();
+    return 0;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): Promise<number>;

package/dist/cli/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { handleScan } from "./_scan-command.js";
+export async function main(argv) {
+    const [command, ...rest] = argv;
+    if (!command) {
+        printUsage();
+        return 1;
+    }
+    switch (command) {
+        case "scan":
+            return handleScan(rest);
+        default:
+            throw new Error(`unknown command: ${command}`);
+    }
+}
+function printUsage() {
+    console.error(`Usage:
+  ghcr-manager scan --db <path> [--log-level <debug|info|warn|error|silent>] --owner <org> --package <name> --token <token>`);
+}
+const _entryPath = process.argv[1];
+const _isDirectExecution = realpathSync(_entryPath) === realpathSync(fileURLToPath(import.meta.url));
+if (_isDirectExecution) {
+    main(process.argv.slice(2)).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        process.exitCode = 1;
+    });
+}

package/dist/core/_types.d.ts

@@ -0,0 +1,49 @@
+export interface PackageVersionRecord {
+    versionId: number;
+    digest: string;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TagRecord {
+    tag: string;
+    digest: string;
+    versionId: number;
+}
+export interface ManifestRecord {
+    digest: string;
+    mediaType: string;
+    artifactType?: string;
+    configMediaType?: string;
+    subjectDigest?: string;
+    annotations?: Record<string, unknown>;
+    platform?: {
+        architecture?: string;
+        os?: string;
+        variant?: string;
+    };
+}
+export interface ManifestDescriptorRecord {
+    parentDigest: string;
+    childDigest: string;
+    mediaType: string;
+    artifactType?: string;
+    platform?: {
+        architecture?: string;
+        os?: string;
+        variant?: string;
+    };
+}
+export interface ManifestEdgeRecord {
+    parentDigest: string;
+    childDigest: string;
+    edgeKind: "image-child" | "referrer";
+}
+export interface PackageSnapshot {
+    packageName: string;
+    scanCompletedAt: string;
+    packageVersions: PackageVersionRecord[];
+    tags: TagRecord[];
+    manifests: ManifestRecord[];
+    manifestEdges: ManifestEdgeRecord[];
+}

package/dist/core/_types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/index.d.ts

@@ -0,0 +1 @@
+export type { ManifestEdgeRecord, ManifestDescriptorRecord, ManifestRecord, PackageSnapshot, PackageVersionRecord, TagRecord } from "./_types.js";

package/dist/core/index.js

@@ -0,0 +1 @@
+export {};

package/dist/db/_manifest-reachability.d.ts

@@ -0,0 +1,2 @@
+import type Database from "better-sqlite3";
+export declare function rebuildManifestReachability(database: Database.Database, scanId: number): void;

package/dist/db/_manifest-reachability.js

@@ -0,0 +1,94 @@
+export function rebuildManifestReachability(database, scanId) {
+    const manifestDigests = _loadManifestDigests(database, scanId);
+    const childDigestsByParent = new Map();
+    const parentDigestsByChild = new Map();
+    for (const digest of manifestDigests) {
+        childDigestsByParent.set(digest, new Set());
+        parentDigestsByChild.set(digest, new Set());
+    }
+    for (const manifestEdge of _loadManifestEdges(database, scanId)) {
+        childDigestsByParent.get(manifestEdge.parent_digest)?.add(manifestEdge.child_digest);
+        parentDigestsByChild.get(manifestEdge.child_digest)?.add(manifestEdge.parent_digest);
+    }
+    const remainingChildrenCount = new Map();
+    const descendantDistancesByDigest = new Map();
+    const readyDigests = [];
+    for (const digest of manifestDigests) {
+        const childCount = childDigestsByParent.get(digest)?.size ?? 0;
+        remainingChildrenCount.set(digest, childCount);
+        if (childCount === 0) {
+            readyDigests.push(digest);
+        }
+    }
+    while (readyDigests.length > 0) {
+        const digest = readyDigests.shift();
+        if (!digest) {
+            continue;
+        }
+        const distances = new Map([[digest, 0]]);
+        for (const childDigest of childDigestsByParent.get(digest) ?? []) {
+            _setMinDistance(distances, childDigest, 1);
+            const childDistances = descendantDistancesByDigest.get(childDigest);
+            if (!childDistances) {
+                throw new Error(`manifest reachability build missing child results for ${childDigest}`);
+            }
+            for (const [descendantDigest, childDistance] of childDistances) {
+                if (descendantDigest === childDigest) {
+                    continue;
+                }
+                _setMinDistance(distances, descendantDigest, childDistance + 1);
+            }
+        }
+        descendantDistancesByDigest.set(digest, distances);
+        for (const parentDigest of parentDigestsByChild.get(digest) ?? []) {
+            const nextCount = (remainingChildrenCount.get(parentDigest) ?? 0) - 1;
+            remainingChildrenCount.set(parentDigest, nextCount);
+            if (nextCount === 0) {
+                readyDigests.push(parentDigest);
+            }
+        }
+    }
+    if (descendantDistancesByDigest.size !== manifestDigests.length) {
+        throw new Error("manifest reachability build detected a cycle in manifest_edges");
+    }
+    const insertRow = database.prepare(`
+      INSERT OR REPLACE INTO manifest_reachability(
+        scan_id,
+        ancestor_digest,
+        descendant_digest,
+        min_distance
+      )
+      VALUES(?, ?, ?, ?)
+    `);
+    const rebuild = database.transaction(() => {
+        database.prepare("DELETE FROM manifest_reachability WHERE scan_id = ?").run(scanId);
+        for (const digest of manifestDigests) {
+            for (const [descendantDigest, distance] of descendantDistancesByDigest.get(digest) ?? []) {
+                insertRow.run(scanId, digest, descendantDigest, distance);
+            }
+        }
+    });
+    rebuild();
+}
+function _loadManifestDigests(database, scanId) {
+    const rows = database
+        .prepare("SELECT digest FROM manifests WHERE scan_id = ? ORDER BY digest")
+        .all(scanId);
+    return rows.map((row) => row.digest);
+}
+function _loadManifestEdges(database, scanId) {
+    return database
+        .prepare(`
+        SELECT DISTINCT parent_digest, child_digest
+        FROM manifest_edges
+        WHERE scan_id = ?
+        ORDER BY parent_digest, child_digest
+      `)
+        .all(scanId);
+}
+function _setMinDistance(distances, digest, distance) {
+    const currentDistance = distances.get(digest);
+    if (currentDistance === undefined || distance < currentDistance) {
+        distances.set(digest, distance);
+    }
+}

package/dist/db/_scan-writer.d.ts

@@ -0,0 +1,18 @@
+import type Database from "better-sqlite3";
+import type { ManifestDescriptorRecord, ManifestEdgeRecord, ManifestRecord, PackageVersionRecord, TagRecord } from "../core/index.js";
+export declare class ScanWriter {
+    #private;
+    constructor(database: Database.Database);
+    resetScan(owner: string, packageName: string, scanStartedAt: string): void;
+    markScanCompleted(scanCompletedAt: string): void;
+    markScanFailed(scanCompletedAt: string): void;
+    insertPackageVersion(version: PackageVersionRecord): void;
+    insertPackageVersionPayload(versionId: number, rawJson: string): void;
+    insertTag(tag: TagRecord): void;
+    insertManifest(manifest: ManifestRecord): void;
+    insertManifestPayload(digest: string, rawJson: string): void;
+    insertManifestDescriptor(descriptor: ManifestDescriptorRecord): void;
+    insertManifestEdge(edge: ManifestEdgeRecord): void;
+    rebuildManifestReachability(): void;
+    getActiveScanId(): number;
+}

package/dist/db/_scan-writer.js

@@ -0,0 +1,176 @@
+import { randomUUID } from "node:crypto";
+import { rebuildManifestReachability } from "./_manifest-reachability.js";
+export class ScanWriter {
+    #database;
+    #activeScanId = null;
+    constructor(database) {
+        this.#database = database;
+    }
+    resetScan(owner, packageName, scanStartedAt) {
+        const result = this.#database
+            .prepare(`
+        INSERT INTO package_scans(scan_uuid, owner, package_name, scan_started_at, scan_completed_at, status)
+        VALUES(?, ?, ?, ?, NULL, 'running')
+      `)
+            .run(randomUUID(), owner, packageName, scanStartedAt);
+        this.#activeScanId = Number(result.lastInsertRowid);
+    }
+    markScanCompleted(scanCompletedAt) {
+        this.#database
+            .prepare(`
+        UPDATE package_scans
+        SET scan_completed_at = ?, status = 'completed'
+        WHERE scan_id = ?
+      `)
+            .run(scanCompletedAt, this.#requireScanId());
+    }
+    markScanFailed(scanCompletedAt) {
+        this.#database
+            .prepare(`
+        UPDATE package_scans
+        SET scan_completed_at = ?, status = 'failed'
+        WHERE scan_id = ?
+      `)
+            .run(scanCompletedAt, this.#requireScanId());
+    }
+    insertPackageVersion(version) {
+        this.#database
+            .prepare(`
+        INSERT OR REPLACE INTO package_versions(scan_id, version_id, digest, created_at, updated_at)
+        VALUES(@scanId, @versionId, @digest, @createdAt, @updatedAt)
+      `)
+            .run({
+            scanId: this.#requireScanId(),
+            versionId: version.versionId,
+            digest: version.digest,
+            createdAt: version.createdAt,
+            updatedAt: version.updatedAt
+        });
+    }
+    insertPackageVersionPayload(versionId, rawJson) {
+        this.#database
+            .prepare(`
+        INSERT OR REPLACE INTO package_version_payloads(scan_id, version_id, raw_json)
+        VALUES(?, ?, ?)
+      `)
+            .run(this.#requireScanId(), versionId, rawJson);
+    }
+    insertTag(tag) {
+        this.#database
+            .prepare(`
+        INSERT OR REPLACE INTO tags(scan_id, tag, digest, version_id)
+        VALUES(@scanId, @tag, @digest, @versionId)
+      `)
+            .run({
+            scanId: this.#requireScanId(),
+            ...tag
+        });
+    }
+    insertManifest(manifest) {
+        this.#database
+            .prepare(`
+        INSERT OR REPLACE INTO manifests(
+          scan_id,
+          digest,
+          media_type,
+          artifact_type,
+          config_media_type,
+          subject_digest,
+          annotations_json,
+          platform_os,
+          platform_architecture,
+          platform_variant
+        )
+        VALUES(
+          @scanId,
+          @digest,
+          @mediaType,
+          @artifactType,
+          @configMediaType,
+          @subjectDigest,
+          @annotationsJson,
+          @platformOs,
+          @platformArchitecture,
+          @platformVariant
+        )
+      `)
+            .run({
+            scanId: this.#requireScanId(),
+            digest: manifest.digest,
+            mediaType: manifest.mediaType,
+            artifactType: manifest.artifactType ?? null,
+            configMediaType: manifest.configMediaType ?? null,
+            subjectDigest: manifest.subjectDigest ?? null,
+            annotationsJson: manifest.annotations ? JSON.stringify(manifest.annotations) : null,
+            platformOs: manifest.platform?.os ?? null,
+            platformArchitecture: manifest.platform?.architecture ?? null,
+            platformVariant: manifest.platform?.variant ?? null
+        });
+    }
+    insertManifestPayload(digest, rawJson) {
+        this.#database
+            .prepare(`
+        INSERT OR REPLACE INTO manifest_payloads(scan_id, digest, raw_json)
+        VALUES(?, ?, ?)
+      `)
+            .run(this.#requireScanId(), digest, rawJson);
+    }
+    insertManifestDescriptor(descriptor) {
+        this.#database
+            .prepare(`
+        INSERT OR REPLACE INTO manifest_descriptors(
+          scan_id,
+          parent_digest,
+          child_digest,
+          media_type,
+          artifact_type,
+          platform_os,
+          platform_architecture,
+          platform_variant
+        )
+        VALUES(
+          @scanId,
+          @parentDigest,
+          @childDigest,
+          @mediaType,
+          @artifactType,
+          @platformOs,
+          @platformArchitecture,
+          @platformVariant
+        )
+      `)
+            .run({
+            scanId: this.#requireScanId(),
+            parentDigest: descriptor.parentDigest,
+            childDigest: descriptor.childDigest,
+            mediaType: descriptor.mediaType,
+            artifactType: descriptor.artifactType ?? null,
+            platformOs: descriptor.platform?.os ?? null,
+            platformArchitecture: descriptor.platform?.architecture ?? null,
+            platformVariant: descriptor.platform?.variant ?? null
+        });
+    }
+    insertManifestEdge(edge) {
+        this.#database
+            .prepare(`
+        INSERT OR IGNORE INTO manifest_edges(scan_id, parent_digest, child_digest, edge_kind)
+        VALUES(@scanId, @parentDigest, @childDigest, @edgeKind)
+      `)
+            .run({
+            scanId: this.#requireScanId(),
+            ...edge
+        });
+    }
+    rebuildManifestReachability() {
+        rebuildManifestReachability(this.#database, this.#requireScanId());
+    }
+    getActiveScanId() {
+        return this.#requireScanId();
+    }
+    #requireScanId() {
+        if (this.#activeScanId === null) {
+            throw new Error("package not initialized; call resetScan(owner, packageName, scanStartedAt) first");
+        }
+        return this.#activeScanId;
+    }
+}

package/dist/db/_schema.d.ts

@@ -0,0 +1,2 @@
+import type Database from "better-sqlite3";
+export declare function initializeSchema(database: Database.Database): void;