Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
import type { Database } from "@carbon/database";
import type {
BackupCompatibilityStatus,
CompatibilityFinding,
Manifest
} from "@carbon/jobs/backups";
import type { SupabaseClient } from "@supabase/supabase-js";
import type { RowsByTable } from "./settings.utils";
// Company backup data access. Export is enqueued server-side
// (exportCompanyBackup in backups.server.ts) and runs in the
// carbon/company-export inngest job. Restore is also enqueued server-side (see
// backups.server.ts) and tracked via the externalIntegrationMapping marker
// (getCompanyRestoreRuns).
// A backup is a folder `exports/<name>/` of small objects: `manifest.json`, one
// `tables/<table>.ndjson.gz` per table, and `assets/<path>` files. Pre-restore
// snapshots use the same layout under a `_pre-restore-*` name. Must match the
// `backup*Path` helpers in packages/jobs/.../company-backup.ts.
const SNAPSHOT_PREFIX = "_pre-restore-";
/**
* One FK edge whose rows escape company scope, as the export/restore jobs record
* it in their failure marker. Typed here rather than imported from `@carbon/jobs`
* — the app must not pull job internals (and Node `Buffer` with them) into its
* bundle.
*/
export type ScopeViolationSummary = {
table: string;
column: string;
refTable: string;
rows: number;
};
/** Supabase storage caps a `list` call; page until a short page comes back. */
const BACKUP_LIST_PAGE_SIZE = 100;
const BACKUP_LIST_MAX_PAGES = 50;
/**
* Remove every object under a prefix (recursing into folders) so a deleted
* backup actually releases its bucket space rather than orphaning files.
*/
async function removeStoragePrefix(
client: SupabaseClient<Database>,
bucket: string,
prefix: string
) {
const { data } = await client.storage
.from(bucket)
.list(prefix, { limit: 1000 });
if (!data) return;
const files: string[] = [];
for (const entry of data) {
const path = `${prefix}/${entry.name}`;
if (entry.id === null) {
await removeStoragePrefix(client, bucket, path);
} else {
files.push(path);
}
}
if (files.length > 0) {
await client.storage.from(bucket).remove(files);
}
}
export type CompanyBackupSummary = {
/** Backup folder name (also the restore `source` identifier). */
name: string;
/** "ready" once manifest.json (the last-written commit marker) exists;
* "pending" while the export is still writing the folder. */
status: "ready" | "pending";
exportedAt: string | null;
label: string | null;
rows: number;
/** Total bundled asset bytes (the bulk of a backup's footprint). */
sizeBytes: number;
/**
* "Would this backup restore into TODAY's schema?" — computed live against
* the current schema by `getCompanyBackups` (settings.service.ts) on every
* load, never stored. The hard refusal is still `assertBackupImportable`
* inside the restore job; this is the same diff, disclosed upfront.
*
* `null` when the schema could not be read (database unreachable, pool
* exhausted). That is "we did not check", NOT "clean" — the row shows no
* badge and the restore screen says so. Never substitute a `ready` verdict
* here: claiming a backup is restorable without comparing anything is the
* exact failure this whole computation replaced.
*/
compatibility: {
status: BackupCompatibilityStatus;
findings: CompatibilityFinding[];
} | null;
/** Per-edge breakdown of what a `skipCorrupted` export left out; `[]` for a full export. */
excludedRows: NonNullable<Manifest["excludedRows"]>;
/** DISTINCT excluded rows per table — sum this, never `excludedRows`. */
excludedRowsByTable: RowsByTable[];
};
/**
* List a company's backup folders (`exports/<name>/`, snapshots excluded),
* reading each manifest for its metadata. Storage layer only: `compatibility`
* is a placeholder here — `getCompanyBackups` in settings.service.ts computes
* the real verdict from the returned `manifest` (server-only, since it needs
* `@carbon/jobs/backups` and a schema read) and strips it before the loader
* returns.
*/
export async function listCompanyBackupFolders(
client: SupabaseClient<Database>,
companyId: string
): Promise<{
data: (CompanyBackupSummary & { manifest: Manifest | null })[] | null;
error: Error | null;
}> {
// Paged: storage caps a list call, and an un-listed backup can be neither
// restored nor deleted. The page cap only guards a misbehaving storage
// response from looping forever.
const entries: Awaited<
ReturnType<ReturnType<typeof client.storage.from>["list"]>
>["data"] = [];
for (let page = 0; page < BACKUP_LIST_MAX_PAGES; page++) {
const { data, error } = await client.storage
.from(companyId)
.list("exports", {
limit: BACKUP_LIST_PAGE_SIZE,
offset: page * BACKUP_LIST_PAGE_SIZE
});
if (error) return { data: null, error };
entries.push(...(data ?? []));
if ((data?.length ?? 0) < BACKUP_LIST_PAGE_SIZE) break;
}
const folders = entries.filter(
(e) => e.id === null && !e.name.startsWith(SNAPSHOT_PREFIX)
);
const backups = await Promise.all(
folders.map(
async (
folder
): Promise<CompanyBackupSummary & { manifest: Manifest | null }> => {
const summary: CompanyBackupSummary & { manifest: Manifest | null } = {
name: folder.name,
status: "pending",
exportedAt: null,
label: null,
rows: 0,
sizeBytes: 0,
compatibility: null,
excludedRows: [],
excludedRowsByTable: [],
manifest: null
};
const mf = await client.storage
.from(companyId)
.download(`exports/${folder.name}/manifest.json`);
if (mf.data) {
try {
const m = JSON.parse(await mf.data.text()) as Manifest;
summary.status = "ready";
summary.exportedAt = m.exportedAt ?? null;
summary.label = m.label ?? null;
summary.rows = (m.tables ?? []).reduce(
(sum, t) => sum + (t.rows ?? 0),
0
);
summary.sizeBytes = (m.storage ?? [])
.filter((x) => x.included)
.reduce((sum, x) => sum + (x.size ?? 0), 0);
summary.excludedRows = m.excludedRows ?? [];
summary.excludedRowsByTable = m.excludedRowsByTable ?? [];
summary.manifest = { ...m, tables: m.tables ?? [] };
} catch {
// Manifest present but unreadable — treat as a partial/aborted
// export (stays "pending"); still listed so the user can delete it.
}
}
return summary;
}
)
);
backups.sort((a, b) =>
(b.exportedAt ?? "").localeCompare(a.exportedAt ?? "")
);
return { data: backups, error: null };
}
/** Delete a backup — the whole `exports/<name>/` folder (data + manifest + assets). */
export async function deleteCompanyBackup(
client: SupabaseClient<Database>,
companyId: string,
name: string
) {
await removeStoragePrefix(client, companyId, `exports/${name}`);
return { error: null as Error | null };
}
/**
* Pending in-place restore runs. One marker row per restore (integration =
* 'company-restore'), holding the pre-restore snapshot path in metadata. A row
* exists between the restore completing and the user keeping or reverting it.
*/
export async function getCompanyRestoreRuns(
client: SupabaseClient<Database>,
companyId: string
) {
const markers = await client
.from("externalIntegrationMapping")
.select("entityId, metadata, createdAt")
.eq("integration", "company-restore")
.eq("companyId", companyId)
.order("createdAt", { ascending: false });
if (markers.error) return { data: null, error: markers.error };
const runs = (markers.data ?? []).map((m) => {
const meta = (m.metadata ?? {}) as {
restoreRunId?: string;
status?: "running" | "ready" | "failed" | "reverting";
rows?: number;
label?: string | null;
error?: string | null;
startedAt?: string;
progress?: { phase: string; done: number; total: number };
filePath?: string;
includeStorage?: "none" | "all";
reason?: "scope-violations";
violations?: ScopeViolationSummary[];
violationRowsByTable?: RowsByTable[];
};
return {
restoreRunId: meta.restoreRunId ?? m.entityId,
status: meta.status ?? "running",
rows: meta.rows ?? 0,
label: meta.label ?? null,
error: meta.error ?? null,
progress: meta.progress ?? null,
startedAt: meta.startedAt ?? m.createdAt,
// Why it failed + what it was restoring, so the recovery action can
// restart the same restore once the live data is fixed.
reason: meta.reason ?? null,
violations: meta.violations ?? [],
violationRowsByTable: meta.violationRowsByTable ?? [],
filePath: meta.filePath ?? null,
includeStorage: meta.includeStorage ?? null
};
});
return { data: runs, error: null };
}
/**
* The one-per-company marker row for a long-running job, or null when none.
* Shared by the export and demo-template readers below: both are a single row
* keyed on `integration`, whose `metadata` JSON the job owns. `createdAt` comes
* back too, as the fallback for a marker written before its first heartbeat.
*/
async function readIntegrationMarker(
client: SupabaseClient<Database>,
companyId: string,
integration: "company-export" | "company-template"
): Promise<{
data: { meta: Record<string, unknown>; createdAt: string } | null;
error: Error | null;
}> {
const marker = await client
.from("externalIntegrationMapping")
.select("metadata, createdAt")
.eq("integration", integration)
.eq("companyId", companyId)
.maybeSingle();
if (marker.error) return { data: null, error: marker.error };
if (!marker.data) return { data: null, error: null };
return {
data: {
meta: (marker.data.metadata ?? {}) as Record<string, unknown>,
createdAt: marker.data.createdAt
},
error: null
};
}
export type CompanyExportRun = {
status: "running" | "failed";
progress: { phase: string; done: number; total: number } | null;
startedAt: string | null;
error: string | null;
/** "scope-violations" = the closure guard refused; the only failure with a skip recovery. */
reason: "scope-violations" | null;
/** Per-edge breakdown for the details popover. */
violations: ScopeViolationSummary[];
/** DISTINCT rows per table — sum this for anything a user reads. */
violationRowsByTable: RowsByTable[];
/** What the failed run asked for, so the retry can reuse it. */
label: string | null;
includeStorage: "none" | "all" | null;
};
/**
* The current export marker, or null when none. One marker per company
* (integration = 'company-export'), written by the export job: absent = not
* running (the new backup appearing in the list is what signals completion),
* "running" = in flight, "failed" = the last export died and the user hasn't
* dismissed it yet.
*/
export async function getCompanyExportRun(
client: SupabaseClient<Database>,
companyId: string
): Promise<{
data: CompanyExportRun | null;
error: Error | null;
}> {
const marker = await readIntegrationMarker(
client,
companyId,
"company-export"
);
if (marker.error || !marker.data) return { data: null, error: marker.error };
const meta = marker.data.meta as {
status?: "running" | "failed";
startedAt?: string;
progress?: { phase: string; done: number; total: number };
error?: string;
reason?: "scope-violations";
violations?: ScopeViolationSummary[];
violationRowsByTable?: RowsByTable[];
label?: string | null;
includeStorage?: "none" | "all";
};
return {
data: {
status: meta.status ?? "running",
progress: meta.progress ?? null,
startedAt: meta.startedAt ?? marker.data.createdAt,
error: meta.error ?? null,
reason: meta.reason ?? null,
violations: meta.violations ?? [],
violationRowsByTable: meta.violationRowsByTable ?? [],
label: meta.label ?? null,
includeStorage: meta.includeStorage ?? null
},
error: null
};
}
export type CompanyTemplateRun = {
templateRunId: string;
status: "running" | "ready" | "failed" | "reverting";
datasetKey: string | null;
startedAt: string | null;
error: string | null;
/** Phase + done/total while the apply or revert is in flight. */
progress: { phase: string; done: number; total: number } | null;
/** Whether a pre-apply snapshot exists yet — the UI offers a revert retry on a
* stalled run only when there is actually something to put back. */
hasSnapshot: boolean;
reason: "scope-violations" | null;
violations: ScopeViolationSummary[];
violationRowsByTable: RowsByTable[];
};
/**
* The current demo-template marker, or null when none. Written by the
* company-template job: absent = no demo data change is outstanding, "running" =
* in flight, "ready" = applied and waiting on a keep/revert decision,
* "reverting" = the undo is in flight, "failed" = it did not land and the user
* hasn't dismissed it yet.
*
* The metadata shape is typed here rather than imported from `@carbon/jobs` —
* the app must not pull job internals (and Node `Buffer` with them) into its
* bundle.
*/
export async function getCompanyTemplateRun(
client: SupabaseClient<Database>,
companyId: string
): Promise<{
data: CompanyTemplateRun | null;
error: Error | null;
}> {
const marker = await readIntegrationMarker(
client,
companyId,
"company-template"
);
if (marker.error || !marker.data) return { data: null, error: marker.error };
const meta = marker.data.meta as {
templateRunId?: string;
status?: "running" | "ready" | "failed" | "reverting";
datasetKey?: string;
startedAt?: string;
error?: string;
progress?: { phase: string; done: number; total: number } | null;
snapshotPath?: string;
reason?: "scope-violations" | null;
violations?: ScopeViolationSummary[] | null;
violationRowsByTable?: RowsByTable[] | null;
};
// Only whether a snapshot EXISTS is projected, never where — the job owns its
// lifecycle end to end, and the client has no use for the location.
return {
data: {
templateRunId: meta.templateRunId ?? "",
status: meta.status ?? "running",
datasetKey: meta.datasetKey ?? null,
startedAt: meta.startedAt ?? marker.data.createdAt,
error: meta.error ?? null,
progress: meta.progress ?? null,
hasSnapshot: Boolean(meta.snapshotPath),
reason: meta.reason ?? null,
violations: meta.violations ?? [],
violationRowsByTable: meta.violationRowsByTable ?? []
},
error: null
};
}