@rigelbuild/dl-reconcile 0.0.0-stage → 0.0.0

package/LICENSE-APACHE

@@ -0,0 +1,181 @@
+                                   Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or Object
+   form, made available under the License, as indicated by a copyright
+   notice that is included in or attached to the work (an example is
+   provided in the Appendix below).
+
+   "Derivative Works" shall mean any work of authorship, whether in Source or
+   Object form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including the original
+   version of the Work and any modifications or additions to that Work or
+   Derivative Works thereof, that is intentionally submitted to Licensor for
+   inclusion in the Work by the copyright owner or by an individual or Legal
+   Entity authorized to submit on behalf of the copyright owner. For the
+   purposes of this definition, "submitted" means any form of electronic,
+   verbal, or written communication sent to the Licensor or its representatives,
+   including but not limited to communication on electronic mailing lists,
+   source control systems, and issue tracking systems managed by or on behalf
+   of the Licensor to discuss and improve the Work, but excluding communication
+   that is conspicuously marked or otherwise designated in writing by the
+   copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity on
+   behalf of whom a Contribution has been received by Licensor and subsequently
+   incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+   License, each Contributor hereby grants to You a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+   reproduce, prepare Derivative Works of, publicly display, publicly perform,
+   sublicense, and distribute the Work and such Derivative Works in Source or
+   Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+   each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+   no-charge, royalty-free, irrevocable (except as stated in this section) patent
+   license to make, have made, use, offer to sell, sell, import, and otherwise
+   transfer the Work, where such license applies only to those patent claims
+   licensable by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s) with the
+   Work to which such Contribution(s) was submitted. If You institute patent
+   litigation against any entity (including a cross-claim or counterclaim in a
+   lawsuit) alleging that the Work or a Contribution incorporated within the
+   Work constitutes direct or contributory patent infringement, then any patent
+   licenses granted to You under this License for that Work shall terminate as
+   of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+   Derivative Works thereof in any medium, with or without modifications, and
+   in Source or Object form, provided that You meet the following conditions:
+
+   (a) You must give any other recipients of the Work or Derivative Works a
+       copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices stating
+       that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works that You
+       distribute, all copyright, patent, trademark, and attribution notices
+       from the Source form of the Work, excluding those notices that do not
+       pertain to any part of the Derivative Works; and
+
+   (d) If the Work includes a NOTICE text file as part of its distribution,
+       then any Derivative Works that You distribute must include a readable
+       copy of the attribution notices contained within such NOTICE file,
+       excluding those notices that do not pertain to any part of the Derivative
+       Works, in at least one of the following places: within a NOTICE text file
+       distributed as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or, within a
+       display generated by the Work, if and wherever such third-party notices
+       normally appear. The contents of the NOTICE file are for informational
+       purposes only and do not modify the License. You may add Your own
+       attribution notices alongside the NOTICE text, provided they cannot be
+       construed as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and may
+   provide additional or different license terms and conditions for use,
+   reproduction, and distribution of the Work otherwise in compliance with
+   this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+   Contribution intentionally submitted for inclusion in the Work by You to the
+   Licensor shall be under the terms and conditions of this License, without
+   any additional terms or conditions. Notwithstanding the above, nothing herein
+   shall supersede or modify the terms of any separate license agreement you may
+   have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor, except as
+   required for reasonable and customary use in describing the origin of the
+   Work and reproducing the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+   writing, Licensor provides the Work (and each Contributor provides
+   Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied, including, without limitation, warranties
+   or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any risks
+   associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+   tort (including negligence), contract, or otherwise, unless required by
+   applicable law or agreed to in writing, shall any Contributor be liable to
+   You for damages, including any direct, indirect, special, incidental, or
+   consequential damages of any character arising as a result of this License
+   or out of the use or inability to use the Work, even if such Contributor has
+   been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+   or Derivative Works thereof, You may choose to offer, and charge a fee for,
+   acceptance of support, warranty, indemnity, or other liability obligations
+   or rights consistent with this License. However, in accepting such
+   obligations, You may act only on Your own behalf and on Your sole
+   responsibility, not on behalf of any other Contributor, and only if You agree
+   to indemnify, defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason of your
+   accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following boilerplate
+   notice, with fields enclosed by brackets "[]" replaced with your own
+   identifying information. (Don't include the brackets!) The text should be
+   enclosed in the appropriate comment syntax for the file format. A file or
+   class name and purpose should be included on the same printed page as the
+   copyright notice for easier identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License"); you may not
+   use this file except in compliance with the License. You may obtain a copy of
+   the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+   License for the specific language governing permissions and limitations
+   under the License.

package/LICENSE-MIT

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Rigel AI Software Inc.
+
+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

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @rigelbuild/dl-reconcile
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reports the decision IDs present in the configured layout to the shared counter. The response lists updated and inserted claims, stale claims, and duplicate IDs.
+
+## Usage
+
+```sh
+bun packages/dl-reconcile/index.ts --config ./ledger.config.json
+bun packages/dl-reconcile/index.ts --config ./ledger.config.json --check
+bun packages/dl-reconcile/index.ts --config ./ledger.config.json --stale-exit
+```
+
+The command discovers files according to the configured design layout, parses every decision, and refuses to submit an empty frontier. `--check` validates files and reports the number found without contacting the counter. `--stale-exit` exits 1 when stale claims remain.
+
+## Credentials
+
+`DL_CLAIM_TOKEN` supplies the bearer token. A non-empty trimmed `DL_CLAIM_TOKEN_FILE` value takes precedence. The counter URL is read from `counter.url` in the config; there is no environment override. `GATE_ROOT` optionally sets the repository root; otherwise the Git toplevel is used.
+
+## Exit codes
+
+- `0`: reconciliation succeeded, with no stale claims when `--stale-exit` is set.
+- `1`: counter request or service failure, or stale claims with `--stale-exit`.
+- `2`: usage, configuration, or read error.

package/index.ts

@@ -0,0 +1,355 @@
+#!/usr/bin/env bun
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import type { LedgerConfig } from "@rigelbuild/design-ledger-gate";
+import {
+	classifyDesignPath,
+	loadLedgerConfig,
+	readDlClaimToken,
+	validateDlClaimToken,
+} from "@rigelbuild/design-ledger-gate";
+import { parseDecisionFile } from "@rigelbuild/design-ledger-gate/decision-files.ts";
+
+export interface LandedDecision {
+	id: string;
+	surface: string;
+	ref: string;
+}
+
+export interface ReconcileRequest {
+	repo: string;
+	landed: LandedDecision[];
+}
+
+export interface StaleClaim {
+	id: string;
+	surface: string;
+	ref: string;
+	lane: string;
+	date: string;
+}
+
+export interface DuplicateClaim {
+	id: string;
+	surfaces: string[];
+}
+
+export interface ReconcileResponse {
+	updated: number;
+	inserted: number;
+	stale: StaleClaim[];
+	duplicates: DuplicateClaim[];
+}
+
+export function assertReconcilableLedgers(
+	config: LedgerConfig,
+	files: ReadonlyMap<string, string>,
+): ReconcileRequest {
+	const surfaces = config.surfaces;
+	if (surfaces === undefined || surfaces.length === 0)
+		throw new Error("config.surfaces must contain at least one surface");
+	if (config.surfaceDepth === 0 && surfaces.length !== 1)
+		throw new Error(
+			"config.surfaces must contain exactly one surface at depth 0",
+		);
+	const decisions = [...files]
+		.filter(([path]) => classifyDesignPath(path, config) === "decision")
+		.sort(([left], [right]) => left.localeCompare(right));
+	if (decisions.length === 0)
+		throw new Error(
+			"decision file list is empty; refusing to post an empty frontier",
+		);
+	const landed: Array<{ path: string; decision: LandedDecision }> = [];
+	for (const [path, text] of decisions) {
+		const parsed = parseDecisionFile(path, text);
+		if (!parsed.ok)
+			throw new Error(
+				`malformed decision file ${path}: line ${parsed.error.line}: ${parsed.error.reason}`,
+			);
+		const relative = path.slice(`${config.designsRoot}/`.length).split("/");
+		const surface = config.surfaceDepth === 0 ? surfaces[0] : relative[0];
+		if (surface === undefined)
+			throw new Error(`cannot determine surface for decision file ${path}`);
+		if (!surfaces.includes(surface))
+			throw new Error(`unknown design surface ${surface} in ${path}`);
+		landed.push({
+			path,
+			decision: { id: basename(path, ".md"), surface, ref: "none" },
+		});
+	}
+	landed.sort(
+		(left, right) =>
+			Number(left.decision.id.slice(3)) - Number(right.decision.id.slice(3)) ||
+			left.path.localeCompare(right.path),
+	);
+	return {
+		repo: config.counter.partition,
+		landed: landed.map(({ decision }) => decision),
+	};
+}
+
+export type FetchFn = (
+	input: string | URL | Request,
+	init?: RequestInit,
+) => Promise<Response>;
+
+export interface ReconcileDeps {
+	fetchFn?: FetchFn;
+	timeoutMs?: number;
+	timeoutSignal?: (timeoutMs: number) => AbortSignal;
+}
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function endpoint(config: LedgerConfig): string {
+	return `${config.counter.url.replace(/\/+$/, "")}/reconcile`;
+}
+
+export async function reconcile(
+	body: ReconcileRequest,
+	config: LedgerConfig,
+	token: string,
+	deps: ReconcileDeps = {},
+): Promise<ReconcileResponse> {
+	const trimmedToken = validateDlClaimToken(token);
+	if (body.landed.length === 0)
+		throw new Error("refusing to reconcile an empty landed frontier");
+	const timeoutMs =
+		deps.timeoutMs !== undefined && deps.timeoutMs > 0
+			? deps.timeoutMs
+			: 30_000;
+	let response: Response;
+	try {
+		response = await (deps.fetchFn ?? fetch)(endpoint(config), {
+			method: "POST",
+			redirect: "error",
+			headers: {
+				Authorization: `Bearer ${trimmedToken}`,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify(body),
+			signal: (deps.timeoutSignal ?? AbortSignal.timeout)(timeoutMs),
+		});
+	} catch (error) {
+		const name = error instanceof Error ? error.name : "UnknownError";
+		throw new Error(`request to ${endpoint(config)} failed (${name})`);
+	}
+	if (!response.ok)
+		throw new Error(`reconciliation failed with HTTP ${response.status}`);
+	const payload: unknown = await response.json();
+	if (!isRecord(payload)) throw new Error("invalid reconciliation response");
+	if (
+		typeof payload.updated !== "number" ||
+		typeof payload.inserted !== "number" ||
+		!Array.isArray(payload.stale) ||
+		!Array.isArray(payload.duplicates)
+	)
+		throw new Error("invalid reconciliation response");
+	const staleItems: unknown[] = payload.stale;
+	const duplicateItems: unknown[] = payload.duplicates;
+	const stale: StaleClaim[] = [];
+	for (const item of staleItems) {
+		if (
+			!isRecord(item) ||
+			typeof item.id !== "string" ||
+			typeof item.surface !== "string" ||
+			typeof item.ref !== "string" ||
+			typeof item.lane !== "string" ||
+			typeof item.date !== "string"
+		)
+			throw new Error("invalid reconciliation response");
+		stale.push({
+			id: item.id,
+			surface: item.surface,
+			ref: item.ref,
+			lane: item.lane,
+			date: item.date,
+		});
+	}
+	const duplicates: DuplicateClaim[] = [];
+	for (const item of duplicateItems) {
+		if (
+			!isRecord(item) ||
+			typeof item.id !== "string" ||
+			!Array.isArray(item.surfaces) ||
+			!item.surfaces.every((surface: unknown) => typeof surface === "string")
+		)
+			throw new Error("invalid reconciliation response");
+		const surfaces: string[] = item.surfaces;
+		duplicates.push({ id: item.id, surfaces });
+	}
+	return {
+		updated: payload.updated,
+		inserted: payload.inserted,
+		stale,
+		duplicates,
+	};
+}
+
+export function formatReconcileOutput(response: ReconcileResponse): string {
+	const lines = [
+		`updated: ${response.updated}  inserted: ${response.inserted}`,
+	];
+	lines.push(`stale: ${response.stale.length}`);
+	for (const entry of response.stale)
+		lines.push(
+			`  ${entry.id} ${entry.surface} ${entry.lane} ${entry.ref} ${entry.date}`,
+		);
+	lines.push(`duplicates: ${response.duplicates.length}`);
+	for (const entry of response.duplicates)
+		lines.push(`  ${entry.id} ${entry.surfaces.join(" ")}`);
+	return lines.join("\n");
+}
+
+interface CliOptions {
+	configPath: string;
+	check: boolean;
+	staleExit: boolean;
+}
+
+export interface RunDeps {
+	root?: string;
+	token?: string;
+	fetchFn?: FetchFn;
+	log?: (message: string) => void;
+	err?: (message: string) => void;
+}
+
+function parseCliArgs(args: readonly string[]): CliOptions {
+	let configPath: string | undefined;
+	let check = false;
+	let staleExit = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index] ?? "";
+		if (arg === "--check") {
+			if (check) throw new Error("duplicate --check flag");
+			check = true;
+		} else if (arg === "--stale-exit") {
+			if (staleExit) throw new Error("duplicate --stale-exit flag");
+			staleExit = true;
+		} else if (arg === "--config") {
+			if (configPath !== undefined) throw new Error("duplicate --config flag");
+			configPath = args[index + 1];
+			if (configPath === undefined || configPath.startsWith("--"))
+				throw new Error("--config requires a path");
+			index += 1;
+		} else if (arg.startsWith("--config=")) {
+			if (configPath !== undefined) throw new Error("duplicate --config flag");
+			configPath = arg.slice("--config=".length);
+			if (configPath.length === 0) throw new Error("--config requires a path");
+		} else {
+			throw new Error(`unknown argument: ${arg}`);
+		}
+	}
+	if (configPath === undefined) throw new Error("--config is required");
+	return { configPath, check, staleExit };
+}
+
+function repositoryRoot(): string {
+	if (process.env.GATE_ROOT !== undefined)
+		return resolve(process.env.GATE_ROOT);
+	const result = Bun.spawnSync({
+		cmd: ["git", "rev-parse", "--show-toplevel"],
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	if (result.exitCode !== 0)
+		throw new Error(
+			new TextDecoder().decode(result.stderr).trim() || "cannot find git root",
+		);
+	return new TextDecoder().decode(result.stdout).trim();
+}
+
+async function discoverDecisionFiles(
+	root: string,
+	config: LedgerConfig,
+): Promise<Map<string, string>> {
+	const files = new Map<string, string>();
+	const glob = new Bun.Glob(`${config.designsRoot}/**`);
+	for await (const path of glob.scan({ cwd: root, onlyFiles: true })) {
+		const normalizedPath = path.replaceAll("\\", "/");
+		const kind = classifyDesignPath(normalizedPath, config);
+		if (kind === "misplaced")
+			throw new Error(`misplaced decision path ${normalizedPath}`);
+		if (kind !== "decision") continue;
+		files.set(
+			normalizedPath,
+			await readFile(resolve(root, normalizedPath), "utf8"),
+		);
+	}
+	return files;
+}
+
+export async function runOnce(
+	args: readonly string[],
+	deps: RunDeps = {},
+): Promise<number> {
+	const log = deps.log ?? console.log;
+	const err = deps.err ?? console.error;
+	if (args.length === 1 && args[0] === "--help") {
+		log("Usage: dl-reconcile --config <path> [--check] [--stale-exit]");
+		return 0;
+	}
+	let options: CliOptions;
+	try {
+		options = parseCliArgs(args);
+	} catch (error) {
+		err(
+			`dl-reconcile: ${error instanceof Error ? error.message : String(error)}`,
+		);
+		return 2;
+	}
+	let config: LedgerConfig;
+	let body: ReconcileRequest;
+	try {
+		config = loadLedgerConfig(options.configPath);
+		const root =
+			deps.root === undefined ? repositoryRoot() : resolve(deps.root);
+		body = assertReconcilableLedgers(
+			config,
+			await discoverDecisionFiles(root, config),
+		);
+	} catch (error) {
+		err(
+			`dl-reconcile: ${error instanceof Error ? error.message : String(error)}`,
+		);
+		return 2;
+	}
+	if (options.check) {
+		log(
+			`Design ledger parse check passed (${body.landed.length} decision files).`,
+		);
+		return 0;
+	}
+	let token: string;
+	try {
+		token = validateDlClaimToken(deps.token ?? (await readDlClaimToken()));
+	} catch (error) {
+		const message =
+			error instanceof Error && error.message === "DL_CLAIM_TOKEN is required"
+				? error.message
+				: "DL_CLAIM_TOKEN must contain printable ASCII characters without whitespace";
+		err(`dl-reconcile: ${message}`);
+		return 2;
+	}
+	try {
+		const response = await reconcile(body, config, token, {
+			...(deps.fetchFn === undefined ? {} : { fetchFn: deps.fetchFn }),
+		});
+		log(formatReconcileOutput(response));
+		return options.staleExit && response.stale.length > 0 ? 1 : 0;
+	} catch (error) {
+		if (
+			error instanceof Error &&
+			error.message.startsWith("reconciliation failed with HTTP ")
+		) {
+			err(`dl-reconcile: ${error.message}`);
+		} else {
+			const name = error instanceof Error ? error.name : "UnknownError";
+			err(`dl-reconcile: request to ${endpoint(config)} failed (${name})`);
+		}
+		return 1;
+	}
+}
+if (import.meta.main) process.exitCode = await runOnce(process.argv.slice(2));

package/package.json

@@ -1,6 +1,31 @@
 {
-  "name": "@rigelbuild/dl-reconcile",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@rigelbuild/dl-reconcile",
+	"version": "0.0.0",
+	"type": "module",
+	"license": "MIT OR Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/RigelBuild/meissa.git",
+		"directory": "packages/dl-reconcile"
+	},
+	"bin": {
+		"dl-reconcile": "./index.ts"
+	},
+	"files": [
+		"package.json",
+		"index.ts",
+		"README.md",
+		"LICENSE-MIT",
+		"LICENSE-APACHE"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@rigelbuild/design-ledger-gate": "0.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "1.4.0",
+		"typescript": "6.0.3"
+	}
+}